This page describes the commands supported by the RapidHA serial protocol. The payload byte values are detailed in the command descriptions. Some commands have no payloads.

Back to Top

Utility Frames ( PH: 0x55 )

This section describes a wide range of command functionality that works on a system-wide level under the Primary Header 0x55.

Reset Command - ( PH:0x55 SH:0x00 )

The Reset command is sent from the Host to the Module, and prompts the Module to reboot. The command has no payload.

Effect on Receipt

The Module reboots.

Module Info Request Command - ( PH:0x55 SH:0x02 )

The Module Info Request command is sent from the Host to the Module to query the Module’s version and application type. This command has no payload.

Effect on Receipt

The Module will respond with a Module Info Response command.

Module Info Response Command - ( PH:0x55, SH:0x03 ) 

The Module Info Response command is sent from the Module to the Host in response to a Module Info Request command.

Payload for Module Info Response Command

Bootloader Version Request Command - ( PH:0x55, SH:0x04 )

The Bootloader Version Request command is sent from the Host to the Module and queries the module’s application bootloader version.  The Module responds with a Bootloader Version Response. The command has no payload.

Effect on Receipt

The Module will respond with a Bootloader Version Response.

  Bootloader Version Response Command - ( PH:0x55, SH:0x05 )

The Bootloader Version Response is sent by the Module after it is queried by the Host with a Bootloader Version Request. The Response contains advanced information about the current application bootloader running on the Module.

The Bootloader Type (e.g., standalone or application bootloader) is conveyed via the Module Info Response command.

Payload for Bootloader Version Response Command

Expected Host Action

None.

Application Version Count Request - ( PH:0x55, SH:0x06 )

The Application Version Count Request is sent from the Host to the Module to query the number of Application Version Strings available from the running application. The command has no payload.

Effect on Receipt

The Module will respond with an Application Version Count Response. 

Application Version Count Response - ( PH:0x55, SH:0x07 )

 The Application Version Count Response is sent from the Module to the Host. The response payload length is 1 octet.

Payload for Application Version Count Response Command

Antenna Configuration Request Command - ( PH:0x55, SH:0x23 )

The Antenna Configuration Request is sent by the Host to the Module and serves to query the Module about the hardware antenna configuration when the application is operating on the MMB Hornet platform. The command has no payload.

Effect on Receipt

The Module will respond with an Antenna Configuration Response.

Antenna Configuration Response Command - ( PH:0x55, SH:0x24 )

The Antenna Configuration Response is sent by the Module after it is queried by the Host with an Antenna Configuration Request. The payload contains the hardware antenna configuration of the MMB Hornet platform. If the application is not operating on that platform, the response indicates that antenna configuration is not supported.

Payload for Antenna Configuration Response Command

Expected Host Action

None.

  Antenna Configuration Write Command - ( PH:0x55, SH:0x25 )

The Antenna Configuration Write command is sent by the Host to the Module to select the hardware antenna configuration of the MMB Hornet platform.

Payload for Antenna Configuration Write Command

Effect on Receipt

If the application is not operating on the MMB Hornet platform, the Host will receive an Invalid Call Error in response. Otherwise, the specified hardware antenna configuration is selected.

LED Configuration Request Command - ( PH:0x55, SH:0x26 )

The LED Configuration Request is sent by the Host to the Module and serves to query the LED behavior configuration of the Telegesis LRS USB Stick or the MMB Hornet-based MMB USB Stick platforms. On these platforms, the LED may be configured to act as an indicator of the application Network State. The Module responds with an LED Configuration Response. The command has no payload.

Effect on Receipt

The Module will respond with an LED Configuration Response.

LED Configuration Response Command - ( PH:0x55, SH:0x27 )

The LED Configuration Response is received from the Module once queried by the Host with an LED Configuration Request. It conveys the LED behavior configuration of the Telegesis LRS USB Stick or MMB Hornet-based MMB USB Stick platforms. On these platforms, the LED may be configured to act as an indicator of the application Network State.

Payload for LED Configuration Response Command  

 Expected Host Action

None.

LED Configuration Write Command - ( PH:0x55, SH:0x28 )

The LED Configuration Write command is sent by the Host to the Module to set the LED behaviour configuration of the Telegesis LRS USB Stick or Hornet-based MMB USB Stick platforms. On these platforms, the LED may be configured to act as an indicator of the application Network State.

Payload for LED Configuration Write Command 

Effect on Receipt

If operating on the Telegesis LRS USB Stick or MMB USB Stick platform, the hardware LED will act as an indicator of the application Network State as described.

Serial ACK Config Write Command - ( PH:0x55, SH:0x30 )

The Serial ACK Config Write command is sent by the Host to the Module in order to enable or disable mandatory serial acknowledgements.

Payload for Serial ACK Config Write Command

Effect on Receipt

The Module shall apply the new Serial ACK Configuration.

Serial ACK Config Request Command - ( PH:0x55, SH:0x31 )

The Serial ACK Config Request command is sent by the Host to the Module in order to query the application Serial ACK Configuration. The command has no payload.

Effect on Receipt

The Module shall respond with a Serial ACK Config Response.

Serial ACK Config Response Command - ( PH:0x55, SH:0x32 )

The Serial Ack Config Response is sent by the Module to the Host in response to a Serial ACK Config Request. The command conveys the current Serial ACK Configuration of the application indicating whether serial acknowledgements between the Host and Module are mandatory or not.

Payload for Serial ACK Config Response Command

Manufacturer ID Request Command - ( PH:0x55, SH:0x40 )

The Manufacturer ID Request is sent by the Host to the Module to query the application Manufacturer ID. This ID is included in the application Node Descriptor and is also applied when querying an OTA server for new firmware images. This command has no payload.

 Effect on Receipt

The Module shall respond with a Manufacturer ID Response.

Manufacturer ID Response Command - ( PH:0x55, SH:0x41 )

The Manufacturer ID Response is sent by the Module to the Host in response to a Manufacturer ID Request. The command conveys the Manufacturer ID of the application.

Payload for the Manufacturer ID Response Command

Expected Host Action

None.

Manufacturer ID Write Command - ( PH:0x55, SH:0x42 )

The Manufacturer ID Write command is sent by the Host to the Module to set the Manufacturer ID of the application. This ID is included in the application Node Descriptor and is also applied when querying an OTA server for new firmware images. The command payload is equivalent to the Manufacturer ID Response.

Payload for the Manufacturer ID Write Command

The Manufacturer ID may only be configured during the Startup Synchronization phase and prior to forming or joining a network. If the Manufacturer ID Write command is issued after the network is formed or joined, the Module will send a Status Response Command to the Host with 0x01 (Invalid Call) in its payload.

The Manufacturer ID is stored in non-volatile memory and therefore only needs to be set once. If the value 0xFFFF is used as the command’s parameter, then the Manufacturer ID will be the default value, which is 0x109A, the MMB Manufacturer ID.

