ZigBee Cluster Library (for ZigBee 3.0) User Guide - NXP

1 ZigBee Cluster Library (for ZigBee )User GuideJN-UG-3115 Revision September 2018 ZigBee Cluster Library (for ZigBee )User Guide 2 NXP Semiconductors 2018JN-UG-3115 ZigBee Cluster Library (for ZigBee )User GuideJN-UG-3115 NXP Semiconductors 20183 ContentsContents 3 Preface 37 Organisation 37 Conventions 39 Acronyms and Abbreviations 40 Related Documents 40 Support Resources 40 Trademarks 40 Chip Compatibility 41 Part I: Fundamentals1. ZigBee Cluster Library (ZCL) ZCL Member Clusters General Measurement and Sensing Lighting Heating, Ventilation and Air-Conditioning (HVAC) Closures Security and Safety Smart Energy Commissioning Appliances Over-The-Air (OTA) Upgrade General ZCL Resources ZCL Compile-time Options 542. ZCL Fundamentals and Features Initialising the ZCL Shared Device Structures Accessing Attributes Attribute Access Permissions Reading Attributes Reading a Set of Attributes of a Remote Cluster Reading an Attribute of a Local Cluster Writing Attributes Writing to Attributes of a Remote Cluster 63 Contents 4 NXP Semiconductors 2018JN-UG-3115 Writing an Attribute Value to a Local Cluster Attribute Discovery Attribute Reporting Global Attributes Default Responses Handling Commands for Unsupported Clusters Handling Commands from Other Manufacturers Bound Transmission Management Command Discovery Discovering Command Sets Compile-time Options 743.

2 Event Handling Event Structure Processing Events Events 774. Error Handling Last Stack Error Error/Command Status on Receiving Command 83 Part II: Common Resources5. ZCL Functions General Functions 87eZCL_Initialise 88eZCL_Register 89vZCL_EventHandler 90eZCL_Update100mS 91vZCL_DisableAPSACK 92eZCL_GetLastZpsError 93vZCL_RegisterHandleGeneralCmdCallBack 94vZCL_RegisterCheckForManufCodeCallBack Attribute Access Functions 96eZCL_SendReadAttributesRequest 97eZCL_SendWriteAttributesRequest 99eZCL_SendWriteAttributesNoResponseRequ est 101eZCL_SendWriteAttributesUndividedRequ est 103eZCL_SendDiscoverAttributesRequest 105eZCL_SendDiscoverAttributesExtendedRe quest 107eZCL_SendConfigureReportingCommand 109 ZigBee Cluster Library (for ZigBee )User GuideJN-UG-3115 NXP Semiconductors 20185eZCL_SendReadReportingConfiguration Command 111eZCL_ReportAllAttributes 113eZCL_ReportAttribute 114eZCL_CreateLocalReport 115eZCL_SetReportableFlag 116vZCL_SetDefaultReporting 117eZCL_HandleReadAttributesResponse 118eZCL_ReadLocalAttributeValue 119eZCL_WriteLocalAttributeValue 121eZCL_OverrideClusterControlFlags 123eZCL_SetSupportedSecurity Command Discovery Functions 125eZCL_SendDiscoverCommandReceivedReque st 126eZCL_SendDiscoverCommandGeneratedRequ est 1286.

3 ZCL Structures General Structures tsZCL_EndPointDefinition tsZCL_ClusterDefinition tsZCL_AttributeDefinition tsZCL_Address tsZCL_AttributeReportingConfigurationRec ord tsZCL_AttributeReportingConfigurationRes ponse tsZCL_AttributeReadReportingConfiguratio nRecord tsZCL_IndividualAttributesResponse tsZCL_DefaultResponse tsZCL_AttributeDiscoveryResponse tsZCL_AttributeDiscoveryExtendedResponse tsZCL_ReportAttributeMirror tsZCL_OctetString tsZCL_CharacterString tsZCL_ClusterCustomMessage tsZCL_ClusterInstance tsZCL_CommandDiscoveryIndividualResponse tsZCL_CommandDiscoveryResponse tsZCL_CommandDefinition tsZCL_SceneExtensionTable tsZCL_WriteAttributeRecord Event Structure (tsZCL_CallBackEvent) 1467. Enumerations and Status Codes General Enumerations Addressing Modes (teZCL_AddressMode) Broadcast Modes (ZPS_teAplAfBroadcastMode) Attribute Types (teZCL_ZCLA ttributeType) 152 Contents 6 NXP Semiconductors 2018JN-UG-3115 Command Status (teZCL_CommandStatus) Report Attribute Status (teZCL_ReportAttributeStatus) Security Level (teZCL_ZCLSendSecurity) General Return Codes (ZCL Status) ZCL Event Enumerations 161 Part III: General Clusters8.

