ZCL Concepts and Definitions#
Clusters#
Each Zigbee cluster defines an application-level protocol. A set of these protocols (or clusters) defines the functionality of a particular Zigbee device. Anyone with a networking background can think of a cluster as an application protocol that has been encapsulated within the Zigbee specification.
The Zigbee Cluster Library (ZCL) is a document that specifies the clusters used by Zigbee devices. The original ZCL document had 30 clusters, most of which were specified as required or optional by at least one device in the Zigbee application profile. The Smart Energy (SE) application profile uses some of the clusters specified in the ZCL but also specifies new clusters that are unique to SE.
Devices#
A Zigbee device can be thought of as a collection of clusters. For example, an on/off light switch and an on/off light are two devices in the Zigbee 3.0 specification. All the devices within a profile must use the same type of security. There are recommendations on polling rates, start-up parameters, what kind of ZDO messages should be implemented, and so on, with the idea being that these devices must interoperate on the same network. If devices have different security settings, they cannot join together. If a user buys a Zigbee 3.0 device from company A and buys another Zigbee 3.0 device from company B, because they use the same application profile, the devices should be able to join work together.
If two Zigbee devices are on a certified Zigbee stack, they can route for each other. In other words, they can exchange messages at the application level. Interoperability at the application level is not guaranteed until devices use an application profile. These standard application profiles enable Project Configurator to generate Zigbee- compliant applications.
The Zigbee 3.0 on/off light has the following implementations:
Identify server (required by all)
Groups server
Scenes server
On/Off server
The Zigbee 3.0 on/off light switch has the following implementations:
Identify client
Groups client
Scenes client
On/Off client
The on/off light switch can send an on/off or toggle message that the on/off light is required to understand and accept.
Profile ID#
When configuring an endpoint, you must specify a Profile ID. If you are developing a Zigbee 3.0 application, you must specify the profile ID 0x0104. When developing an SE application, you must specify the profile ID 0x0109.
More About Clusters and Attributes#
Clusters specify two things: attributes and commands. Attributes are well-defined pieces of data that are stored on a device and can be read (and sometimes written) by external devices. Commands specify Over-The-Air (OTA) messages that are exchanged. Each command defined by the ZCL is unidirectional in the sense that it is sent by one side (either the client or server) and received by the other. A device can implement only one side of a cluster, or it can implement both sides of a cluster.
For instance, a Zigbee On/Off Light implements the server side of the “on/off” cluster, while the Zigbee On/Off Light Switch implements the client side of the “on/off” cluster. This defines that the Light Switch sends “on”, “off”, and “toggle” commands that the Light can receive (and understand). It also defines that the Light stores a Boolean attribute called “on/off” representing the current state of the device.
Note: Zigbee often uses the terms “in-cluster-list” and “out-cluster-list” instead of server and client. An “in-cluster-list” is the list of supported server clusters, and the “out-cluster-list” is the list of supported client clusters.
In most cases, the server side of a cluster contains all the attributes, and the client side is the side that initiates an OTA exchange. For the most part, the client sends a message and the server answers that message.
Example: The Identify Cluster#
The client/server interaction defined by the ZCL is illustrated in the Identify example shown in the following figure.
Like many clusters, the Identify cluster is a simple cluster. The lower right corner shows the single attribute—identify time.
Identify Cluster Use Case#
A user is provisioning a network of 12 lights in one room and must connect six of those lights to a single switch. The MAC address of each light is used to associate it with the switch. The MAC addresses for all 12 lights can be discovered by using a provisioning tool and a low power broadcast or by using a token (set when they were installed) on each light indicating room or location. The “Identify” functionality can be used to figure out which six MAC addresses correspond to the six physical lights that the user wants bound to a switch. Using the Identify cluster, the user can tell each light individually to “identify” itself (for example, blink so that it can be seen).
The Identify cluster defines the protocol for how devices are put into and taken out of identify mode. In the above example, the provisioning tool implements the client side of the identify cluster and the light or the device that needs to be identified implements the server side.
When the client wants to tell a device to “start identifying,” it sends the “Identify” command and specifies a period of time in seconds for which to continue identifying. The device stops identifying when the identify time attributes (decremented each second) reaches 0 or if the device receives an “Identify” command with identify time value of 0.
The first message in the above figure turns on “identify.” When identify is turned on, a time period is also included in the message. For example, suppose identify is turned on for 30 seconds. The second message shows the client (provisioning device) querying the server (light) to find out how much time is left in the identify process.
Because a query message can be sent to a group, it is possible to put a device into a mode where it is identifying, and then use a PC or provisioning tool and figure out which device in the group is identifying. This is useful if a device supports a physical cue to start identifying. Then a device can be poked (button press, magnet wand, and so on) to start identifying, and a group message can be sent to map the MAC address to the physical device.
Example: The Temperature Measurement Cluster#
The following figure illustrates another example of a temperature measurement cluster.
Notice that this cluster has no commands, it only has attributes. In this case, the device implements measurements of temperature, such as a thermostat. This example includes a measured value, a minimum measured value, and a maximum measured value. With no commands, this cluster relies on the global commands defined in the ZCL. The global commands define messages for reading, writing, discovering, and reporting attributes.
Note: Fourteen global commands such as read attributes, write attributes, configure attribute reporting, discover attributes, and report attribute values are included in this cluster. Clusters that only include attributes are simple to understand and implement because the global commands are already implemented.
To read the value of an attribute of this cluster, a global read attributes command is used. This message contains the attribute ID of the attribute to read. In combination, the cluster and the attribute ID provide unique identification. On the embedded side, this makes it possible to centralize all the attributes in a single table. All the code for those attributes is generic, shared code.
As a result, for example, when adding four of the temperature-measuring-sensing clusters, the impact on flash is minimal because there are no additional commands. The impact on RAM depends on the number of attributes added per cluster.
The application-level protocol provided by the ZCL makes it possible for two companies to develop products separately and have them work together without having to test them together.