Status Responses to Manufacturer ID Write Command

Effect on Receipt

The Module shall apply the new Manufacturer ID and store it to non-volatile memory.

Sleepy Parameters Request CMD Command - ( PH:0x55, SH:0x50 )

The Sleepy Parameters Request CMD command is sent by the Host to the Module to query the application’s sleepy parameters. The command has no payload. See Sleepy Devices for more information about the Module’s sleepy behavior.

Effect on Receipt

The Module shall respond with a Sleepy Parameters Response CMD command.

Sleepy Parameters Response CMD Command - ( PH:0x55, SH:0x51 )

The Sleepy Parameters Response CMD command is sent by the Module to the Host in response to a Sleepy Parameters Request CMD. The command conveys the sleepy parameters of the application. See Sleepy Devices for more information about the Module’s sleepy behavior.

Payload for Sleepy Parameters Response CMD Command

Sleepy Parameters Write CMD Command - ( PH:0x55, SH:0x52 )

The Sleepy Parameters Write CMD command is sent by the Host to the Module to modify the sleepy parameters. The command allows for multiple attributes to be written for a device in one operation. The value 0xFF is an invalid parameter for all byte fields in the payload; it will not be written. See Sleepy Devices for more information about the Module’s sleepy behaviour.

Payload for Sleepy Parameters Write CMD Command

Effect on Receipt

The Module will send a Status Response to the Host. The table below lists the possible return values for this command.

Status Responses to Sleepy Hibernate Duration Write CMD Command

Sleepy Hibernate Duration Request CMD Command - ( PH:0x55, SH:0x53 )

The Sleepy Hibernate Duration Request CMD command is sent by the Host to the Module to query only the App Hibernate Duration parameter. This command is provided to read the App Hibernate Duration parameter without reading the other sleepy parameters. The command has no payload. See Sleepy Devices for more information about the Module’s sleepy behavior.

Effect on Receipt

The Module shall respond with a Sleepy Hibernate Duration Response CMD frame.

Sleepy Hibernate Duration Response CMD Command - ( PH:0x55, SH:0x54 )

The Sleepy Hibernate Duration Response CMD is sent by the Module to the Host in response to a Sleepy Hibernate Duration Request CMD. The command conveys the Module's hibernation duration; i.e., the App Hibernate Duration parameter. See Sleepy Devices for more information about the Module’s sleepy behavior.

Payload for the Sleepy Hibernate Duration Response CMD Command

  Sleepy Hibernate Duration Write CMD Command - ( PH:0x55, SH:0x55 )

The Sleep Hibernate Duration Write Command is sent by the Host to the Module to modify the parameter App Hibernate Duration. See Sleepy Devices for more information about the Module’s sleepy behavior.

Payload for the Sleepy Hibernate Duration Write CMD Command

 Effect on Receipt

The Module will return a Status Response to the Host. The table below lists the possible return values for this command.

Status Responses to Sleepy Hibernate Duration Write CMD Command

Sleep Control Stay Awake Duration Write - ( PH:0x55, SH:0x58 )

The Sleep Control Stay Awake Duration Write command is issued by the Host to the Module and serves to impose a duration for which the application will stay awake. This allows the Host to override the standard sleep cycle of the application when desired.

Specifying a Stay Wake Duration of 0 will return the application to the sleep state upon the subsequent application tick, provided there are no pending tasks.

Sleep Control Stay Awake Duration Read - ( PH:0x55, SH:0x59 )

The Sleep Control Stay Awake Duration Read command is issued by the Host to the Module to query the Stay Awake Duration of the application. The command has no payload.

Sleep Control Stay Awake Duration Response - ( PH:0x55, SH:0x5A )

The Sleep Control Stay Awake Duration Read Response is issued by the Module to the Host in response to a Sleep Control Stay Awake Duration Read command. It conveys the remaining Stay Awake Duration of the application, in milliseconds.

Status Response Command - ( PH:0x55, SH:0x80 )

The Status Response command may be issued either by the Module to the Host, or by the Host to the Module, in order to acknowledge the reception of a command.

Payload for Status Response Command

Sleep Control Wakeup - ( PH:0x55, SH:0xA0 )

The Sleep Control Wakeup frame is issued by the Host to the Module to wake the application when it is sleeping. On reception, the application will stay awake for a default duration of 50ms. It is expected that the Host will stuff the 19-byte payload with all 0xFF’s.

The Host may then either send a serial message within the 50ms wake window or issue the Sleepy Control Stay Awake Duration Write command to force the application stay awake for a longer specified duration.

Error Command - ( PH:0x55, SH:0xE0 )

The Error frame is sent by the Module to the Host to report an application error.

Payload for Error Command

Expected Host Action 

Error conditions are reported for diagnostic purposes. Depending on the given error received, there may or may not be an expected action for the Host to take in response.

 Back to Top

Network Commissioning Frames (0x01)

The Network Commissioning command set allows the Host to prompt the Module to either form a network or join an existing network. A third option exists for performing HA 1.2 EZ-Mode Commissioning, defined as an automated process that prompts the application to join an existing network and, failing to find one, to form its own.

Join Network Command - ( PH:0x01, SH:0x00 )

The Join Network command is sent by the Host to the Module to prompt the Module to scan for and join an existing network.

Payload for Join Network Command

Effect on Receipt

The Module will sequentially scan all channels defined by the Channel Mask. The Module will attempt to join any network with an open Permit Join window and matching the PAN IDs as specified in the command payload. If a join attempt fails, the Module will resume scanning until it has tried all available and applicable networks. The possible Status Responses generated by the Module in response to this command are listed in the following table.

Status Responses to Join Network Command

Form Network Command - ( PH:0x01, SH:0x01 )

The Form Network command is sent by the Host to the Module to prompt the latter to form a network. Additionally on reception of this command, the application ZigBee Device Type is set to Coordinator.

Payload for Form Network Command

Effect on Receipt

The Module will sequentially scan all channels defined by the channel mask and select the one with the least interference. It will then attempt to form a network with the Short and Extended PAN ID’s specified by the Host. Otherwise, if the Host has enabled the Auto Options for those parameters, the Module will generate randomized PAN ID’s that do not conflict with any other network within range.

The possible Status Responses generated by the Module in response to this command are listed in the following table. Additionally, when a network is successfully formed, the Module will inform the Host by issuing a Network Status Response indicating the new application network state.

Status Responses to Form Network Command

Permit Join Command - ( PH:0x01, SH:0x03 )

The Permit Join command is sent by the Host to the Module in order to prompt the Module to open its Permit Join window for a given duration.

Payload for Permit Join Command

Effect on Receipt

