Send Zigbee cluster library (ZCL) commands with the API
The Zigbee cluster library defines a set of attributes and commands (clusters) that can be supported in multiple Zigbee profiles. The ZCL commands are typically required when developing a Zigbee product that will interoperate in a public profile such as home automation or smart energy, or when communicating with Zigbee devices from other vendors. Applications that are not designed for a public profile or for interoperability applications can skip this section.
The following table shows some prominent clusters with their respective attributes and commands.
| Cluster (Cluster ID) | Attributes (Attribute ID) | Cluster ID |
|---|---|---|
| Basic (0x0000) |
Application Version (0x0001) Hardware Version (0x0003) Model Identifier (0x0005) |
Reset to defaults (0x00) |
| Identify (0x0003) | Identify Time (0x0000) |
Identify (0x00) Identify Query (0x01) |
| Time (0x000A) |
Time (0x0000) Time Status (0x0001) Time Zone (0x0002) |
|
| Thermostat (0x0201) |
Local Temperature (0x0000) Occupancy (0x0002) |
Setpoint raise / lower (0x00) |
The ZCL defines a number of profile-wide commands that can be supported on any profile, also known as general commands. These commands include the following.
| Command (Command ID) |
Description |
|---|---|
| Read Attributes (0x00) | Used to read one or more attributes on a remote device. |
| Read Attributes Response (0x01) | Generated in response to a read attributes command. |
| Write Attributes (0x02) | Used to change one or more attributes on a remote device. |
| Write Attributes Response (0x04) | Sent in response to a write attributes command. |
| Configure Reporting (0x06) | Used to configure a device to automatically report on the values of one or more of its attributes. |
| Report Attributes (0x0A) | Used to report attributes when report conditions have been satisfied. |
| Discover Attributes (0x0C) | Used to discover the attribute identifiers on a remote device. |
| Discover Attributes Response (0x0D) | Sent in response to a discover attributes command. |
Use the Explicit Addressing Command Request - 0x11 to send ZCL commands to devices in the network. Sending ZCL commands with the Explicit Transmit API frame requires some formatting of the data payload field.
When sending a ZCL command with the API, all multiple byte values in the ZCL command (API Payload) (for example, u16, u32, 64-bit addresses) must be sent in little endian byte order for the command to be executed correctly on a remote device.
Note When sending ZCL commands, set the AO command to 1 to enable the explicit receive API frame. This provides indication of the source 64- and 16-bit addresses, cluster ID, profile ID, and endpoint information for each received packet. This information is required to properly decode received data.
The following table shows how the Explicit API frame can be used to read the hardware version attribute from a device with a 64-bit address of 0x0013A200 40401234 (unknown 16-bit address). This example uses arbitrary source and destination endpoints. The hardware version attribute (attribute ID 0x0003) is part of the basic cluster (cluster ID 0x0000). The Read Attribute general command ID is 0x00.
| Frame fields | Offset |
Description |
||
|---|---|---|---|---|
| Frame type | 3 | |||
| Frame ID | 4 | Identifies the serial port data frame for the host to correlate with a subsequent transmit status. If set to 0, no transmit status frame will be sent out the serial port. | ||
| 64-bit destination address | MSB 5 | The 64-bit address of the destination device (big endian byte order). For unicast transmissions, set to the 64-bit address of the destination device, or to 0x0000000000000000 to send a unicast to the coordinator. Set to 0x000000000000FFFF for broadcast. | ||
| 6 | ||||
| 7 | ||||
| 8 | ||||
| 9 | ||||
| 10 | ||||
| 11 | ||||
| LSB 12 | ||||
| 16-bit destination network address | MSB 13 | The 16-bit address of the destination device (big endian byte order). Set to 0xFFFE for broadcast, or if the 16-bit address is unknown. | ||
| LSB 14 | ||||
| Source endpoint | 15 | Set to the source endpoint on the sending device (0x41 arbitrarily selected). | ||
| Destination endpoint | 16 | Set to the destination endpoint on the remote device (0x42 arbitrarily selected). | ||
| Cluster ID | MSB 17 | Set to the cluster ID that corresponds to the ZCL command being sent. 0x0000 = Basic Cluster. | ||
| LSB 18 | ||||
| Profile ID | MSB 19 | Set to the profile ID supported on the device (0xD123 arbitrarily selected). | ||
| LSB 20 | ||||
| Broadcast radius | 21 | Sets the maximum number of hops a broadcast transmission can traverse. If set to 0, the transmission radius will be set to the network maximum hops value. | ||
| Transmit options | 22 | All bits must be set to 0. | ||
| Data payload | ZCL frame header | Frame control | 23 | Bitfield that defines the command type and other relevant information in the ZCL command. For more information, see the ZCL specification. |
| Transaction sequence number | 24 | A sequence number used to correlate a ZCL command with a ZCL response. (The hardware version response will include this byte as a sequence number in the response.) The value 0x01 was arbitrarily selected. | ||
| Command ID | 25 | Since the frame control “frame type” bits are 00, this byte specifies a general command. Command ID 0x00 is a Read Attributes command. | ||
| ZCL payload | Attribute ID | 26 |
The payload for a “Read Attributes” command is a list of Attribute Identifiers that are being read. Note The 16-bit Attribute ID (0x0003) is sent in little endian byte order (0x0300). All multi- byte ZCL header and payload values must be sent in little endian byte order. |
|
| 27 | 0xFF minus the 8 bit sum of bytes from offset 3 to this byte. | |||
Example
In this example, the Frame Control field (offset 23) is constructed as follows:
| Name | Bits | Example Value Description |
|---|---|---|
| Frame Type | 0-1 | 00 - Command acts across the entire profile. |
| Manufacturer Specific | 2 | 0 - The manufacturer code field is omitted from the ZCL Frame Header. |
| Direction | 3 | 0 - The command is being sent from the client side to the server side. |
| Disable Default Response | 4 | 0 - Default response not disabled. |
| Reserved | 5-7 | Set to 0. |
For more information, see the Zigbee Cluster Library specification.
|
Frame data fields |
Offset |
Example |
||
|---|---|---|---|---|
|
Start delimiter |
0 |
0x7E |
||
|
Length |
MSB 1 |
0x00 |
||
|
LSB 2 |
0x19 |
|||
|
Frame type |
3 |
0x11 |
||
| Frame ID | 4 | 0x01 | ||
|
64-bit destination address
|
MSB 5 |
0x00 |
||
|
6 |
0x13 |
|||
|
7 |
0xA2 | |||
|
8 |
0x00 | |||
|
9 |
0x40 | |||
|
10 |
0x40 | |||
|
11 |
0x12 | |||
|
LSB12 |
0x34 | |||
|
16-bit destination network address |
MSB 13 |
0xFF |
||
| LSB 14 |
0xFE |
|||
|
Source endpoint |
15 |
0x41 |
||
|
Destination endpoint |
16 |
0x42 |
||
|
Cluster ID |
MSB 17 |
0x00 |
||
|
LSB 18 |
0x00 |
|||
|
Profile ID |
MSB 19 |
0xD1 |
||
|
LSB 20 |
0x23 |
|||
|
Broadcast radius |
21 |
0x00 |
||
|
Transmit options |
22 |
0x00 |
||
|
Data payload |
ZCL frame header | Frame control |
23 |
0x00 |
| Transaction sequence number | 24 | 0x01 | ||
| Command ID | 25 | 0x00 | ||
| ZCL payload | Attribute ID | 26 | 0x03 | |
| 27 | 0x00 | |||
|
Checksum |
28 |
0xFA |
||
PDF
