ZigBee Cluster Library User Guide - NXP · PDF fileZigBee Cluster Library User Guide. ZigBee...

ZigBee Cluster LibraryUser Guide
JN-UG-3077Revision 2.1
6 February 2015

2 NXP Laboratories UK 2015 JN-UG-3077 v2.1

Contents
About this Manual 23Organisation 23Conventions 25Acronyms and Abbreviations 25Related Documents 26Support Resources 26Trademarks 26Chip Compatibility 26
Part I: General and Development Information
1. ZigBee Cluster Library (ZCL) 291.1 Member Clusters 301.2 Compile-time Options 34
2. ZCL Fundamentals and Features 352.1 Shared Device Structures 352.2 Accessing Attributes 37
2.2.1 Reading Attributes 372.2.1.1 Reading a Set of Attributes of a Remote Cluster 372.2.1.2 Reading All Attributes of a Remote Cluster 392.2.1.3 Reading an Attribute of a Local Cluster 40
2.2.2 Writing Attributes 402.2.2.1 Writing to Attributes of a Remote Cluster 402.2.2.2 Writing an Attribute Value to a Local Cluster 43
2.2.3 Attribute Discovery 442.2.4 Attribute Reporting 45
2.3 Default Responses 462.4 Bound Transmission Management 462.5 Command Discovery 48
2.5.1 Discovering Command Sets 482.5.2 Compile-time Options 49
3. Event Handling 513.1 Event Structure 513.2 Processing Events 523.3 Events 53
JN-UG-3077 v2.1 NXP Laboratories UK 2015 3

Contents
4. Error Handling 594.1 Last Stack Error 594.2 Error/Command Status on Receiving Command 59
Part II: Clusters and Modules
5. Basic Cluster 635.1 Overview 635.2 Basic Cluster Structure and Attributes 645.3 Mandatory Attribute Settings 685.4 Functions 68
eCLD_BasicCreateBasic 695.5 Enumerations 71
5.5.1 teCLD_BAS_ClusterID 715.5.2 teCLD_BAS_PowerSource 715.5.3 teCLD_BAS_ApplicationProfileType 73
5.6 Compile-Time Options 73
6. Power Configuration Cluster 756.1 Overview 756.2 Power Configuration Cluster Structure and Attributes 766.3 Functions 86
eCLD_PowerConfigurationCreatePowerConfiguration 876.4 Enumerations and Defines 89
6.4.1 teCLD_PWRCFG_AttributeId 896.4.2 teCLD_PWRCFG_BatterySize 916.4.3 Defines for Voltage Alarms 91
7. Identify Cluster 977.1 Overview 977.2 Identify Cluster Structure and Attribute 987.3 Initialisation 997.4 Sending Commands 99
7.4.1 Starting and Stopping Identification Mode 997.4.2 Requesting Identification Effects (ZLL Only) 997.4.3 Inquiring about Identification Mode 1007.4.4 Using EZ-mode Commissioning Features (HA only) 100
7.5 Sleeping Devices in Identification Mode 101

7.6 Functions 101eCLD_IdentifyCreateIdentify 102eCLD_IdentifyCommandIdentifyRequestSend 104eCLD_IdentifyCommandTriggerEffectSend 106eCLD_IdentifyCommandIdentifyQueryRequestSend 108eCLD_IdentifyEZModeInvokeCommandSend 110eCLD_IdentifyUpdateCommissionStateCommandSend 112
7.7 Structures 1147.7.1 Custom Data Structure 1147.7.2 Custom Command Payloads 1147.7.3 Custom Command Responses 1147.7.4 EZ-mode Commissioning Command Payloads 115
7.8 Enumerations 1167.8.1 teCLD_Identify_ClusterID 116
8. Groups Cluster 1198.1 Overview 1198.2 Groups Cluster Structure and Attribute 1198.3 Initialisation 1208.4 Sending Commands 120
8.4.1 Adding Endpoints to Groups 1208.4.2 Removing Endpoints from Groups 1208.4.3 Obtaining Information about Groups 121
8.5 Functions 121eCLD_GroupsCreateGroups 122eCLD_GroupsAdd 124eCLD_GroupsCommandAddGroupRequestSend 125eCLD_GroupsCommandViewGroupRequestSend 127eCLD_GroupsCommandGetGroupMembershipRequestSend 129eCLD_GroupsCommandRemoveGroupRequestSend 131eCLD_GroupsCommandRemoveAllGroupsRequestSend 133eCLD_GroupsCommandAddGroupIfIdentifyingRequestSend 135
8.6 Structures 1378.6.1 Custom Data Structure 1378.6.2 Group Table Entry 1378.6.3 Custom Command Payloads 1388.6.4 Custom Command Responses 139
8.7 Enumerations 1408.7.1 teCLD_Groups_ClusterID 140