When the application ZigBee device type is configured as an end device, the Module will ignore this command. When configured as a router, the Module will open its Permit Join window for the specified Permit Join Duration. When configured as a coordinator, the Module will open its Permit Join window for the specified Permit Join Duration and will additionally broadcast a message to prompt all routers on its network to also permit joining.

Leave Network Command - ( PH:0x01, SH:0x04 )

The Leave Network command is sent by the Host to the Module in order to prompt the Module to leave the network to which it is currently joined. The command has no payload.

Effect on Receipt

The application will leave the network and clear all data pertaining to that network from its non-volatile memory. The Host must apply this command with caution, as once the Module is prompted to leave a network it will be unable to join that network again until it is re-commissioned with the network coordinator.

Rejoin Network Command - ( PH:0x01, SH:0x05 )

The Rejoin Network command is sent by the Host to the Module in order to prompt the latter to rejoin the network to which it is currently joined. Though the Module may automatically engage in Rejoin behavior when having lost the connection to the network (i.e., as determined by the Network Heartbeat), this command provides facilities for the Host to manually engage the process (i.e., to re-initiate Service Discovery and Binding). The command has no payload.

Effect on Receipt

The application will enter the Rejoin state, alternating between Secure Rejoin and Trust Center Rejoin until it successfully rejoins the network.

Network Status Request Command - ( PH:0x01, SH:0x08 )

The Network Status Request is sent by the Host to the Module to query the application Network State. The Host is not required to issue this command, as the Module will automatically issue a Network Status Response on any change of the application Network State. The command has no payload.

Effect on Receipt

The Module will respond with a Network Status Response.

Network Status Response Command - ( PH:0x01, SH:0x09 )

The Network Status Response is sent by the Module to the Host, either as a response to the Network Status Request command, or automatically upon a change to the application Network State or Permit Join Duration (i.e., on transition from non-zero to zero or vice versa).

Payload for Network Status Response Command

Trust Center Device Update Command - ( PH:0x01, SH:0x10 )

When the application ZigBee device type is configured as a coordinator and a network has been formed, the Trust Center Device Update command is sent by the Module to the Host when any device attempts to join or leave that network.

Payload for Trust Center Device Update Command

Event Triggers explained:

MAC Association -- a device's attempt to join the network. Seeing this does not mean that a device successfully joined, however. The indication for when the device joining successfully is when you see Device Announce.
Secure Rejoin -- this is a device rejoining the network using the network key
Trust Center Rejoin -- this is a device rejoining the network without the network key. It needs to get the network key from the Trust Center, which sends the network key encrypted using the trust center key.
Network Leave -- a device leaving the network.  

Network Auto Join Command - ( PH:0x01, SH:0x11 )

The Network Auto Join command is sent by the Host to the Module to prompt the Module to scan all channels for X number of retries and with Y number of seconds delay between each scan.

The average scan period is roughly 8 seconds. Sending a Leave Network command terminates the scan loop.

Payload for Network Auto Join Command

Effect on Receipt

The Module will perform a scan on all channels for X number of retries with Y number of seconds delay between each scan. The Module will attempt to join a network on the channel with the strongest signal strength/lowest noise ratio. If multiple networks exist on the that channel, the Module will join the first viable network that responds.

Status Responses to Network Auto Join Command

Network Reset Auto Join Command - ( PH:0x01, SH:0x12 )

The Network Reset Auto Join command is sent by the Host to the Module to prompt it to leave any network to which it may be joined and then scan all channels for X number of retries and with Y number of seconds of delay between each scan.

The average scan period is roughly 8 seconds. Sending a Leave Network command terminates the scan loop.

Payload for Network Reset Auto Join Command

Effect on Receipt

The Module will leave any network to which it belongs. The Module will then perform a scan on all channels for X number of retries with Y number of seconds delay between each scan. The Module will attempt to join a network on the channel with the strongest signal strength/lowest noise ratio. If multiple networks exist on that channel, the Module will join the first viable network that responds.

Status Responses to Network Reset Auto Join Command

Back to Top

Security Configuration Frames (0x02) 

This section describes commands that set and report on security keys.

Preconfigured Key Option Write Command - ( PH:0x02, SH:0x00 )

The Preconfigured Key Option Write command is sent by the Host to the Module and serves to dictate which key the application will use when attempting to join a network; either the Preconfigured Link Key or the key derived from Installation Code.

The application default is to join with the Preconfigured Link Key. This configuration is not stored in non-volatile memory and should therefore be set prior to initiating any Scan and Join activity (i.e., while in the Network Down state) and subsequent to a reset or power-cycle.

Payload for Preconfigured Key Option Write Command

Effect on Receipt

The Module will apply the chosen key the next time it attempts to join a network. This command only has an effect while Module is in the Network Down state and therefore prior to initiating any scan and join activity.

Preconfigured Key Option Request Command - ( PH:0x02, SH:0x01 )

The Preconfigured Key Option Request is sent by the Host to the Module to query the current application Preconfigured Key Option. The Module will respond with a Preconfigured Key Option Response. The command has no payload.

Preconfigured Key Option Response Command - ( PH:0x02, SH:0x02 )

The Preconfigured Key Option Response is sent by the Module to the Host when queried with a Preconfigured Key Option Request. The command has the same payload as the Preconfigured Key Option Write command.

Payload for Preconfigured Key Option Response Command

Install Code Request Command - ( PH:0x02, SH:0x03 )

The Install Code Request frame is sent by the Host to the Module to query the application Installation Code. The Module responds with an Install Code Response. It should be noted that the Installation Code is assigned to the Module at production time and cannot be modified. The command has no payload.

Install Code Response Command - ( PH:0x02, SH:0x04 )

The Install Code Response frame is sent by the Module to the Host when queried with an Install Code Request. 

Payload for Install Code Response Command

Link Key Write Command - ( PH:0x02, SH:0x05 )

The Link Key Write command is sent by the Host to the Module in order to set the application Preconfigured Link Key. The Host may only set the Preconfigured Link Key while the application is in the Network Down state.

If the Host subsequently forms a network as a coordinator, the key will be applied as the Global Trust Center Link Key. Otherwise, if the Host joins a network as either a router or end device, the key will be applied as the Joining Key.

The Preconfigured Link Key is not stored in non-volatile memory and must therefore be set prior to forming or joining a network subsequent to a Reset or power-cycle. If the Host does not manually set the key, the application will use the default Preconfigured Link Key specified by the ZigBee Home Automation Specification.

Payload for Link Key Write Command

Effect on Receipt

The Module will apply this Preconfigured Link Key when it either forms or joins a network, the latter when the Joining Key Option corresponds to Preconfigured Link Key.

Link Key Request Command - ( PH:0x02, SH:0x06 )

The Link Key Request is sent by the Host to the Module to request the current application Link Key. The Module responds with a Link Key Response. When the Module is configured as a coordinator, it will return the Global Trust Center Link Key. When the Module is otherwise configured and not joined to a network, it will return the Preconfigured Link Key and likewise, when joined to a network, it returns the current Trust Center Link Key assigned to it. The command has no payload.