4 Basic Cluster Overview Basic Cluster Structure and Attributes Mandatory Attribute Settings Functions 173eCLD_BasicCreateBasic 174eCLD_BasicCommandResetToFactoryDefaul tsSend Enumerations teCLD_BAS_ClusterID teCLD_BAS_PowerSource teCLD_BAS_GenericDeviceClass eCLD_BAS_GenericDeviceType teCLD_BAS_PhysicalEnvironment Compile-Time Options 1839. Power Configuration Cluster Overview Power Configuration Cluster Structure and Attributes Attributes for Default Reporting Functions 199eCLD_PowerConfigurationCreatePowerCon figuration Enumerations and Defines teCLD_PWRCFG_AttributeId teCLD_PWRCFG_BatterySize Defines for Voltage Alarms Compile-Time Options 20410. Device Temperature Configuration Cluster Overview Cluster Structure and Attributes Functions 212eCLD_DeviceTemperatureConfigurationCr eateDeviceTemperatureConfiguration 213 ZigBee Cluster Library (for ZigBee )User GuideJN-UG-3115 NXP Semiconductors Enumerations and Defines teCLD_DEVTEMPCFG_AttributeId Defines for Device Temperature Alarms Compile-Time Options 21511.

5 Identify Cluster Overview Identify Cluster Structure and Attribute Initialisation Sending Commands Starting and Stopping Identification Mode Requesting Identification Effects Inquiring about Identification Mode Using EZ-mode Commissioning Features Sleeping Devices in Identification Mode Functions 221eCLD_IdentifyCreateIdentify 222eCLD_IdentifyCommandIdentifyRequestSe nd 224eCLD_IdentifyCommandTriggerEffectSend 226eCLD_IdentifyCommandIdentifyQueryRequ estSend 228eCLD_IdentifyEZModeInvokeCommandSend 230eCLD_IdentifyUpdateCommissionStateCom mandSend Structures Custom Data Structure Custom Command Payloads Custom Command Responses EZ-mode Commissioning Command Payloads Enumerations teCLD_Identify_ClusterID Compile-Time Options 23612. Groups Cluster Overview Groups Cluster Structure and Attributes Initialisation Sending Commands Adding Endpoints to Groups Removing Endpoints from Groups Obtaining Information about Groups Functions 242eCLD_GroupsCreateGroups 243eCLD_GroupsAdd 245 Contents 8 NXP Semiconductors 2018JN-UG-3115 246eCLD_GroupsCommandViewGroupRequestSen d 248eCLD_GroupsCommandGetGroupMembershipR equestSend 250eCLD_GroupsCommandRemoveGroupRequestS end 252eCLD_GroupsCommandRemoveAllGroupsRequ estSend 254eCLD_GroupsCommandAddGroupIfIdentifyi ngRequestSend Structures Custom Data Structure Group Table Entry Custom Command Payloads Custom Command Responses Enumerations teCLD_Groups_ClusterID Compile-Time Options 26213.

6 Scenes Cluster Overview Scenes Cluster Structure and Attributes Initialisation Sending Remote Commands Creating a Scene Copying a Scene Applying a Scene Deleting a Scene Obtaining Information about Scenes Issuing Local Commands Creating a Scene Applying a Scene Functions 269eCLD_ScenesCreateScenes 270eCLD_ScenesAdd 272eCLD_ScenesStore 273eCLD_ScenesRecall 274eCLD_ScenesCommandAddSceneRequestSend 275eCLD_ScenesCommandViewSceneRequestSen d 277eCLD_ScenesCommandRemoveSceneRequestS end 279eCLD_ScenesCommandRemoveAllScenesRequ estSend 281eCLD_ScenesCommandStoreSceneRequestSe nd 283eCLD_ScenesCommandRecallSceneRequestS end 285eCLD_ScenesCommandGetSceneMembershipR equestSend 287eCLD_ScenesCommandEnhancedAddSceneReq uestSend 289eCLD_ScenesCommandEnhancedViewSceneRe questSend 291eCLD_ScenesCommandCopySceneSceneReque stSend Structures 295 ZigBee Cluster Library (for ZigBee )User GuideJN-UG-3115 NXP Semiconductors Custom Data Structure Custom Command Payloads Custom Command Responses Scenes Table Entry Enumerations teCLD_Scenes_ClusterID Compile-Time Options 30414.

7 On/Off Cluster Overview On/Off Cluster Structure and Attribute for Default Reporting Initialisation Sending Commands Switching On and Off Timeout on the On Command On/Off with Transition Effect Switching Off Lights with Effect Switching On Timed Lights Saving Light Settings Functions 313eCLD_OnOffCreateOnOff 314eCLD_OnOffCommandSend 316eCLD_OnOffCommandOffWithEffectSend 318eCLD_OnOffCommandOnWithTimedOffSend Structures Custom Data Structure Custom Command Payloads Enumerations teCLD_OnOff_ClusterID teCLD_OOSC_SwitchType (On/Off Switch Types) teCLD_OOSC_SwitchAction (On/Off Switch Actions) Compile-Time Options 32515. On/Off Switch Configuration Cluster Overview On/Off Switch Config Cluster Structure and Attribute Initialisation Functions 329eCLD_OOSCC reateOnOffSwitchConfig Enumerations teCLD_OOSC_ClusterID 332 Contents 10 NXP Semiconductors 2018JN-UG-3115 teCLD_OOSC_SwitchType teCLD_OOSC_SwitchAction Compile-Time Options 33316.

