Zigbee Cluster Library#

Overview#

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. SeeUG391: Zigbee Application Framework Developer's Guide for SDK 6.x and Lower or Zigbee Application Framework Developer's Guide for SDK 7.x for more information.

Inside Clusters#

Clients and Servers#

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).

Attributes#

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.

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.

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.

Commands#

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:

• 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 cluster-specific, 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.

Example: Temperature Measurement Sensor Cluster#

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.

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).

Functional Domains#

As of this writing, the Zigbee Cluster Library defines the following functional domains:

• General

• Closures

• HVAC

• Lighting

• Measurement & Sensing

• Security & Safety

• Protocol Interfaces

• Smart Energy

• Over-the-Air Upgrading

• Telecommunications

• Commissioning

• Retail

• Appliances

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).

Manufacturer Extensions#

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 Connectivity Standards 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.