In the Zigbee Cluster Library (ZCL), a cluster is a set of messages used to send and receive related commands and data over a Zigbee network. For example, a temperature cluster would contain all the necessary OTA messages required to send and receive information about temperature.
To facilitate learning and management, these clusters are further grouped into functional domains, such as those useful for HVAC, Security, Lighting, and so on. Developers may also define their own clusters, if the pre-defined clusters do not meet their specific application needs.
The Zigbee common application layer then references which clusters are used within certain applications, and specifies which clusters are supported by different devices–some clusters are mandatory, others optional. In this way, the ZCL simplifies the documentation of a particular application and allows the developer to understand quickly which behaviors devices support.
A more detailed overview of the ZCL, the format of messages within clusters, and a set of messages that may be used within any cluster are described in the Zigbee Cluster Library Specification document (15-02017-002). Functional domain clusters are described in separate documents, such as the Functional Domain: Generic, Security and Safety document.
Silicon Labs provides source code to easily assemble and disassemble ZCL messages, whether they are pre-defined by the ZCL or custom messages created by the developer. In addition, Silicon Labs provides a powerful tool called AppBuilder that allows developers to create and configure most of their ZCL-based application. See document UG102: Application Framework Developer Guide, for more information.
Each cluster is divided into two ends, a client end and a server end. The client end of a cluster sends messages that may be received by the server end. The client end may also receive messages that are sent by the server end. In this sense, the client and server ends of a cluster are always complementary. In contrast to many other systems (for example, HTTP), both have the same potential for sending and receiving messages: the “client” designation does not imply a subordinate or response-only status.
Because all commands have a sender and a receiver, each cluster is described in two parts – a server part and a client part, as shown in the following figure. A device supporting the server half of a cluster will communicate with a device supporting the client half of the same cluster.
This equality complicates discussions; for clarity, this document always refers to “cluster end” when one of the client or the server end must be used, “cluster ends” when speaking of both client and server ends, and “cluster server” or “cluster client” when a specific end is required (usually examples).
An attribute is data associated with a cluster end; the server and client ends of a cluster may each possess multiple attributes.
Each attribute declares a 16-bit identifier, a data type, a read-only or read/write designator, a default value, and an indicator of whether its support by any implementation is mandatory or optional. The following table lists example data types.
Data Type | Description |
---|---|
Binary data types | 8, 16, 24, or 32 bits in length |
Logical data type | Boolean |
Bitmap data type | 8, 16, 24, or 32 bits in length |
Unsigned Integer | 8, 16, 24, or 32 bits in length |
Signed Integer: | 8, 16, 24, or 32 bits in length |
Enumeration: | 8 or 16 bits in length |
Floating Point: | 2-byte semi-precision, 4-byte single precision, or 8 byte double precision |
String: | binary octet string or character string; first byte is length |
Time: | time of day, date |
Identifier: | cluster ID, attribute ID |
IEEE address type | 8-byte unique IEEE address of an 802.15.4 radio |
The attribute identifier is unique only within the specific cluster end: this means that the attribute 0x0002 within the cluster server does not need to be the same as the attribute 0x0002 within the cluster client, even within the same cluster.
The data types are fully described in the ZCL Specification. The following table is an excerpt from that document.
Type Class | Data Type ID | Data Type | Length of Data (octets) | Invalid Number | Analog / Discrete |
---|---|---|---|---|---|
Null | 0x00 | No data | 0 | - | - |
0x01 – 0x7 | Reserved | - | - | ||
General Data | 0x08 | 8-bit data | 1 | - | D |
0x09 | 16-bit data | 2 | - | ||
0x0A | 24-bit data | 3 | - | ||
0x0B | 32-bit data | 4 | - | ||
0x0C – 0x0F | Reserved | - | - | ||
Logical | 0x10 | Boolean | 1 | 0xFF | D |
0x11 – 0x17 | Reserved | - | - | ||
Bitmap | 0x18 | 8-bit bitmap | 1 | - | D |
0x19 | 16-bit bitmap | 2 | - | ||
0x1a | 24-bit bitmap | 3 | - | ||
0x1b | 32-bit bitmap | 4 | - | ||
0x1C – 0x1F | Reserved | - | - | ||
Unsigned Integer | 0x20 | Unsigned 8-bit integer | 1 | 0xFF | A |
0x21 | Unsigned 16-bit integer | 2 | 0xFFFF | ||
0x22 | Unsigned 24-bit integer | 3 | 0xFFFFFF | ||
0x23 | Unsigned 32-bit integer | 4 | 0xFFFFFFFF | ||
0x24 – 0x27 | Reserved | - | - | ||
Signed Integer | 0x28 Signed 8-bit integer | 1 | 0x80 | A | |
0x29 Signed 16-bit integer | 2 | 0x8000 | |||
0x2A Signed 24-bit integer | 3 | 0x800000 | |||
0x2B Signed 32-bit integer | 4 | 0x80000000 | |||
0x2C – 0x2F | Reserved | - | - | ||
Enumeration | 0x30 | 8-bit enumeration | 1 | 0xFF | |
0x31 | 16-bit enumeration | 2 | 0xFFFF | ||
0x32 – 0x37 | Reserved | - | - | ||
Floating Point | 0x38 | Semi-precision | 2 | Not a Number | A |
0x39 | Single precision | 4 | Not a Number | ||
0x3A | Double precision | 8 | Not a Number | ||
0x3B – 0x3F | Reserved | - | - | ||
String | 0x40 | Reserved | - | - | D |
0x41 | Octet string | Defined in first octet | 0xFF in first octet | ||
0x42 | Character string | Defined in first octet | 0xFF in first octet | ||
0x43 – 0x47 | Reserved | - | - | ||
Array | 0x48 – 0x4F | Reserved | - | - | - |
List | 0x50 – 0x57 | Reserved | - | - | - |
Reserved | 0x58 – 0xDF | - | - | - | - |
Time | 0xE0 | Time of day | 4 | 0xFFFFFFFF | A |
0xE1 | Date | 4 | 0xFFFFFFFF | ||
0xE2 – 0xE7 | Reserved | - | - | ||
Identifier | 0xE8 | Cluster ID | 2 | 0xFFFF | D |
0xE9 | Attribute ID | 2 | 0xFFFF | ||
0xEA | BACnet OID | 4 | 0xFFFFFFFF | ||
0xEB – 0xEF | Reserved | - | - | ||
Miscellaneous | 0xF0 | IEEE address | 8 | 0xFFFFFFFFFFFFFFFF | D |
0xF1 – 0xEF | Reserved | - | - | - | |
Unknown | 0xFF | Unknown | 0 | - | - |
Attributes may be accessed over the air by use of the attribute commands described later in this document.
Global attributes were introduced in revision 6 of the ZCL. These attributes are defined for every cluster instance on a device and function as normal ZCL attributes. Cluster Revision (attribute ID 0xFFFD) is one example of a global attribute. This attribute is a way to version each of the individual cluster specifications, to improve backwards compatibility, and allow for testing of specific versioned cluster behavior. One device may read the Cluster Revision attribute on another device to determine how to communicate certain cluster behavior to them over the air. This Cluster Revision attribute is incremented for every major change to each cluster’s specification.
A command is composed of an 8-bit command-identifier and a payload format. Like attributes, the 8-bit identifier is unique only within the specific cluster end. The payload format is arbitrary to the command type, conforming only to the general packet format guidelines as described in the ZCL Specification.
Commands are divided into two types: global and cluster-specific. Global commands are defined in the ZCL Specification and are not specific to any cluster. These global commands were originally referred to as Profile-Wide, but have changed name to fall in line with the Zigbee 3.0 common application layer. Cluster-specific commands are defined inside the cluster definitions in the ZCL functional domain documents, and are unique to the cluster in which they are defined.
Global Commands
Global commands are not unique to a specific cluster; they are defined in the ZCL General Command Frame (see ZCL Specification 075123r02, Chapter 7). The following table lists example profile-wide commands:
Messages Sent to the Cluster End Supporting the Attribute | Messages Sent From the Cluster End Supporting the Attribute |
---|---|
Read Attributes | Read Attributes Response |
Write Attributes | Write Attributes Response/No Response |
Write Attributes Undivided | Write Attributes Response/No Response |
Configure Reporting | Configure Reporting Response |
Read Reporting Configuration | Read Reporting Configuration Response |
Discover Attributes | Discover Attributes Response |
Report Attributes | Report Attributes |
Default Response | Default Response |
- Read Attributes: Requests one or more attributes to be returned by the recipient; replies with Read Attributes Response.
- Write Attributes: Provides new values for one or more attributes on the recipient; the reply will contain a Write Attributes Response portion indicating which attributes were successfully updated, and/or a Write Attributes No Response portion for attributes that were not successfully updated.
- Write Attributes Undivided: Updates all attributes and replies with Write Attributes Response; if any single attribute cannot be updated, no attributes are updated and this command replies with Write Attributes No Response.
- Configure Reporting: Configures a reporting interval, trigger events, and a destination for indicated attributes. Replies with Configure Reporting Response.
- Read Reporting Configuration: Generates a Read Reporting Configuration Response containing the current reporting configuration sent in reply.
- Discover Attributes: Requests all supported attributes to be sent; replies with a Discover Attributes Response.
- Report Attributes: A report of attribute values configured by Configure Reporting command.
- Default Response: A response sent when no more specific response is available (and the default response is not disabled by the incoming message).
Since attributes are always tied to a cluster, the commands affecting attributes specify which cluster and which attributes are to be accessed or modified. Additionally, each cluster defines which attributes support which commands – for example, an attributes may be declared READ ONLY, in which case it will not support the Write Attributes command. Thus, while the command format is not clusterspecific, the attributes it describes and its result on the receiving system are both cluster-specific.
Readers interested in more detail about the format or specific behaviors of these messages should review the ZCL Specification (075123r02)
Cluster-Specific Commands
The payload format, support requirements (mandatory, optional), and behavior on receipt of a cluster-specific command are all defined in the cluster definition. Typically, these commands affect the state of the receiving device and may alter the attributes of the cluster as a side-effect.
For example, the ZCL defines three commands (OFF, ON, and TOGGLE) that are received by the On/Off cluster server. It further declares that each of these commands is mandatory and the payload format for each command (in this case, none of them have payloads). The ZCL defines that the On/Off cluster client is responsible for generating the commands received by the server.
As an example, consider a portion of the Temperature Measurement Sensor cluster that is fully described in Chapter 4 of the Zigbee Cluster Library Specification (15-02017-002).
The following table lists some of the attributes from the ZCL specification.
Identifier | Names | Types | Range | Access | Default | Mandatory/Optional |
---|---|---|---|---|---|---|
0x0000 | MeasuredValue | Signed 16-bit Integer | MinMeasuredValue to MaxMeasuredValue | Read only | 0 | M |
0x0001 | MinMeasuredValue | Signed 16-bit Integer | 0x954B – 0x7FFE | Read only | - | M |
0x0002 | MaxMeasuredValue | Signed 16-bit Integer | 0x954C – 0x7FFF | Read only | - | M |
0x0003 | Tolerance | Unsigned 16- bit Integer | 0x0000 – 0x0800 | Read only | - | O |
0xFFFD | ClusterRevision | Unsigned 16- bit Integer | 0x0001 – 0xFFFE | Read only | 0x0001 | M |
1. Overview of Attributes: The cluster server supports at least those five attributes, four of which must be supported by any implementation (MeasuredValue, MinMeasuredValue, MaxMeasuredValue, and ClusterRevision), and one of which may be optionally supported (Tolerance). All of these attributes are read-only, indicating that any write attempts to them will fail. Note the ClusterRevision global attribute functions as a regular attribute.
2. Implications for Cluster Server, Cluster Client: Clearly, the cluster server should be implemented by the device that contains the temperature sensor. Meanwhile the cluster client should be implemented by any device that wishes to receive temperature sensor information, either actively (through a read attributes command) or passively (through first a configure report attributes command and then from report attributes).
3. Further Information: The cluster description also provides useful information about the actual format of the data (for example, the range of the signed 16-bit integer for MaxMeasuredValue) and the mandatory supported operations – not all attributes support all basic commands. For example, MaxMeasuredValue is a read-only command and cannot be written.Note: While the incoming write attribute commands are supported, in this case MaxMeasuredValue always generates a Write Attributes No Response reply.
4. Commands: No custom commands are supported by this cluster (either the server or the client). For an example of a cluster containing custom commands, see the Thermostat Cluster in the ZCL (15-02017-002).
As of this writing, the Zigbee Cluster Library defines the following functional domains:
- General
- HVAC
- Lighting
- Measurement & Sensing
- Security & Safety
- Smart Energy
- Over-the-Air Upgrading
- Telecommunications
- Commissioning
Each domain defines a number of clusters that are then used by the Zigbee Application Layer to describe the OTA behavior of devices (see the following figure).
The ZCL allows extension of the existing library in two ways: users may add manufacturer specific commands or attributes to existing clusters, or they may define entirely new clusters that are manufacturer specific.
Manufacturer-specific commands are identified by setting a special bit in the ZCL header and including the manufacturer code (received from the Zigbee Alliance) in the ZCL header. This guarantees that manufacturer-specific extensions do not interfere with other manufacturer-specific extensions or existing ZCL clusters, commands, or attributes.
Manufacturer-specific clusters must use the cluster ID range of 0xFC00-0xFFFE.
Zigbee compliance is based on a building block of compliance testing used to ensure that each layer is tested.
Products that meet all compliance requirements may be branded “Zigbee Compliant” and can display the Zigbee logo.
The Zigbee radio and MAC are required to have passed the applicable parts of IEEE 802.15.4 certification testing. Parts of the MAC not required for Zigbee operation are not required for this testing.
Zigbee stacks are required to be built on certified IEEE 802.15.4 platforms. Zigbee stack providers are required to have the stack tested against a standard Zigbee test plan known as Zigbee Compliant Platform Testing. This testing validates the basic network, security, and Zigbee Device Object (ZDO) operations for the stack.
Zigbee products are required to be built on a Zigbee Compliant Platform. The developer can choose to build a public or manufacturerspecific application. Those applications which are manufacturer-specific are tested against a specific set of tests to validate basic operation. Products based on the common Zigbee application layer are more extensively tested using a standard Zigbee test for the application layer commands. Testing scrutiny has been heavily increased in Zigbee 3.0; there are now many negative test cases that products must pass in order to pass certification.
The Zigbee Test Harness is new in Zigbee 3.0. The Zigbee Test Harness is provided to Zigbee members for testing their products and also is used for the final compliance testing for a Zigbee 3.0 product. The Zigbee Test Harness involves both a test harness Zigbee software stack running on a compliant IEEE 802.15.4 platform and a desktop application offering a friendly user interface to the tester.
Each shipping product has to be certified and substantive changes to the product after certification can require recertification. Silicon Labs sends all chips and stack releases through compliance testing.
All of the Zigbee test plans are developed and tested using at least three members’ products to ensure interoperability between different implementations.
Companies are required to become members of the Zigbee alliance to ship product containing the Zigbee stack. There are specific rules for use of the Zigbee logo on product that are detailed on the Zigbee web site (www.zigbee.org).
Zigbee 3.0 marks the beginning of a new chapter in the Zigbee Alliance. Zigbee 3.0 unites all of the different application profiles into one common application layer. Furthermore, it introduces greater test coverage for product certification, ensuring better interoperability for Zigbee devices in the field. The Zigbee 3.0 document suite contains both revised and completely new material for the Zigbee application specification.
The Base Device Behavior Specification (BDB) is perhaps the most important new document in the Zigbee 3.0 document suite. It specifies mandatory and optional application layer behavior for any Zigbee product. These behaviors include, but are not limited to:
- Network commissioning
- Network security
- ZDO command handling
- Reporting
- MAC data polling
- Persistent data
See document 13-0402 for more specific information on these items. Because there is now one specification for all Zigbee applications,two different Zigbee 3.0-compliant products in different application domains can interoperate on the same network (for example, a light switch and a garage door opener can perform separate functions on the same network).
At the heart of the BDB are the commissioning methods that a Zigbee 3.0 device can use. The methods follow an order of execution, but they are all optional for a device. For example, it may only makes sense for a Zigbee End Device switch application to performing touchlink commissioning, classical joining, and then finding and binding. On the other hand, a Zigbee Coordinator gateway application may only wish to form a network. Lastly, maybe a Zigbee Router light application could perform classical joining, and then fall back to classical network formation if it does not find any networks to join. The commissioning methods, and order, are as follows.
- Touchlink commissioning
- Classical network joining
- Classical network formation
- Finding and binding
Touchlink commissioning is the first step in the Zigbee 3.0 network commissioning process. A device may choose to perform the touchlink process for an initiator to try and find a touchlink target. A typical example of this interaction may be a switch and a light. Theswitch may perform touchlink commissioning to establish itself on the same network as the light. See 13-0402 for a more in-depth description of touchlink commissioning.
The next step in the BDB defined process is classical joining. This means finding open networks and joining one using the original Zigbee joining process. Finding a network involves performing IEEE 802.15.4 active scans on a product-defined set of channels. Once a device has found a network that it wishes to join, it may join that network using an install code derived link key, a default link key for a centralized security network, and a default link key for a distributed security network. For more information on the security mechanisms involved in the Zigbee 3.0 application layer, see UG103.5: Security Fundamentals.
A Zigbee 3.0 application may then choose to form a classical Zigbee network. A product may form a centralized security network as a trust center or form a distributed security network as a router. This is different from many legacy application profiles where only a Zigbee coordinator could form a network. A light may wish to form a network as a router so that it can act as a touchlink target, whereas it makes more sense for a gateway to form a centralized network as a trust center. Trust centers may choose to only allow only certain devices on the network by using install code derived link keys for joining. Again, see UG103.5: Security Fundamentals for a thorough discussion of Zigbee 3.0 security.
Once devices are on a network, they can perform finding and binding, where devices create bindings to establish application layer links. For example, an On/Off switch may perform finding and binding to create a binding to an On/Off Light. Again, as all commissioning steps, this step is optional.
As mentioned previously, Zigbee 3.0 also introduces more stringent testing on products. This means products will go through more negative test cases and specific cluster functionality tests before they are allowed on the market. Included in the Zigbee 3.0 document suite are the new Cluster Test Specifications. These documents contain test cases for Zigbee products implementing certain clusters. For a product using a certain cluster to be Zigbee 3.0 certified, it must pass the test cases contained within this document for that specific cluster. There is an individual Zigbee document for each cluster test spec. For an example, see document 15-0310, the On/Off Cluster test specification.
Zigbee 3.0 also mandates that devices should support proxy functionality for Green Power, a networking and application-level specification designed for energy-harvesting end devices. Essentially, this means that every Zigbee 3.0 device will be able to process and forward Green Power messages to other devices with more application-layer Green Power functionality. The Green Power Basic specification and test specification are included in the Zigbee 3.0 document suite.
It is worth mentioning that the 6th revision of the Zigbee Cluster Library (document 15-02017) is also included in the Zigbee 3.0 document suite. See section 6. Zigbee Cluster Library for more information about this specification.
A set of design decisions must be made in any Zigbee implementation. For more information, see UG103.3: Software Design Fundamentals.