ZigBee Cluster Library (ZCL)
The ZigBee Cluster Library (ZCL) for ZigBee 3.0 contains standard clusters, as defined by the ZigBee Alliance, for use in ZigBee 3.0 applications over a diverse range of market sectors. Each cluster corresponds to a specific functionality, through a set of attributes and/or commands. Clusters can be selected from the ZCL to give an application the required set of capabilities.
The ZCL also provides a common means for applications to communicate. It defines a header and payload that sit inside the Protocol Data Unit (PDU) used for messages. It also defines attribute types (such as integers and strings), common commands (for example, for reading attributes), and default responses for indicating success or failure.
The NXP implementation of the ZCL, described in this manual, is supplied in the ZigBee 3.0 Software Developer’s Kit (SDK) available via the NXP web site (see Support Resources). These SDKs provide only the clusters supported by NXP that are described in this manual. The ZCL is fully detailed in the ZigBee Cluster Library Specification (075123), available from the ZigBee Alliance.
ZCL Member Clusters
The clusters of the ZCL are divided into functional areas, for convenience. An application can use clusters from any number of these areas to make up its complete functionality. The clusters implemented by NXP are from the following areas (the associated clusters are listed in the referenced sub-sections):
General - Section 1.1.1
Measurement and Sensing - Section 1.1.2
Lighting - Section 1.1.3
Heating, Ventilation and Air-Conditioning (HVAC) - Section 1.1.4
Closures - Section 1.1.5
Security and Safety - Section 1.1.6
Smart Energy - Section 1.1.7
Commissioning - Section 1.1.8
Appliances - Section 1.1.9
Over-The-Air (OTA) Upgrade - Section 1.1.10
Note: Not all of the clusters from the above ZCL functional areas are available in the NXP software.
General
The General clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part III: General Clusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
Basic |
0x0000 |
The Basic cluster contains the basic properties of a ZigBee device for example, software and hardware versions. The Basic cluster allows the setting of user-defined properties such as location. This cluster is detailed in Chapter 8. |
Power Configuration |
0x0001 |
The Power Configuration cluster allows users to determine the power source details of a device and helps configure the under/over-voltage alarms. This cluster is detailed in Chapter 9. |
Device Temperature Configuration |
0x0002 |
The Device Temperature Configuration cluster allows information about the internal temperature of a device to be obtained and under/over-temperature alarms to be configured. This cluster is detailed in Chapter 10. |
Identify |
0x0003 |
The Identify cluster allows a ZigBee device to make itself known visually (for example, by flashing a light) to an observer, such as a network installer. This cluster is detailed in Chapter 11. |
Groups |
0x0004 |
The Groups cluster allows the management of the Group table concerned with group addressing - that is, the targeting of multiple endpoints using a single address. This cluster is detailed in Chapter 12. |
Scenes |
0x0005 |
The Scenes cluster allows the management of pre-defined sets of cluster attribute values called scenes, where a scene can be stored, retrieved, and applied to put the system into a pre-determined state. This cluster is detailed in Chapter 13. |
On/Off |
0x0006 |
The On/Off cluster allows a device to be put into the ‘on’ and ‘off’ states, or toggled between the two states. This cluster is detailed in Chapter 14. |
On/Off Switch Configuration |
0x0007 |
The On/Off Switch Configuration cluster allows the switch type on a device to be defined, as well as the commands to be generated when the switch is moved between its two states. This cluster is detailed in Chapter 15. |
Level Control |
0x0008 |
The Level Control cluster allows control of the level of a physical quantity (for example, heat output) on a device. This cluster is detailed in Chapter 16. |
Alarms |
0x0009 |
The Alarms cluster is used for sending alarm notifications and the general configuration of alarms for all other clusters on the ZigBee device (individual alarm conditions are set in the corresponding clusters). This cluster is detailed in Chapter 17. |
Time |
0x000A |
The Time cluster provides an interface to a real-time clock on a ZigBee device, allowing the clock time to be read and written in order to synchronize the clock to a time standard. This is the number of seconds since 0 hrs 0 mins 0 secs on 1st January 2000 UTC (Coordinated Universal Time). This cluster includes functionality for local time-zone and daylight saving time. This cluster is detailed in Chapter 18. |
Analogue Input (Basic) |
0x000C |
The Analogue Input (Basic) cluster provides an interface for accessing an analog measurement. This cluster is detailed in Section 19.1. |
Analogue Output (Basic) |
0x000D |
The Analogue Output (Basic) cluster provides an interface for setting the value of an analog output. This cluster is detailed in Section 19.2. |
Binary Input (Basic) |
0x000F |
The Binary Input (Basic) cluster provides an interface for accessing a binary (two-state) measurement. This cluster is detailed in Section 19.3. |
Binary Output (Basic) |
0x0010 |
The Binary Output (Basic) cluster provides an inter-face for setting the state of a binary (two-state) output. This cluster is detailed in Section 19.4. |
Multistate Input (Basic) |
0x0012 |
The Multistate Input (Basic) cluster provides an interface for accessing a multistate measurement (that can take one of a set of fixed states). This cluster is detailed in Section 19.5. |
Multistate Output (Basic) |
0x0013 |
The Multistate Output (Basic) cluster provides an interface for setting the value of a multistate output (that can take one of a set of fixed states). This cluster is detailed in Section 19.6. |
Poll Control |
0x0020 |
The Poll Control cluster provides an interface for remotely controlling the rate at which a ZigBee End Device polls its parent for data. This cluster is detailed in Chapter 20. |
Power Profile |
0x001A |
The Power Profile cluster provides an interface between a home appliance (for example, a washing machine) and the controller of an energy management system. This cluster is detailed in Chapter 21. |
Diagnostics |
0x0B05 |
The Diagnostics cluster allows the operation of the ZigBee PRO stack to be followed over time. This cluster is detailed in Chapter 22. |
Parent topic:ZCL Member Clusters
Measurement and Sensing
The Measurement and Sensing clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part IV: Measurement and SensingClusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
Illuminance Measurement |
0x0400 |
The Illuminance Measurement cluster provides an interface to an illuminance measuring device, allowing the configuration of measuring and the reporting of measurements. This cluster is detailed in Chapter 23. |
Illuminance Level Sensing |
0x0401 |
The Illuminance Level Sensing cluster provides an interface to light-level sensing functionality. This cluster is detailed in Chapter 24. |
Temperature Measurement |
0x0402 |
The Temperature Measurement cluster provides an interface to a temperature measuring device, allowing the configuration of measuring and the reporting of measurements. This cluster is detailed in Chapter 25. |
Pressure Measurement |
0x0403 |
The Pressure Measurement cluster provides an inter-face to a pressure measuring device, allowing the configuration of measuring and the reporting of measurements. This cluster is detailed in Chapter 26. |
Flow Measurement |
0x0404 |
The Flow Measurement cluster provides an interface to a flow measuring device for a fluid, allowing the configuration of measuring and the reporting of measurements. This cluster is detailed in Chapter 27. |
Relative Humidity Measurement |
0x0405 |
The Relative Humidity Measurement cluster provides an interface to a humidity measuring device, allowing the configuration of relative humidity measuring and the reporting of measurements. This cluster is detailed in Chapter 28. |
Occupancy Sensing |
0x0406 |
The Occupancy Sensing cluster provides an interface to an occupancy sensor, allowing the configuration of sensing and the reporting of status. This cluster is detailed in Chapter 29. |
Electrical Measurement |
0x0B04 |
The Electrical Measurement cluster provides an interface for obtaining electrical measurements from a device. This cluster is detailed in Chapter 30. |
Parent topic:ZCL Member Clusters
Lighting
The Lighting clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part V: Lighting Clusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
Colour Control |
0x0300 |
The Colour Control cluster can be used to adjust the colour of a light (it does not govern the overall luminance of the light, as this is controlled using the Level Control cluster). This cluster is detailed in Chapter 31. |
Ballast Configuration |
0x0301 |
The Ballast Configuration cluster can be used to configure a lighting ballast that restricts the light levels of a connected set of lamps. This cluster is detailed in Chapter 32. |
Parent topic:ZCL Member Clusters
Heating, Ventilation, and Air-Conditioning (HVAC)
The HVAC clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part VI: HVAC Clusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
Thermostat |
0x0201 |
The Thermostat cluster provides a means of configuring and controlling the functionality of a thermostat. This cluster is detailed in Chapter 33. |
Fan Control |
0x0202 |
The Fan Control cluster provides a means of con-trolling the speed or state of a fan which may be part of a heating or cooling system. The cluster is detailed in Chapter 34. |
Thermostat User Interface Configuration |
0x0204 |
The Thermostat User Interface (UI) Configuration cluster provides a means of configuring the user inter-face (keypad and/or LCD screen) for a thermostat or a thermostat controller device. This cluster is detailed in Chapter 35. |
Parent topic:ZCL Member Clusters
Closures
The Closure clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part VII: Closure Clusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
Door Lock |
0x0101 |
The Door Lock cluster provides a means of representing the state of a door lock and (optionally) the door. This cluster is detailed in Chapter 36. |
Parent topic:ZCL Member Clusters
Security and Safety
The Security and Safety clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part VIII: Security and Safety Clusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
IAS Zone |
0x0500 |
The IAS Zone cluster provides an interface to a zone device in an IAS (Intruder Alarm System). This cluster is detailed in Chapter 37. |
IAS ACE (Ancillary Control Equipment) |
0x0501 |
The IAS ACE cluster provides a control interface to a CIE (Control and Indicating Equipment) device in an IAS (Intruder Alarm System). This cluster is detailed in Chapter 38. |
IAS WD (Warning Device) |
0x0502 |
The IAS WD cluster provides an interface to a Warning Device in an IAS (Intruder Alarm System). For example, a CIE (Control and Indicating Equipment) device can use the cluster to issue alarm warning indications to a Warning Device when an alarm condition is detected. This cluster is detailed in Chapter 39. |
Parent topic:ZCL Member Clusters
Smart Energy
The Smart Energy clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part IX: Smart Energy Clusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
Price |
0x0700 |
The Price cluster provides the mechanism for sending and receiving pricing information within a ZigBee 3.0 network. This cluster is detailed in Chapter 40. |
Demand-Response and Load Control |
0x0701 |
The Demand-Response and Load Control (DRLC) cluster provides an interface for controlling an attached appliance that supports load control. The cluster is able to receive load control requests and act upon them - the demand-response functionality. This cluster is detailed in Chapter 41. |
Simple Metering |
0x0702 |
The Simple Metering cluster provides a mechanism to obtain consumption data from a metering device (elec-tric, gas, water or thermal). This cluster is detailed in Chapter 42. |
Other Smart Energy (SE) clusters, that are not available in the ZigBee 3.0 SDK, are provided in the NXP ZigBee Smart Energy SDK. The ZigBee 3.0 SDK contains only the SE clusters that are supported by NXP for non-SE applications.
Parent topic:ZCL Member Clusters
Commissioning
The Commissioning clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part X: Commissioning Clusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
Commissioning |
0x0015 |
The Commissioning cluster can be used for commissioning the ZigBee stack on a device during network installation and defining the device behaviour with respect to the ZigBee network (it does not affect applications operating on the devices). This cluster is detailed in Chapter 43. |
Touchlink Commissioning |
0x1000 |
The Touchlink Commissioning cluster is used when forming a ZigBee 3.0 network or adding a new node to an existing network. This cluster is detailed in Chapter 44. |
Parent topic:ZCL Member Clusters
Appliances
The Appliances clusters implemented by NXP are listed and outlined in the table below. These clusters are detailed in ‘Part XI: Appliances Clusters’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
Appliance Control |
0x001B |
The Appliance Control cluster provides an interface for remotely controlling appliances in the home. This cluster is detailed in Chapter 45. |
Appliance Identification |
0x0B00 |
The Appliance Identification cluster provides an interface for obtaining and setting basic appliance information. This cluster is detailed in Chapter 46. |
Appliance Events and Alerts |
0x0B02 |
The Appliance Events and Alerts cluster provides an interface for the notification of significant events and alert situations. This cluster is detailed in Chapter 47. |
Appliance Statistics |
0x0B03 |
The Appliance Statistics cluster provides an interface for supplying statistical information about an appliance. This cluster is detailed in Chapter 48. |
Parent topic:ZCL Member Clusters
Over-The-Air (OTA) Upgrade
The Over-The-Air (OTA) Upgrade cluster is outlined in the table below and detailed in ‘Part XII: Over-The-Air Upgrade’ of this manual.
Cluster |
Cluster ID |
Description |
|---|---|---|
OTA Upgrade |
0x0019 |
The OTA Upgrade cluster provides the facility to upgrade (or downgrade or re-install) application software on the nodes of a ZigBee 3.0 network by distributing the replacement software through the network (over the air) and updating the software with minimal interruption to node operation. This cluster is detailed in Chapter 49. |
Parent topic:ZCL Member Clusters
Parent topic:ZigBee Cluster Library (ZCL)
General ZCL Resources
In addition to clusters, the ZCL provides general (non-cluster-specific) resources. For example, common mechanisms are used to allow a cluster client to access (read and write to) the attributes on the cluster server - the NXP ZCL software includes C functions and structures for performing such accesses across all clusters.
The fundamental principles and mechanisms of the ZCL are presented in the rest of Part I: Fundamentals:
Chapter 2 describes essential ZCL principles, such as accessing attributes
Chapter 3 describes the ZCL handling of stack-related and timer-related events
Chapter 4 described the ZCL handling of errors.
The general resources provided by the ZCL software are detailed in Part II: CommonResources:
Chapter 5 details the core functions provided with the ZCL
Chapter 6 details the general ZCL structures
Chapter 7 details the general ZCL enumerations and status codes
Cluster-specific resources are detailed in the respective chapters for the clusters.
Note: It is possible to customize the clusters of the ZCL by introducing manufacturer-specific attributes and commands. The processes of adding custom attributes and commands are described in Appendix E.
Parent topic:ZigBee Cluster Library (ZCL)
ZCL Compile-time Options
Before the application can be built, the ZCL compile-time options must be configured in the header file zcl_options.h for the application.
Enabled Clusters
All required clusters must be enabled in the options header file. For example, to enable the Basic and Time clusters, the following lines are required:
#define CLD_BASIC
#define CLD_TIME
In addition, to include the software for a cluster client or server or both, it is necessary to select them in the options header file. For example, to select the Basic cluster client and server, the following lines are required:
#define BASIC_CLIENT
#define BASIC_SERVER
Support for Attribute Read/Write
Read/write access to cluster attributes must be explicitly compiled into the application, and must be enabled separately for the server and client sides of a cluster using the following macros in the options header file:
#define ZCL_ATTRIBUTE_READ_SERVER_SUPPORTED
#define ZCL_ATTRIBUTE_READ_CLIENT_SUPPORTED
#define ZCL_ATTRIBUTE_WRITE_SERVER_SUPPORTED
#define ZCL_ATTRIBUTE_WRITE_CLIENT_SUPPORTED
Each of the above definitions apply to all clusters used in the application.
Tip: If only read access to attributes is required, then it is recommended not to enable write access. This is because omitting the write options gives the benefit of a reduced application size.
Optional Attributes
Many clusters have optional attributes that may be enabled at compile-time via the options header file - for example, to enable the Time Zone attribute in the Time cluster:
#define E_CLD_TIME_ATTR_TIME_ZONE
Note: Cluster-specific compile-time options are described in detail in the chapters for the individual clusters. The attribute reporting feature also has its own compile-time options (see Appendix B.3.1).
Number of Endpoints
The following line can be added to set the number of endpoints supported on a node (to n):
#define ZCL_NUMBER_OF_ENDPOINTS n
The default value is 1.
Default Responses
The following line can be added to enable default responses (see Section 2.5):
#define ZCL_DISABLE_DEFAULT_RESPONSES
By default, they are disabled.
APS Acknowledgements
The following line can be added to enable APS acknowledgments:
#define ZCL_DISABLE_APS_ACK
By default, they are disabled.
Cooperative Tasks
By default, tasks within the application are cooperative, and events will therefore not be generated for locking and unlocking mutexes for resources that are shared between the tasks. To disable the cooperative task feature, add the following line:
#undefine COOPERATIVE
Note that this requires an undefine.
Parameter Checking
Parameter checking in various functions can be enabled by including the following line:
#define STRICT_PARAM_CHECK
This feature is useful for testing during application development. When the testing is complete, the option should be disabled to eliminate the checks and to save code memory. This option can be defined in the zcl_options.h file or the makefile.
‘Wild Card’ Profile
Commands with a ‘wild card’ application profile (Profile ID of 0xFFFF) can be accepted and processed by the receiving device by including the following line:
#define ZCL_ALLOW_WILD_CARD_PROFILE
Parent topic:ZigBee Cluster Library (ZCL)