8 Level Control Cluster Overview Level Control Cluster Structure and Attributes Attributes for Default Reporting Initialisation Sending Remote Commands Changing Level Stopping a Level Change Issuing Local Commands Setting Level Obtaining Level Functions 341eCLD_LevelControlCreateLevelControl 342eCLD_LevelControlSetLevel 344eCLD_LevelControlGetLevel 345eCLD_LevelControlCommandMoveToLevelCo mmandSend 346eCLD_LevelControlCommandMoveCommandSe nd 348eCLD_LevelControlCommandStepCommandSe nd 350eCLD_LevelControlCommandStopCommandSe nd Structures Level Control Transition Structure Custom Data Structure Custom Command Payloads Move To Level Command Payload Move Command Payload Step Command Payload Stop Command Payload Enumerations teCLD_LevelControl_ClusterID teCLD_LevelControl_Transition teCLD_LevelControl_MoveMode Compile-Time Options 35917. Alarms Cluster Overview Alarms Cluster Structure and Attributes Initialisation Alarm Operations Raising an Alarm 363 ZigBee Cluster Library (for ZigBee )User GuideJN-UG-3115 NXP Semiconductors Resetting Alarms (from Client) Alarms Events Functions 365eCLD_AlarmsCreateAlarms 366eCLD_AlarmsCommandResetAlarmCommandSe nd 368eCLD_AlarmsCommandResetAllAlarmsComma ndSend 370eCLD_AlarmsCommandGetAlarmCommandSend 372eCLD_AlarmsCommandResetAlarmLogComman dSend 374eCLD_AlarmsResetAlarmLog 376eCLD_AlarmsAddAlarmToLog 377eCLD_AlarmsGetAlarmFromLog 378eCLD_AlarmsSignalAlarm Structures Event Callback Message Structure Custom Data Structure Custom Command Payloads Reset Alarm Command Payload Alarm Notification Payload Custom Response Payloads Get Alarm Response Payload Alarms Table Entry Enumerations teCLD_Alarms_AttributeID Compile-Time Options 38518.

9 Time Cluster and ZCL Time Overview Time Cluster Structure and Attributes Attribute Settings Mandatory Attributes Optional Attributes Maintaining ZCL Time Updating ZCL Time Following Sleep ZCL Time Synchronisation Time-Synchronisation of Devices Initialising and Maintaining Master Time Initial Synchronisation of Devices Re-synchronisation of Devices Time Event Functions 399eCLD_TimeCreateTime 400vZCL_SetUTCTime 402u32 ZCL_GetUTCTime 403bZCL_GetTimeHasBeenSynchronised 404 Contents 12 NXP Semiconductors 2018JN-UG-3115 Return Codes Enumerations teCLD_TM_AttributeID Compile-Time Options 40619. Input and Output Clusters Analogue Input (Basic) Overview Analogue Input (Basic) Structure and Attributes Attributes for Default Reporting Functions 413eCLD_AnalogInputBasicCreateAnalogInpu tBasic Enumerations teCLD_AnalogInputBasicCluster_AttrID teCLD_AnalogInputBasic_Reliability Compile-Time Options Analogue Output (Basic) Overview Analogue Output (Basic) Structure and Attributes Attributes for Default Reporting Functions 422eCLD_AnalogOutputBasicCreateAnalogOut putBasic Enumerations teCLD_AnalogOutputBasicCluster_AttrID teCLD_AnalogOutputBasic_Reliability Compile-Time Options Binary Input (Basic) Cluster Overview Binary Input (Basic)

10 Structure and Attributes Attributes for Default Reporting Functions 431eCLD_BinaryInputBasicCreateBinaryInpu tBasic Enumerations teCLD_BinaryInputBasicCluster_AttrID teCLD_BinaryInputBasic_Polarity teCLD_BinaryInputBasic_Reliability Compile-Time Options Binary Output (Basic) Overview Binary Output (Basic) Structure and Attributes Attributes for Default Reporting Functions 441eCLD_BinaryOutputBasicCreateBinaryOut putBasic Enumerations teCLD_BinaryOutputBasicCluster_AttrID 444 ZigBee Cluster Library (for ZigBee )User GuideJN-UG-3115 NXP Semiconductors teCLD_BinaryOutputBasic_Polarity teCLD_BinaryOutputBasic_Reliability Compile-Time Options Multistate Input (Basic) Overview Multistate Input (Basic) Structure and Attributes Attributes for Default Reporting Functions 449eCLD_MultistateInputBasicCreateMultis tateInputBasic Enumerations teCLD_MultistateInputBasicCluster_AttrID teCLD_MultistateInputBasic_Reliability Compile-Time Options Multistate Output (Basic) Overview Multistate Output (Basic) Structure and Attributes Attributes for Default Reporting Functions 457eCLD_MultistateOutputBasicCreateMulti stateOutputBasic Enumerations teCLD_MultistateOutputBasicCluster_AttrI D teCLD_MultistateOutputBasic_Reliability Compile-Time Options 46120.