How to use the ZigBee Device Object (ZDO)

The ZDO (occupying Endpoint 0 of each node) is a stack-level entity defined by the ZigBee Networking Specification for use in network management and information gathering. This document explains how to make use of ZDO functionality in the EmberZNet stack and/or EZSP. An example is described as well.

The ZDO, an entity in the stack, provides network management capabilities that nodes can use to learn about each other, about the network in general, or for managing certain stack-level functionality. Many features of the ZDO are required to be implemented as part of a ZigBee Certified Platform (ZCP) and are therefore available on all ZigBee/ZigBeePro devices, making them useful as an interoperable way to gather and manage system properties on a ZigBee network. The ZDO is implemented via an over-the-air messaging format known as the ZigBee Device Profile. The following basic guidelines apply to using the ZDO for network management:

• Broadcasts requests must go to broadcast mask 0xFFFD.
• Requests should always be sent to destination endpoint 0, with application profile ID 0x0000, as this indicates that the ZDO (intrinsic in the stack) should handle the message. The source endpoint generally corresponds to the portion of your application that is interested in the requested information.
• Responses to ZDO requests come from source endpoint 0, to the destination endpoint corresponding to the source used for the Request.
• If a particular ZDO request handler is not implemented in the stack, a status of EMBER_ZDP_NOT_SUPPORTED (0x84) will be returned in the response.
• Cluster ID is used to indicate the Request or Response type being sent.
• Requests can be sent as unicast, broadcast or multicast, just like any other APS frame (with optional APS acknowledgement), and responses arrive in the IncomingMessageHandler like any other incoming APS message. However, certain kinds of requests, if sent as broadcasts, will not generate a response (in the interest of network bandwidth conservation).
• "stack/include/zigbee-device-stack.h" details the frame formats for commands and responses, including which request types are supported by the EmberZNet stack. Further details about the frame formats are described in the ZigBee Device Profile (ZDP) section of the ZigBee Networking Specification (ZigBee document #053474).
• On EmberZNet API (non-EZSP) releases, utility functions (provided as source code) for generating ZDO requests and parsing certain kinds of responses can be found in "app/util/zigbee-framework/zigbee-device-library.h".
• All ZDO requests and responses begin with the transaction sequence number as the first byte of the payload. This allows a request to be matched up with a particular response.

So, as an example, let's examine the case of a Permit Joining ZDO transaction, which facilitates remote control of the PermitAssociation flag for one or more devices in the network.

For this particular transaction, zigbee-device-stack.h explains the following:

So a Permit Joining request frame would use cluster ID 0x0036, and the response would arrive with cluster ID 0x8036. For the request parameters, the “duration” byte corresponds to the argument you would ordinarily provide to the PermitJoining call in EmberZNet/EZSP (a number of seconds to allow joining, or 0x00 for always-off joining, or 0xFF for always-on joining). The “permit authentication” byte is only applicable to when the recipient of the request is the Trust Center (TC) and controls whether the TC should perform authentication or "certain devices" during future association requests.

However, as the current ZigBee Networking Specification doesn’t provide any guidelines about which "certain devices" we can trust or must validate, the EmberZNet stack simply ignores the authentication parameter in this case, so this argument in the Permit Joining Request is not significant.

Some examples (current as of EmberZNet 3.0.1) of sending this request frame via the EZSP Training-Host application follow below. (0x42 is used as an arbitrary value here for a sequence number; the application would substitute its own values in these places.)

Unicast to node 0x401C asking it to permit joining for the next 60 (0x3C) seconds:

sendunicast 0 0x401C 0x0000 0x0036 1 0 0x1140 0xFFFF 0x42 0x42 4 {42 3C 00}

This generates an APS ACK frame (because the RETRY bit is set in the APS options above) as well as an incoming unicast (Permit Joining Response) from the request’s destination signifying the result of the request:

incomingMessage
type:UNICAST profileId:0x0000 clusterId:0x8036 sourceEndpoint:0
destinationEndpoint:0 options:RETRY | ENABLE_ROUTE_DISCOVERY
groupId:0x0000 sequence:10 lastHopLqi:255 lastHopRssi:0 sender:0x401C
bindingIndex:255 addressIndex:255 messageLength:2 messageContents: 42
00

Broadcast to entire network asking it to permit joining forever (0xFF):

sendbroadcast 0xfffd 0x0000 0x0036 1 0 0x0000 0xffff 0x42 10 0x42 3 {42 FF 00}

No response is generated as a result (since there could be potentially many responders), but devices can now join at any router in the network after this broadcast request as been processed.
Hopefully, this provides a good starting point for how to use the ZDO for messaging.