The ZigBee application layer offers support for two types of network messages: ZDO (ZigBee Device Object) and ZCL (ZigBee Cluster Library).

The RapidHA serial protocol abstracts the most common messages of these types into easy-to-process formats for the Host application, thus removing the need for developers to reference ZigBee specifications in order to understand and appropriately process incoming data. Additionally, the application provides facilities for the Host to send and receive any custom ZDO or ZCL message.

ZDO Messages

ZDO messages provide facilities for a device to discover other devices, as well as the services and capabilities of those devices. Additionally, ZDO messages are used in the basic management of a ZigBee network.

RapidHA automatically handles all incoming ZDO requests. The Host retains the option of forming and transmitting custom ZDO messages, as well as receiving and processing incoming replies to those messages.

Supported ZDO Requests

The application supports the ZDO Requests listed below and will automatically generate responses for them:

• Node Descriptor Request
• Power Descriptor Request
• Simple Descriptor Request
• Active Endpoint Request
• Match Descriptor Request
• Bind Request
• Unbind Request
• Binding Table Request
• LQI Table Request
• Routing Table Request
• Leave Request
• Network Address Request
• IEEE Address Request
• Permit Joining Request

Some common ZDO Messages and their respective Command ID’s are listed below:

ZDO Messages

Custom ZDO Messages

The application allows the Host to create and transmit custom ZDO unicast and ZDO broadcast messages.

The transmit status of a custom ZDO message is relayed to the Host via the ZDO Send Status command. Additionally, the Host may configure the Response Options of a custom ZCL Message to specify that it expects an APS Acknowledgement response to be relayed to it via the ZCL APS Ack command.

If a custom ZDO message constitutes a request (i.e., an explicit query for data from another device on the network), the Host may configure the Response Options of the message to require that the Module relay the response to it on reception, which it will do as a ZDO Response Received command; otherwise, the application will not automatically pass the response through to the Host.   

ZCL Messages

The application allows the Host to form and transmit any custom ZCL unicast, multicast or broadcast commands, as well as receive responses to ZCL requests.

ZCL Messages are either profile-wide general commands (e.g., Attribute Read / Attribute Write) or cluster-specific commands (e.g., Move to Level, On/Off State Update, etc.).

Incoming ZCL general commands (e.g., ZCL Read Attribute Request) are handled automatically by the application. Incoming cluster-specific commands, if recognized by the application, are relayed to the Host as cluster call-back commands (e.g., Move to Level, On/Off State Update, etc.).

If the application does not recognize an incoming cluster-specific command, the message is dropped and not relayed to the Host. The Host may circumvent this behaviour if it has foreknowledge of the unknown messages it may receive. This is done by registering the messages for direct pass-through for reception as ZCL Passthru Message commands.

Custom ZCL Messages

The application allows the Host to create and transmit custom ZCL unicast, ZCL multicast and ZCL broadcast messages.

The transmit status of a custom ZCL message is relayed to the Host via the ZCL Send Status command. Additionally, the Host may configure the Response Options of a custom ZCL Message to specify that an APS Acknowledgement is required on its reception, with the response relayed to it via the ZCL APS Ack command.

If a custom ZCL Message constitutes a Request (e.g., ZCL Read Attribute Request), the Host may configure the Response Options of the message to require that the Module relay the response to it on reception (i.e., as a ZCL Response Received command). Otherwise, the application will not automatically pass the response through to the Host.

The following list of General ZCL Commands can be sent using the custom ZCL Message feature.

Incoming ZCL Messages

The application processes incoming ZCL messages by applying the following checks and actions:

• If the message targets an endpoint or cluster that does not exist, the message is discarded.
• If the message is recognized as a response to a command issued by the Host (i.e., the Host had specified that a response was expected), the message is relayed to the Host as a ZCL Response Received command. Specifically, the application will check that Transaction Sequence Number, Cluster ID and Endpoint ID of the message match those of the original request. The application will automatically issue a Default Response on reception of the message, if required.
• If the message is a ZCL general command, the application will automatically handle a response where required.  If the incoming command resulted in a change of state to an attribute (i.e. Attribute Write), the application will notify the Host of the change with a Received Attribute Write message.
• If the message is a cluster-specific command registered by the Host for pass-through, the application will relay it to the Host as a message. The Host is responsible for issuing a response to any pass-through message it receives, where applicable.
• If the message is a cluster-specific command for which the application has native support (e.g., On/Off, Levels, etc.) the application will process the command and trigger any required cluster call-back commands (e.g., On/Off State Update, Move to Level, etc.).
• If the message is an unsupported cluster command, the message is discarded.

Supported ZCL General Commands

The application supports the ZCL general requests listed here:

• Read Attributes
• Write Attributes
• Write Attributes No Response
• Configure Reporting
• Read Reporting Configuration
• Discover Attributes
• Discover Attributes Extended
• Discover Commands Received
• Discover Commands Generated

If the value of an attribute is modified via a Attribute Write command, the application will inform the Host with a Received Attribute Write command.

Command Pass-Through Registration

The application provides facilities for the Host to register incoming commands for direct pass-through i.e., without any additional processing by the application. 

The Register Commands Passthru message is sent by the Host to the Module to create an index of those cluster commands that the Module should pass directly to the Host without additional processing. That is, the Host may specify supported commands that would otherwise result in additional action being taken by the Module on their reception, or commands not supported by the Module that would otherwise not be passed to the Host on their reception.

Specifying a Commands Count of 0x00 indicates that all received commands should be directly passed through to the Host.

A registered ZCL command is passed through to the Host as a ZCL Passthru Message command. The Host is responsible for issuing any applicable responses to a pass-through command. If a command is not recognized by the application and it not registered for pass-through, it is discarded.

Typical Communication Scenarios

The following figures depict the sequence of messages sent during certain operational scenarios during the ZCL/ZDO request/response model.

Scenario 1 (Success): This is the positive execution path. Messages are sent serially from Host to Module and Over the air from the Module to devices in the network. The module responds to the request and when it receives an OTA response from device it confirms with the Host.

Scenario 2 (Timeout): This is one of possible failure paths. Messages are sent serially from Host to Module and Over the air from the Module to devices in the network. The module responds to the request but doesn’t receive a response from the device OTA. The request times-out and the module responds to the Host with a ZCL Response Timeout.