Contents
9. Scenes Cluster 1439.1 Overview 1439.2 Scenes Cluster Structure and Attributes 1449.3 Initialisation 1449.4 Sending Remote Commands 145
9.4.1 Creating a Scene 1459.4.2 Copying a Scene (ZLL Only) 1469.4.3 Applying a Scene 1469.4.4 Deleting a Scene 1469.4.5 Obtaining Information about Scenes 147
9.5 Issuing Local Commands 1479.5.1 Creating a Scene 1479.5.2 Applying a Scene 147
9.6 Functions 148eCLD_ScenesCreateScenes 149eCLD_ScenesAdd 151eCLD_ScenesStore 152eCLD_ScenesRecall 153eCLD_ScenesCommandAddSceneRequestSend 154eCLD_ScenesCommandViewSceneRequestSend 156eCLD_ScenesCommandRemoveSceneRequestSend 158eCLD_ScenesCommandRemoveAllScenesRequestSend 160eCLD_ScenesCommandStoreSceneRequestSend 162eCLD_ScenesCommandRecallSceneRequestSend 164eCLD_ScenesCommandGetSceneMembershipRequestSend 166eCLD_ScenesCommandEnhancedAddSceneRequestSend 168eCLD_ScenesCommandEnhancedViewSceneRequestSend 170eCLD_ScenesCommandCopySceneSceneRequestSend 172
9.7 Structures 1749.7.1 Custom Data Structure 1749.7.2 Custom Command Payloads 1749.7.3 Custom Command Responses 178
9.8 Enumerations 1829.8.1 teCLD_Scenes_ClusterID 182
10. On/Off Cluster 18510.1 Overview 18510.2 On/Off Cluster Structure and Attribute 18610.3 Initialisation 188

10.4 Sending Commands 18810.4.1 Switching On and Off 188
10.4.1.1 Timeout on the On Command 18810.4.1.2 Profile-specific Features 189
10.4.2 Switching Off Lights with Effect (ZLL Only) 18910.4.3 Switching On Timed Lights (ZLL Only) 190
10.5 Saving Light Settings (ZLL Only) 19010.6 Functions 191
eCLD_OnOffCreateOnOff 192eCLD_OnOffCommandSend 194eCLD_OnOffCommandOffWithEffectSend 196eCLD_OnOffCommandOnWithTimedOffSend 198
10.7 Structures 20010.7.1 Custom Data Structure 20010.7.2 Custom Command Payloads 200
10.8 Enumerations 20210.8.1 teCLD_OnOff_ClusterID 20210.8.2 teCLD_OOSC_SwitchType (On/Off Switch Types) 20210.8.3 teCLD_OOSC_SwitchAction (On/Off Switch Actions) 202
11. On/Off Switch Configuration Cluster 20511.1 Overview 20511.2 On/Off Switch Config Cluster Structure and Attribute 20611.3 Initialisation 20611.4 Functions 206
eCLD_OOSCCreateOnOffSwitchConfig 20711.5 Enumerations 209
11.5.1 teCLD_OOSC_ClusterID 20911.6 Compile-Time Options 209
12. Level Control Cluster 21112.1 Overview 21112.2 Level Control Cluster Structure and Attributes 21212.3 Initialisation 21412.4 Sending Remote Commands 214
12.4.1 Changing Level 21412.4.2 Stopping a Level Change 215
12.5 Issuing Local Commands 21612.5.1 Setting Level 21612.5.2 Obtaining Level 216