Link Key Response Command - ( PH:0x02, SH:0x07 )

The Link Key Response is sent by the Module to the Host when queried with a Link Key Request. The command has the same payload as the Link Key Write command.

Payload for Link Key Response Command

Network Key Write Command - ( PH:0x02, SH:0x08 )

The Network Key Write command is sent by the Host to the Module in order to set the application Preconfigured Network Key. The Host may only set the Network Key while the application is in the Network Down state, after which the key will be automatically randomized.

The Network Key is only applied if the Host subsequently forms a network as a coordinator. If serving as a router or end device, the application will receive a Network Key from the network Trust Center.

The Network Key is not stored in non-volatile memory and must therefore be set prior to forming a network subsequent to a Reset or power-cycle. If the Host does not manually set the key, the application will generate a random value for it upon forming a network.

Payload for Network Key Write Command

Network Key Request Command - ( PH:0x02, SH:0x09 )

The Network Key Request command is sent by the Host to the Module to query the application Network Key. The Module will respond with a Network Key Response. If the application has not formed a network, the response will convey the Preconfigured Network Key. Otherwise, the response will convey the current Network Key. The command has no payload.  

Network Key Response Command - ( PH:0x02, SH:0x0A )

The Network Key Response command is sent by the Module to the Host when queried with a Network Key Request. The command has the same payload as Network Key Write command.

Payload for Network Key Response Command

Back to Top

ZigBee Support Configuration Frames (0x03)

This section describes the commands used to configure RapidHA’s IEEE functional device type, as well as the endpoints, clusters and attributes that will logically exist on that device.

Device Type Write Command - ( PH:0x03, SH:0x00 )

The Device Type Write command is sent by the Host to the Module in order to configure the application’s IEEE functional device type. The Host is only required to issue this command once after synchronizing with a factory default Module for the first time, as the configuration is preserved in the application’s non-volatile memory.

The Module may be configured to behave as either a Full-Function Device (FFD) or Reduced-Function Device (RFD). An FFD has facilities for routing network messages as either a coordinator or a router, while an RFD may only join a network as a non-routing end node

If the Host configures the Module as an RFD, it may additionally configure the application to serve as either a non-sleepy or sleepy end device, with the latter configuration serving to conserve power should the given device be battery powered or otherwise consumption-sensitive.

Payload for Device Type Write Command

Effect on Receipt 

If the command is valid, the Module will update the setting and save it to non-volatile memory while also relaying a Device Type Response to the Host to confirm the setting. The following table lists the possible Status Responses on reception of the command.

Status Responses to Device Type Write Command

Device Type Request Command - ( PH:0x03, SH:0x01 )

The Device Type Request is sent by the Host to the Module in order to query the application IEEE functional device type. The command has no payload.

Effect on Receipt

The Module will respond with a Device Type Response.

Device Type Response Command - ( PH:0x03, SH:0x02 )

The Device Type Response is sent by the Module to the Host in response to a Device Type Request.

Payload for Device Type Response Command

  Add Endpoint Command - ( PH:0x03, SH:0x10 )

The Add Endpoint command is sent by the Host to the Module in order to configure an application endpoint. This includes defining the Endpoint ID, Profile ID, Device ID, Device Version and the lists of server and client clusters supported on that endpoint.

Every known cluster included in the command (i.e., those already defined in the ZCL or HA specifications) will be automatically populated by the application with its mandatory attributes, which will likewise be enabled.

The Add Endpoint command may also be used to update the definition of an existing endpoint by specifying its Endpoint ID in the payload. If an update operation does not include previously specified clusters, those clusters are removed along with their associated attributes.

Payload for Add Endpoint Command

 Effect on Receipt 

The Module will verify that the Endpoint ID is valid and that there is sufficient memory for the new endpoint and its associated clusters. Likewise, the application will automatically configure all mandatory attributes for specified known clusters. The following table  lists the possible Status Responses on reception of the command.

Status Responses to Add Endpoint Command

Endpoint List Request Command - ( PH:0x03, SH:0x11 )

The Endpoint List Request is sent by the Host to the Module in order to query the application endpoint list. The Host may apply this command to verify the configuration of application endpoints after having created them. The command has no payload.

Effect on Receipt 

The Module will respond with an Endpoint List Response conveying a list of Endpoint ID’s. There are no Status Responses issued on reception of this command.

  Endpoint List Response Command - ( PH:0x03, SH:0x12 )

The Endpoint List Response is sent by the Module to the Host in response to an Endpoint List Request. The command conveys the Endpoint ID’s of all the configured endpoints supported by the application.

Payload for Endpoint List Response Command

Expected Host Action 

None.

  Endpoint Descriptor Request Command - ( PH:0x03, SH:0x13 )

The Endpoint Descriptor Request is sent by the Host to the Module in order to query the definition of a given application endpoint. The Host may apply this command to verify the full configuration of an application Endpoints after having creating it.

Payload for Endpoint Descriptor Request Command

Effect on Receipt 

The Module will respond with an error if it does not support the specified endpoint. Otherwise, it relays the appropriate Endpoint Descriptor Response to the Host. The following table lists the possible Status Responses on reception of the command.

Status Response to Endpoint Descriptor Request Command

  Endpoint Descriptor Response Command - ( PH:0x03, SH:0x14 )

The Endpoint Descriptor Response is sent by the Module to the Host in response to an Endpoint Descriptor Request.

Payload for Endpoint Descriptor Response Command

 Expected Host Action

None.

  Add Attributes to Cluster Command - ( PH:0x03, SH:0x20 )

The Add Attribute to Cluster command is sent by the Host to the Module in order to append attribute definitions to a configured application cluster. The command may specify as many attributes as the maximum payload capacity of a RapidHA frame allows. For a cluster with large number of attributes, the command may be issued as many times as required.

Please note the application automatically adds mandatory attributes to all configured known clusters, i.e., those already defined in the ZCL or HA specifications. Thus, a simple Host implementation may not need to send this command, or only send it to add optional attributes.

Payload for Add Attributes to Cluster Command

Attribute Definition Record Format

Effect on Receipt 

The Module will submit the payload of the received command to a series of checks:

• • That there is sufficient memory available for all specified attributes
  • That the target endpoint and cluster exist
  • That the Data Type of each specified attribute is valid
  • That the Payload is complete

On completion of these checks, the application will issue an appropriate Status Response indicating success or failure, as conveyed in the following table. Should the response indicate an error, the command will not take effect. Furthermore, the application will ignore duplicate definitions (i.e. corresponding exactly to an existing configuration) but will update existing attributes if the configuration specified is different. Each configured attribute is automatically populated with the default ZCL value for its given Data Type.

