Send ZDO commands with the API
Zigbee specifications define Zigbee device objects (ZDOs) as part of the Zigbee device profile. These objects provide functionality to manage and map out the Zigbee network and to discover services on Zigbee devices. ZDOs are typically required when developing a Zigbee product that interoperates in a public profile such as home automation or smart energy, or when communicating with Zigbee devices from other vendors. You can also use the ZDO to perform several management functions such as frequency agility (energy detect and channel changes - Mgmt Network Update Request), discovering routes (Mgmt Routing Request) and neighbors (Mgmt LQI Request), and managing device connectivity (Mgmt Leave and Permit Join Request).
The following table shows some of the more prominent ZDOs with their respective cluster identifier. Each ZDO command has a defined payload. See the Zigbee device profile section of the Zigbee specification for details.
| ZDO command | Cluster ID |
|---|---|
| Network Address Request | 0x0000 |
| IEEE Address Request | 0x0001 |
| Node Descriptor Request | 0x0002 |
| Simple Descriptor Request | 0x0004 |
| Active Endpoints Request | 0x0005 |
| Match Descriptor Request | 0x0006 |
| Mgmt LQI Request | 0x0031 |
| Mgmt Routing Request | 0x0032 |
| Mgmt Leave Request | 0x0034 |
| Mgmt Permit Joining Request | 0x0036 |
| Mgmt Network Update Request | 0x0038 |
Use the Explicit Addressing Command Request - 0x11 to send Zigbee device objects commands to devices in the network. Sending ZDO commands with the Explicit Transmit API frame requires some formatting of the data payload field.
When sending a ZDO command with the API, all multiple byte values in the ZDO command (API payload), for example, u16, u32, and 64-bit addresses, must be sent in little endian byte order for the command to be executed correctly on a remote device.
For an API XBee to receive ZDO responses, set AO (API Options) to 1 to enable the explicit receive API frame.
The following table shows how you can use the Explicit API frame to send an “Active Endpoints” request to discover the active endpoints on a device with a 16-bit address of 0x1234.
| Frame data fields | Offset | Description |
|---|---|---|
| Frame type | 3 | 0x11 |
| Frame ID | 4 | Identifies the data frame for the host to correlate with a subsequent transmit status. If set to 0, the device does not send a response out the serial port. |
| 64-bit destination address | 5-12 |
MSB first, LSB last. 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. |
| 16-bit destination network address | 13 | MSB first, LSB last. 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. |
| 14 | ||
|
Source endpoint |
15 | Set to 0x00 for ZDO transmissions (endpoint 0 is the ZDO endpoint). |
| Destination endpoint | 16 | Set to 0x00 for ZDO transmissions (endpoint 0 is the ZDO endpoint). |
| Cluster ID | 17 |
Set to the cluster ID that corresponds to the ZDO command being sent. 0x0005 = Active Endpoints Request |
| 18 | ||
| Profile ID | 19-20 | Set to 0x0000 for ZDO transmissions (Profile ID 0x0000 is the Zigbee device profile that supports ZDOs). |
| Broadcast radius | 21 |
Sets the maximum number of hops a broadcast transmission can traverse. If set to 0, the device sets the transmission radius to the network maximum hops value. |
| Transmission options | 22 |
All bits must be set to 0. |
| Data payload | 23 |
The required payload for a ZDO command. All multi-byte ZDO parameter values (u16, u32, 64- bit address) must be sent in little endian byte order. The Active Endpoints Request includes the following payload: [16-bit NwkAddrOfInterest] Note The 16-bit address in the API example (0x1234) is sent in little endian byte order (0x3412). |
| 24 | ||
| 25 |
Example
The following example shows how you can use the Explicit API frame to send an “Active Endpoints” request to discover the active endpoints on a device with a 16-bit address of 0x1234.
|
Frame data fields |
Offset |
Example |
|---|---|---|
|
Start delimiter |
0 |
0x7E |
|
Length |
MSB 1 |
0x00 |
|
LSB 2 |
0x17 |
|
|
Frame type |
3 |
0x11 |
| Frame ID | 4 | 0x01 |
|
64-bit destination address
|
MSB 5 |
0x00 |
|
6 |
0x00 |
|
|
7 |
0x00 | |
|
8 |
0x00 | |
|
9 |
0x00 | |
|
10 |
0x00 | |
|
11 |
0xFF | |
|
LSB12 |
0xFF | |
|
16-bit Destination Network Address |
MSB 13 |
0xFF |
| LSB 14 |
0xFE |
|
|
Source endpoint |
15 |
0x00 |
|
Destination endpoint |
16 |
0x00 |
|
Cluster ID |
17 |
0x00 |
|
18 |
0x05 |
|
|
Profile ID |
19 |
0x00 |
|
20 |
0x00 |
|
|
Broadcast radius |
21 |
0x00 |
|
Transmit options |
22 |
0x00 |
|
Data payload - transaction sequence number |
23 |
0x01 |
| Data payload - ZDO payload | 24 | 0x34 |
| 25 | 0x12 | |
|
Checksum |
29 |
0xA6 |
PDF