Contents
12.6 Functions 217eCLD_LevelControlCreateLevelControl 218eCLD_LevelControlSetLevel 220eCLD_LevelControlGetLevel 221eCLD_LevelControlCommandMoveToLevelCommandSend 222eCLD_LevelControlCommandMoveCommandSend 224eCLD_LevelControlCommandStepCommandSend 226eCLD_LevelControlCommandStopCommandSend 228eCLD_LevelControlCommandStopWithOnOffCommandSend 229
12.7 Structures 23012.7.1 Custom Data Structure 23012.7.2 Custom Command Payloads 230
12.7.2.1 Move To Level Command Payload 23012.7.2.2 Move Command Payload 23112.7.2.3 Step Command Payload 231
12.8 Enumerations 23212.8.1 teCLD_LevelControl_ClusterID 232
13. Alarms Cluster 23513.1 Overview 23513.2 Alarms Cluster Structure and Attributes 23613.3 Initialisation 23613.4 Alarm Operations 236
13.4.1 Raising an Alarm 23613.4.2 Clearing an Alarm (from Server) 23713.4.3 Resetting Alarms (from Client) 237
13.5 Alarms Events 23713.6 Functions 239
eCLD_AlarmsCreateAlarms 240eCLD_AlarmsCommandResetAlarmCommandSend 242eCLD_AlarmsCommandResetAllAlarmsCommandSend 244eCLD_AlarmsCommandGetAlarmCommandSend 246eCLD_AlarmsCommandResetAlarmLogCommandSend 248eCLD_AlarmsResetAlarmLog 250eCLD_AlarmsAddAlarmToLog 251eCLD_AlarmsGetAlarmFromLog 252eCLD_AlarmsSignalAlarm 253eCLD_AlarmsClearAlarm 255
13.7 Structures 25713.7.1 Event Callback Message Structure 25713.7.2 Custom Data Structure 258

13.7.3 Custom Command Payloads 25813.7.3.1 Reset Alarm Command Payload 25813.7.3.2 Alarm Notification Payload 259
13.7.4 Custom Response Payloads 25913.7.4.1 Get Alarm Response Payload 259
13.7.5 Alarms Table Entry 26013.8 Enumerations 260
13.8.1 teCLD_Alarms_AttributeID 26013.9 Compile-Time Options 261
14. Time Cluster and ZCL Time 26314.1 Overview 26314.2 Time Cluster Structure and Attributes 26414.3 Attribute Settings 266
14.3.1 Mandatory Attributes 26614.3.2 Optional Attributes 267
14.4 Maintaining ZCL Time 26814.4.1 Updating ZCL Time Following Sleep 26814.4.2 ZCL Time Synchronisation 269
14.5 Time-Synchronisation of Devices 26914.5.1 Initialising and Maintaining Master Time 27114.5.2 Initial Synchronisation of Devices 27314.5.3 Re-synchronisation of Devices 274
14.6 Time Event 27414.7 Functions 275
eCLD_TimeCreateTime 276vZCL_SetUTCTime 278u32ZCL_GetUTCTime 279bZCL_GetTimeHasBeenSynchronised 280vZCL_ClearTimeHasBeenSynchronised 281
14.8 Return Codes 28214.9 Enumerations 282
14.9.1 teCLD_TM_AttributeID 28214.10 Compile-Time Options 282
15. Binary Input (Basic) Cluster 28515.1 Overview 28515.2 Binary Input (Basic) Structure and Attribute 28515.3 Functions 288
eCLD_BinaryInputBasicCreateBinaryInputBasic 289

Contents
15.4 Enumerations 29115.4.1 teCLD_BinaryInputBasicCluster_Attr

ZigBee Cluster Library User Guide - NXP · PDF fileZigBee Cluster Library User Guide. ZigBee...

Documents

Transcript of ZigBee Cluster Library User Guide - NXP · PDF fileZigBee Cluster Library User Guide. ZigBee...