Status Responses to Add Attributes to Cluster Command

  Attribute List Request Command - ( PH:0x03, SH:0x21 )

The Attribute List Request is sent by the Host to the Module in order to query the attributes on a given application cluster and endpoint.

Payload for Attribute List Request Command

 Effect on Receipt 

If the Module supports the target endpoint and cluster, it will relay an appropriate number of Attribute List Response commands to the Host. Otherwise, a Status Response is generated indicating an error, as described in the following table.

 Status Response to Attribute List Request Command

  Attribute List Response Command - ( PH:0x03, SH:0x22 )

The Attribute List Response command is sent by the Module to the Host in response to an Attribute List Request. The message conveys a list of attributes supported on the cluster and endpoint queried. Should the number of attributes exceed the payload capacity of the message, they will be conveyed as multiple responses, or pages.

Payload for Attribute List Response Command

 Expected Host Action 

None.

 Attribute Request Command - ( PH:0x03, SH:0x23 )

The Attribute Request is sent by the Host to the Module in order to query the definition and value of an attribute on a given cluster and endpoint.

 Payload for Attribute Request Command

 Effect on Receipt 

If the Module supports the requested attribute, it will respond with an Attribute Response. Otherwise, the application will relay a Status Response indicating an error, as described in the following table.

Status Response to Attribute Request Status

Attribute Response Command - ( PH:0x03, SH:0x24 )

An Attribute Response is sent by the Module to the Host in response to an Attribute Request.

 Payload for Attribute Response Command 

 Expected Host Action 

None.

  Attribute Write Command - ( PH:0x03, SH:0x25 )

The Attribute Write command is sent by the Host to the Module in order to set the value of an existing attribute residing on a target cluster and endpoint.

 Payload for Attribute Write Command 

 Effect on Receipt

If the attribute is supported, the specified Attribute Type matches and the Attribute Value is the correct size, the Module will return a Status Response indicating Success. Otherwise, the response will indicate an error. The possible Status Responses are listed in the following table.

Status Responses to Attribute Write Command

Attribute Report Passthrough Control - ( PH:0x03, SH:0x26 )

The Attribute Report Passthrough Control message is sent from the Host to the Module. The payload length is 1 octet.

Payload for Attribute Report Passthrough Control

Effect on Receipt

When enabled, RapidHA will pass all ZCL Attribute Reports through via the ZCL Passthrough functionality.

  Clear Endpoint Config Command - ( PH:0x03, SH:0x30 )

The Clear Endpoint Config command is sent by the Host to the Module in order to wipe all applied configurations of endpoints, clusters, attributes and registered pass-through commands. The command has no payload.

Effect on Receipt

The Module shall clear all application endpoints, clusters, attributes and registered pass-through commands.

Register Commands Passthru Command - ( PH:0x03, SH:0x80 )

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 through 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.

 Payload for Register Commands Passthru

Effect on Receipt

The Module will register the given commands in non-volatile memory and refer to the list on reception of ZCL commands. The following table lists the possible Status Responses on reception of the command.

Status Responses to Register Commands Passthru Command

Back to Top

ZDO Message Frames (0x04)

This section describes the two ways, unicast and broadcast, for the Host to send a ZDO command. It also describes the commands sent by the Module to communicate ZDO-level information to the Host.

Send ZDO Unicast Command - ( PH:0x04, SH:0x01 )

The Send ZDO Unicast command is sent by the Host to the Module in order to prompt the Module to send a ZDO message to a single destination node. The command configures the following options:

• custom sequence numbers
• reception of APS ACK
• reception of ZDO Response Received

Payload for Send ZDO Unicast Command

Effect on Receipt

The Module will attempt to issue the ZDO message over the network. The status of the transmission and its assigned sequence number will be relayed to the Host via a ZDO Send Status command.

To know whether the destination node has successfully received a message, the Host should enable reception of APS ACK status messages via the Response Options field. On reception the Module relays these messages to the Host as ZDO APS Ack commands.

If the given message is a request (e.g., ZDO Bind Request or ZDO Simple Descriptor Request) and the Host expects a response, it should enable the option to receive a ZDO Response Received, via the Response Options field. On reception of a message with a matching sequence number, the Module will relay the response to the Host via the ZDO Response Received command. If no response is received within a given interval, the Module will instead issue a ZDO Response Timeout command to the Host.

Send ZDO Broadcast Command - ( PH:0x04, SH:0x02 )

The Send ZDO Broadcast command is sent by the Host to the Module to prompt the Module to broadcast a ZDO Message across the network.  

Payload for Send ZDO Broadcast Command

Effect on Receipt

The Module will try to broadcast the message over the network. The status of the transmission and its assigned sequence number will be relayed to the Host via a ZDO Send Status command.

ZDO Send Status Command - ( PH:0x04, SH:0x03 )

The ZDO Send Status message is sent by the Module to the Host after the transmission of a Send ZDO Unicast or Send ZDO Broadcast. The message conveys the success or failure of the transmission. If the Status indicates Success, the message will also convey a value for the Transaction Sequence Number assigned to it.

Payload for ZDO Send Status Command

Expected Host Action

No action is expected from the Host as the command is for notification purposes only. The Host may choose to display the Status in some manner, or it may also choose to re-send the message if the Status indicates an error occurred.

The Host also retains the option to store the Transaction Sequence Number associated with any outgoing message, such that it may match received ZDO Send Status messages to the requests that triggered them.

ZDO APS Ack Command - ( PH:0x04, SH:0x04 )

The ZDO APS Ack command is sent by the Module to the Host on reception of an equivalent acknowledgement from the network, triggered by the initial transmission of a ZDO message that required an APS Ack among its Response Options. The Module will also generate the command when a given acknowledgment is not received and therefore times out.

Payload for ZDO APS Ack Command

Expected Host Action

No action is expected from the Host. The command is for notification purposes only. If an APS Ack times out, the Host retains the option of retransmitting the original message.

ZDO Response Received Command - ( PH:0x04, SH:0x05 )

The ZDO Response Received command is sent by the Module to the Host on reception of ZDO Message from the network. That is, the command is generated if the Host configured an outgoing Send ZDO Unicast or Broadcast request with Response Options indicating that a response is expected (i.e. enable reception of ZDO Response Received with corresponding Transaction Sequence Number, though the application will also verify the Source Node ID and Command ID). 

Payload for ZDO Response Received Command

Expected Host Action

None.

ZDO Response Timeout Command - ( PH:0x04, SH:0x06 )

The ZDO Response Timeout command is sent by the Module to the Host when an expected ZDO Response Received command to an outgoing Send ZDO Unicast or Send ZDO Broadcast is not received within a given interval after transmission. The fixed timeout period is 10 seconds.

Note: When a Send ZDO Broadcast command is sent from the Host to the Module, the Module will open a receive window to listen for incoming responses. Once the Module is no longer listening for responses, it will also send a ZDO Response Timeout command back to the Host to signify that the receive window is closed.

