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