Payload for ZDO Response Timeout Command

Expected Host Action

None. The Host retains the option of retransmitting the original message or may otherwise register an error condition.

ZDO Device Announce Received Command - ( PH:0x04, SH:0x1E )

The ZDO Device Announce Received frame is sent by the Module to the Host when a new device announces itself on the network.

Payload for ZDO Device Response Received Command

Back to Top

ZCL Message Frames (0x05)

This section describes the three ways, unicast, multicast and broadcast, available to the Host to send a ZCL command. In addition, it describes the commands used by the Host to read and write attributes that were previously configured using the ZigBee Support Configurations commands. This section also includes commands sent from the Module to convey responses and statuses from commands previously sent by the Host. It also describes the command used by the Module to pass through ZCL commands that have been registered by the Host using the Register Commands Passthru command.

Send ZCL Unicast Command - ( PH:0x05, SH:0x00 )

The Send ZCL Unicast command is sent by the Host to the Module in order to transmit a custom ZCL message to a target node. The command provides facilities for configuring the Encryption Level of the message, either with Network or Network + APS Encryption, as well as available Response Options, including custom sequence numbers, requiring an APS ACK or enabling processing of a corresponding response with a matching transaction sequence number.

Payload for Send ZCL Unicast Command

Effect on Receipt

The Module will attempt to issue the ZCL message over the network. The status of the transmission and its assigned sequence number will be relayed to the Host via a ZCL Send Status command.

If the Host wishes to know whether the Destination Node has successfully received a message, it should enable reception of APS ACK status messages via the Response Options field. On reception the Module relays these messages to the Host as ZCL APS Ack commands.

If the given message is a request (e.g., Read Attribute Request, Add Group, etc.) and the Host expects a response, it should enable the option to receive a ZCL Response Received command, via the same field. On reception of a message with a matching sequence number, the Module will relay the response to the Host via the ZCL Response Received command. If no response is received within a given interval, the Module will instead issue a ZCL Response Timeout command to the Host.

Send ZCL Multicast Command - ( PH:0x05, SH:0x01 )

The Send ZCL Multicast command is sent by the Host to the Module in order to prompt the latter to multicast a ZCL Message to a select Group of target devices on the network. Unlike Send ZCL Unicast messages, multicast messages cannot be APS-encrypted; that is, they are encrypted on the Network layer only.

Payload for Send ZCL Multicast Command

Effect on Receipt

The Module will try to transmit the message over the network, for reception and processing by the devices in the target Group. The status of the transmission and its assigned sequence number will be relayed to the Host via a ZCL Send Status command.

Send ZCL Broadcast Command - ( PH:0x05, SH:0x02 )

The Send ZCL Broadcast command is sent by the Host to the Module in order to prompt the latter to broadcast a ZCL Message to the network. Unlike Send ZCL Unicast messages, broadcast messages cannot be APS-encrypted; they are encrypted on the Network layer only.

Payload for Send ZCL Broadcast Command

The Module will try to broadcast the message over the network. The status of the transmission and its assigned sequence number will be relayed to the Host via a ZCL Send Status command.

ZCL Send Status Command - ( PH:0x05, SH:0x03 )

The ZCL Send Status message is sent by the Module to the Host after the transmission of a Send ZCL Unicast, Send ZCL Multicast or Send ZCL Broadcast. The message conveys the success or failure of the preceding transmission. If the Status indicates success, the message will also convey a value for the Transaction Sequence Number assigned to it.

Payload for ZCL Send Status Command

Expected Host Action

No action is expected of the Host as the command is for notification purposes only. The Host may choose to display the Status in some manner, or it may also choose to re-send the message if the Status indicates an error occurred.

The Host also retains the option to store the Transaction Sequence Number associated with any outgoing message, such that it may match received ZCL Send Status messages to the requests that triggered them.

ZCL APS Ack Command - ( PH:0x05, SH:0x10 )

The ZCL APS Ack command is sent by the Module to the Host on reception of an equivalent acknowledgement from the network, triggered by the initial transmission of a ZCL message that required an APS Ack among its Response Options. The Module will also generate the command when a given acknowledgment is not received and therefore times out.

Payload for ZCL APS Ack Command

 Expected Host Action

No action is expected from the Host. The command is for notification purposes only. If an APS Ack times out, the Host retains the option of retransmitting the original message.

ZCL Response Received Command - ( PH:0x05, SH:0x11 )

The ZCL Response Received command is sent by the Module to the Host on reception of ZCL message from the network. That is, the command is generated if the Host had configured an outgoing Send ZCL Unicast or Send ZCL Broadcast with Response Options indicating that a response is expected (i.e. enable reception of ZCL Response Received with corresponding Transaction Sequence Number, though the application will also verify the Source Node ID and Command ID).

Payload for ZCL Response Received Command

 Expected Host Action

None.

ZCL Response Timeout Command - ( PH:0x05, SH:0x12 )

The ZCL Response Timeout command is sent by the Module to the Host when an expected ZCL Response Received to an outgoing Send ZCL Unicast or Broadcast request is not received within a given interval after transmission. The fixed timeout period is 10 seconds.

Payload for ZCL Response Timeout Command

Expected Host Action

None. The Host retains the option of retransmitting the original message or may otherwise register an error condition.

Received Attribute Write Command - ( PH:0x05, SH:0x14 )

The Received Attribute Write command is sent by the Module to the Host on reception of a Attribute Write command from the source node on the network. The command serves to inform the Host of a change to the value of an attribute along with source of the change and the value itself.

Payload for Received Attribute Write Command

Expected Host Action

None. The Host retains the option to handle a change to an attribute value in any desired manner.

 ZCL Passthru Message Command - ( PH:0x05, SH:0x20 )

The ZCL Passthru Message command is sent by the Module to the Host on reception of a ZCL Message which has been registered by the Host using the Register Commands Passthru facility (that is, to prevent the application from processing the command in order to pass it directly to the Host; see the Register Commands Passthru command).

Payload for ZCL Passthru Message Command

ZCL Read Attribute Request Command - ( PH:0x05, SH:0x30 )

The ZCL Read Attribute Request command is sent from the Host to the Module to query attributes on a target network device. The command may be used to query multiple attributes on a cluster, with the subsequent responses relayed to the Host one attribute at a time.

Payload for ZCL Read Attribute Request Command

Effect on Receipt

The Module will transmit the query to the target device. The response is forwarded to the Host as a ZCL Read Attribute Response. If the response conveys multiple attributes, the Module relays each to the Host as an individual ZCL Read Attribute Response.

The table below lists the possible error statuses returned by the Status Response for this command.

Status Responses to ZCL Read Attribute Request Command 

ZCL Read Attribute Response Command - ( PH:0x05, SH:0x31 )

The ZCL Read Attribute Response command is sent by the Module to the Host in response to a successful ZCL Read Attribute Request. A response conveys the properties of a single queried attribute. As such, if the request successfully queried multiple attributes, the Host will in turn receive multiple responses.

Payload for ZCL Read Attribute Response Command

Expected Host Action

None.

ZCL Write Attribute Request Command - ( PH:0x05, SH:0x32 )

The ZCL Attribute Write Request is sent by the Host to the Module to modify the value of an attribute on a target network device. The command allows for multiple attributes on the same endpoint and cluster to be written to in one operation.

Payload for ZCL Write Attribute Request Command

Attribute Write Record

Effect on Receipt

The Module will transmit the command to the target device. The response is forwarded to Host as a ZCL Write Attribute Response.

The table below lists the possible status return values for this command.

Status Responses to ZCL Write Attribute Request Command

ZCL Write Attribute Response Command - ( PH:0x05, SH:0x33 )

The ZCL Write Attribute Response is sent by the Module to the Host in response to a successful ZCL Write Attribute Request. The frame conveys the Overall Status of the write request. Note that if the Overall Status indicates success no Attribute Write Failed Records are included in the payload.

Payload for ZCL Write Attribute Response Command

Attribute Write Failed Record

If there are any attributes not written (i.e., the write attempt failed) then the payload of the ZCL Write Attribute Response command will contain an Attribute Write Failed Record for each one of the attributes not written.

Attribute Write Failed Record

Expected Host Action

None.

Back to Top

General Cluster Frames (0x11)

The General Clusters command set encompasses the following mandatory ZCL clusters in the general domain:

• Basic
• Identify
• Time

The mandatory commands associated with a given General Cluster are made available only if that cluster is first appended to the application endpoint configuration. For example, the Identify Start and Identify Stop commands will become available to the Host only after it configures an application endpoint with the Identify server cluster.

Received Reset to Factory Default Command - ( PH:0x011, SH:0x00 )

The Received Reset to Factory Default command is sent by the Module to the Host on reception of a Basic cluster Reset to Factory Default command from the network. The command has no payload.

Please note: RapidHA does not currently support this command. If the Host sends a Reset to Factory Default command, the Module will respond with UNSUPPORTED_CLUSTER_COMMAND (0x81) and will not trigger the Received Reset to Factory Default command.

Expected Host Action

The Host is expected to reset the values of all supported attributes to their factory defaults. If the Host possesses these values, it should apply the Attribute Write command to re-write them.

Identify Start Command - ( PH:0x011, SH:0x10 )

The Identify Start command is sent by the Module to the Host on reception of an Identify cluster Identify command from the network. Specifically, the command conveys the ID of the endpoint on which the Identify action should occur and will only be passed to the Host at its required time of execution.

Payload for Identify Start Command

Expected Host Action

The Host shall initiate its Identify action (e.g., blinking LED, etc.) on the specified endpoint.

Identify Stop Command - ( PH:0x011, SH:0x11 )

The Identify Stop command is sent by the Module to the Host on expiration of a preceding Identify Start command (i.e., when the Identify Time duration of that command has been expended) or on reception of an explicit command from the network prompting the application to stop identifying on the given endpoint.

Payload for Identify Stop Command

Expected Host Action

The Host shall stop its Identify action on the specified endpoint.

Time Client Get Time Command - ( PH:0x011, SH:0x40 )

The Time Client Get Time command is sent by the Host to the Module to query the UTC and Local Time attributes of the application. Appending the Time cluster to the application endpoint configuration enables the application Time client, which automatically synchronizes its time with the network Time server. The command has no payload.  

Effect on Receipt

The Module will respond with the Time Client Get Time Response command.

Time Client Get Time Response Command - ( PH:0x011, SH:0x41 )

The Time Client Get Time Response command is sent by the Module to the Host in response to a Time Client Get Time request. The command conveys both the current UTC and Local Time, as maintained by the application in synchronization with the network Time Server.

Payload for Time Client Get Time Response Command

Expected Host Action

The Host retains the option of using the response to maintain its own UTC and Local Time.

Time Client Time Changed Command - ( PH:0x011, SH:0x42 )

The Time Client Time Changed command is sent by the Module to the Host to inform the Host of a change to the Current UTC Time and/or Current Local Time, as retrieved from the network Time Server. The command is also generated when the application first synchronizes its time with the Time Server. The command has no payload.

Expected Host Action

The Host should update its time by performing a Time Client Get Time query.

Network Time Sync Period Write Command - ( PH:0x011, SH:0x43 )

The Network Time Sync Period Write command is sent from the Host to the Module to modify how often the Time Server will be polled by the device. The command conveys the time sync period in minutes.

By default the Time Server is polled every five minutes. This applies to all device types, including sleepy devices. Since such devices are battery-powered, it is good practice to minimize network communication when possible. Polling the Time Server every five minutes is considered excessive for a sleepy device. 

Payload for Network Time Synch Period Write Command

Network Time Sync Period Request Command - ( PH:0x011, SH:0x44 )

The Network Time Sync Period Request command is sent from the Host to the Module to read the current value for the time sync period. The command has no payload.

Effect on Receipt

The Module will respond with the Network Time Sync Period Response command, which conveys the current value of the time sync period.

Network Time Sync Period Response Command - ( PH:0x011, SH:0x45 )

The Network Time Sync Period Response command is sent from the Module to the Host in response to a Network Time Sync Period Request command. The command conveys the time sync period currently set on the module.

Payload for Network Time Sync Period Response Command

Back to Top

HA Clusters (0x12)

The HA clusters command set encompasses the following ZCL clusters for common HA applications:

• On/Off
• Level Control
• Power Configuration
• Lock/Unlock Door (under development)

The mandatory commands associated with a given HA cluster are only made available if that cluster is first appended to the application endpoint configuration. For example, the On/Off State Update command will only become available to the Host after it configures an application endpoint with the On/Off server cluster.

On/Off State Update Command - ( PH:0x012, SH:0x00 )

The On/Off State Update command is sent by the Module to the Host on reception of a network command that modifies the On/Off attribute value on the given endpoint (i.e. that which supports the On/Off server cluster). The command contains the current On/Off state and indicates if it was updated by a local or remote source.

Payload for On/Off State Update Command

Expected Host Action

The Host shall modify its hardware output appropriately based on the new On/Off state. For example, if the given device is a light switch and the command indicates a new state of “On” the switch should be turned on.

Move to Level Command - ( PH:0x012, SH:0x20 )

The Move to Level command is sent by the Module to the Host on reception of a Move to Level command from the network, targeted to an endpoint on which the application supports the Level Control server cluster.

Payload for Move to Level Command

Expected Host Action

The Host shall modify its hardware output appropriately based on the new Level. For example, if the given device is a dimmer, the Host shall dim the connected light to the light level corresponding to the given Level value. In this example, if the Host controls multiple dimmers on disparate endpoints, the change in Level should only be applied to the dimmer identified by the target Endpoint ID.

If the withOnOff flag is “True” the Host must update the CurrentLevel attribute of the Level Control server cluster and the OnOff attribute of the On/Off cluster. The CurrentLevel attribute must be set to the value given in the Level field of the command payload. If the Level field is non-zero, the OnOff attribute must be set to On. Otherwise, the Level field is zero and the OnOff attribute must be set to Off.

Level Move Command - ( PH:0x012, SH:0x21 )

The Level Move command is sent by the Module to the Host on reception of a Move command from the network, targeted to an endpoint on which the application supports the Level Control server cluster. The command conveys both the expected Direction and Rate of movement.

Payload for Level Move Command

Expected Host Action

The Host shall modify its hardware output appropriately based on the given Direction and Rate of movement specified. The movement is not expected to stop until reception of a Level Stop command or until further movement is not possible (i.e. maximum or minimum Level reached).

If the withOnOff flag is “True” the Host must update the CurrentLevel attribute of the Level Control server cluster and the OnOff attribute of the On/Off cluster.

Level Step Command - ( PH:0x012, SH:0x22 )

The Level Step command is sent by the Module to the Host on reception of a Step command from the network, targeted to an endpoint on which the application supports the Level Control server cluster. The command conveys both the expected direction of movement (up or down) and unit size of each step.

Payload for Level Step Command

Expected Host Action

The Host shall modify its hardware output appropriately based on the given Step Mode, Step Size and Transition Time specified. The movement is not expected to stop until reception of a Level Stop command or until further movement is not possible (i.e., maximum or minimum Level reached).

If the withOnOff flag is “True” the Host must update the CurrentLevel attribute of the Level Control server cluster and the OnOff attribute of the On/Off cluster.

Level Stop Command - ( PH:0x012, SH:0x23 )

The Level Stop command is sent by the Module to the Host on reception of a Stop command from the network, targeted to an endpoint on which the application supports the Level Control server cluster.

Payload for Level Stop Command

Expected Host Action

The Host shall stop all Level Control movement on the specified hardware endpoint.

Check Battery Attribute Command - ( PH:0x012, SH:0x24 )

The Check Battery Attribute command is sent from the Host to the Module which triggers the Module to check the battery voltage. The command has no payload. It is recommended that this command be called after updating the battery voltage attribute.

Effect on Receipt

Module responds with a Status Response. If the battery voltage is lower than the threshold voltage, an alarm will be sent out through the OTA client.

Status Response to Check Battery Attribute Command

Move To Level With On/Off Status - ( PH:0x012, SH:0x25 )

The Move to Level with On/Off status command is sent by the Module to the Host whenever the Current Level and OnOff status change as a result of incoming Level Control cluster commands. 

When the Module receives incoming Level Control cluster commands (Move to Level, Move, Step) over the air, it computes the changes to Current Level and OnOff, and send the result to Host. If the level change requires a transition (e.g. move from 0 to 100 in 5 seconds), the Module will send the Host a series of Move To Level With OnOff Status every 50ms til the end of the transition time. Thus, the Module takes care of the ZigBee cluster logic; Host only needs to modify the hardware output based on the changes.

Payload for Move to Level With On/Off Command

Expected Host Action

The Host shall modify its hardware output appropriately based on the new Level and new OnOff status. For example, if the given device is a dimmer, the Host shall dim the connected light to the light level corresponding to the given Level value. In this example, if the Host controls multiple dimmers on disparate endpoints, the change in Level should only be applied to the dimmer identified by the target Endpoint ID.

The Host is otherwise required to mirror the state indicated by the On/Off Status parameter on the physical device. 

Example Payload

• (Indicating Level 100, Transition Time 0, On/Off Status ON) F1 12 25 BB 05 16 64 00 00 01 72 01 [RHAMoveToLevel]

Lock Door Command  - ( PH:0x012, SH:0x60 )

The Lock Door command is sent by the Module to the Host on reception of Lock command from the network (Lock Door, Toggle, Recall Scene, etc.). The command has no payload.

This command is under development.

Expected Host Action

The Host shall lock the door and confirm the new Lock State by issuing the Lock Confirm command. If the Module times out while waiting for the Lock Confirm response from the Host, it will report a failure to the network device that issued the original Lock command.

Unlock Door Command - ( PH:0x012, SH:0x61 )

The Unlock Door command is sent by the Module to the Host on reception of an Unlock command from the network (Unlock Door, Toggle, Recall Scene, etc.). The command has no payload.

This command is under development.

Expected Host Action

The Host shall unlock the door and confirm the new Lock State by issuing the Lock Confirm command. If the Module times out while waiting for the Lock Confirm response from the Host, it will report a failure to the network device that issued the original Unlock Door command.

Lock Confirm Command - ( PH:0x012, SH:0x63 )

The Lock Confirm command is sent by the Host to the Module in order to confirm the current Lock State after reception of a Lock Door or Unlock Door command.

This command is under development.

Payload for Lock Confirm Command

Effect on Receipt

The Module will update the value of the application Lock State attribute and report the success of the Lock or Unlock action to the network device that issued the original command.

Back to Top

Serial Bootload Frames (0x0B)

The commands in this section facilitate serial bootload upgrade of the application operating on the Module. These commands have been implemented per HA 1.2 guidelines.

Query Next Image Response Command - ( PH:0x0B, SH:0x02 )

The Query Next Image Response frame is sent from the Host to the Module and prompts the Module to prepare its external flash memory to receive a new image. Any existing firmware image in flash is erased.

Payload for Query Next Image Response Command

Image Block Request Command - ( PH:0x0B, SH:0x03 )

The Image Block Request frame is sent from the Module to the Host. The Module expects to receive an Image Block Response from the Host in return.

Payload for Image Block Request Command

Image Block Response Command - ( PH:0x0B, SH:0x05 )

The Image Block Response frame is sent from the Host to the Module. The Module will store this data to external flash memory at the offset provided.

Payload for Image Block Response Command

Upgrade End Request Command - ( PH:0x0B, SH:0x06 )

The Upgrade End Request frame is sent from the Module to the Host to indicate that it has received the new image and is awaiting an Upgrade End Response from the Host to switch to that image.

Payload for Upgrade End Request Command

Upgrade End Response Command - ( PH:0x0B, SH:0x07 )

The Upgrade End Response frame is sent from the Host to Module in response to an Upgrade End Request and serves to specify the time at which the Module will switch to the new image.

Payload for Upgrade End Response Command

Back to Top

OTA Upgrade Client Frames (0x0B)

The commands in this section facilitate over-the-air (OTA) client of the application operating on the Module. These commands have been implemented per the ZigBee HA 1.2 guidelines.