This page describes the commands supported by the RapidHA serial protocol. 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.
Network state restrictions apply to some frames. In these restrictions the ' - ' character denotes frames that are responses sent from Module to Host and will be sent when the network is in the same state as the request.
...
| title | New in RapidHA v1.7 |
|---|
...
| Anchor | ||||
|---|---|---|---|---|
|
| Note | ||
|---|---|---|
| ||
New sleep control frames under the Utility command group (PH: 0x55) provide the user with a wake-up handshaking scheme, as well as total and accurate control of application sleep cycles. |
...
| Table of Contents | ||||
|---|---|---|---|---|
|
...
This section describes a wide range of command functionality that works on a system-wide level under the Primary Header 0x55.
| Module |
| Anchor | ||||
|---|---|---|---|---|
|
The Reset command is sent from the Host to the Module, and prompts the Module to reboot. The command has no payload.
...
| Anchor | ||||
|---|---|---|---|---|
|
The Module Info Request commandis sent from the Hostto the Module to query the Module’s version and application type. This command has no payload.
...
| Anchor | ||||
|---|---|---|---|---|
|
The Module Info Responsecommand is sent from the Module to the Hostin response to a Module Info Request command.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Anchor Application Version Count Response Application Version Count Response
Application Version Count Response - ( PH:0x55, SH:0x07 )
| Application Version Count Response | |
| Application Version Count Response |
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
Byte Index | Field Name | Notes |
|---|---|---|
0 | Version String Count | A count of the total number of Application Version Strings available from the running application. |
Expected Host Action
None.
| Anchor | ||||
|---|---|---|---|---|
|
The Application Version Request is sent from the Host to the Module to query a given Application Version String describing either the Application Bootloader Version, the core RapidHA Version or the Virtual Host Application Version. The request payload length is 1 octet.
Payload for Application Version Request Command
Byte Index | Field Name | Notes |
|---|---|---|
0 | Version Index | 0x00 - Retrieve Bootloader Version |
Effect on Receipt
The Module will respond with an Application Version Response.
| Anchor | ||||
|---|---|---|---|---|
|
The Application Version Response is sent from the Module to the Host. The response payload length is variable.
Payload of Application Version Response Command
Byte Index | Field Name | Notes |
|---|---|---|
0 | Version String Index | The array index (0 based) that this command relates to. |
| 1 | Version Type | The type of version string returned. See Version Types. |
| 2..(n + 3) | Version | The version being returned. The length n is specified in the first octet of the field. A total of n bytes will follow this length byte containing data which shall be interpreted based on the Version Type. |
Expected Host Action
None.
Anchor Application Version Types Application Version Types
Version Types
| Application Version Types | |
| Application Version Types |
Type ID | Type Name | Length (Octets) |
|---|---|---|
0x00 | LSB Binary Type | 4 |
| 0x01 | MSB Binary Type | 4 |
| 0x02 | String Type | Variable |
| 0x03 | LSB Binary Type | 2 |
| 0x04 | MSB Binary Type | 2 |
| 0x05 - 0xFE | Reserved | N/A |
| 0xFF | Invalid | N/A |
LSB Binary Type
A type value of LSB Binary Type indicates that the version string is being provided as a series of binary encoded bytes that represent the version string in a dotted version format with the least significant byte provided first. For example, a binary value of 0x01,0x02,0x03,0x04 provided using this encoding would be translated to 4.3.2.1 (or possibly 4.3.2rc1) when displayed to the user. This is the default encoding for version numbers.
MSB Binary Type
A type value of MSB Binary Type indicates that the version string is being provided as a series of binary encoded bytes that represent the version string in a dotted version format with the most significant byte provided first. For example, a binary value of 0x05,0x06,0x07, 0x08 provided using this encoding would be translated to 5.6.7.8 (or possibly 5.6.7rc8) when displayed to the user.
String Type
A type value of String Type indicates that the version string is being provided as an ASCII encoded string of length n. The value will not be null terminated as the length is provided. For example, a binary value of 0x31,0x2e,0x32,0x2e,0x30,0x72,0x63,0x31 provided using this encoding would be translated to 1.2.0rc1.
Invalid
A type value of Invalid indicates that the requested element is invalid. Typically this indicates that a request was made for an index which lies outside of the valid range of version string indices.
| Anchor | ||||
|---|---|---|---|---|
|
The Restore Defaults frame is sent from the Host to the Module and serves to restore the Module to its factory default settings. The command has no payload.
Effect on Receipt
The Module restores all non-volatile elements to their factory default settings, leaves the network if it is joined to one or dissolves the network if it has formed one, and then reboots.
| Anchor | ||||
|---|---|---|---|---|
|
The Host shall send the Host Startup Ready command to the Module after it starts up and is ready for communication. The command has no payload.
Effect on Receipt
On receiving the command, the Module will respond with the Startup Sync Request command. If the Module is in the Already Running state (see payload for Startup Sync Request ), it signifies that this command was received due to an unexpected reset of the Host. In this case, the Module will have retained all its application cache and attribute values, but will suspend network operations and return to the Startup Synchronization phase.
| Anchor | ||||
|---|---|---|---|---|
|
The Startup Sync Request command is sent by the Module on startup or as a response to the Host Startup Ready command. Upon issuing this command, the Module suspends execution of the full application until the Host has completed all desired configuration and updates against it.
The Module resends this command every five seconds until the Host sends the Startup Sync Complete command in response, signaling the completion of the configuration and update process.
Payload for Startup Sync Request Command
Byte Index | Field Name | Notes |
|---|---|---|
0 | Running State | 0x00 = Starting Up |
1 | Configuration State | 0x00 = Factory Default |
The Running State indicates whether the Module has just powered up or is already running. If the Running State indicates the latter, it signifies that the Host experienced a unilateral reset.
The Configuration State indicates the application configuration state of the Module. The Factory Default state indicates that the Module is operating for the first time post-production, or subsequent to the reception of the Restore to Default command from the Host. The Needs Endpoint Configuration state indicates that the Module has restored all default configurations (Manufacturer ID, etc.), but still requires the Host to configure application endpoints, clusters and attributes. This state will occur after a soft or hard reset of the Module, regardless of the amount of non-volatile memory available.
Expected Host Action
The Host may receive the Startup Sync Request either during a synchronized power up or after a unilateral reset of the Module. The Host shall process both scenarios in the same manner.
If the Running State of the Module is Already Running the Host is not required to configure endpoints, clusters and attributes and perform updates on the values of the latter. Instead, the Host should query attribute values and cached event data from the Module in order to synchronize its internal state with that of the application.
If the Configuration State of the Module is Factory Default, the Host shall perform a full configuration of the application, specifying the IEEE functional device type, security configuration, endpoints, etc. If the Configuration State is Needs Endpoint Configuration, the Host shall configure the application endpoints, clusters and attributes accordingly. If Configuration State is Fully Configured, no further configuration action is required of the Host.
| Anchor | ||||
|---|---|---|---|---|
|
The Host shall send the Startup Sync Complete command to the Module in response to a Startup Sync Request and upon completion of all startup configurations and updates to the latter. The command has no payload.
Effect on Receipt
The Module acknowledges reception of the command with a Status Response indicating Success, after which it runs the full application. If the Module was previously joined to a network it will rejoin that network. Additionally, application configurations are backed up to non-volatile memory for restoration on the next startup.
Please note that Host configurations for endpoints, clusters and attributes are not preserved in non-volatile memory; thus they must be reconfigured after any soft or hard reset of the Module.
Status Response to Startup Sync Complete Command
Status Response | Enum | Description |
|---|---|---|
Success | 0x00 | Module received the command and will start the full application. |
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Expected Host Action
None.
Anchor Antenna Configuration Write Antenna Configuration Write
Antenna Configuration Write Command - ( PH:0x55, SH:0x25 )
| Antenna Configuration Write | |
| Antenna Configuration Write |
The Antenna Configuration Write command is sent by the Host to the Module to select the hardware antenna configuration of the MMB Hornet platform.
...
Anchor LED Configuration Request LED Configuration Request
LED Configuration Request Command - ( PH:0x55, SH:0x26 )
| LED Configuration Request | |
| LED Configuration Request |
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.
...
Anchor LED Configuration Response LED Configuration Response
LED Configuration Response Command - ( PH:0x55, SH:0x27 )
| LED Configuration Response | |
| LED Configuration Response |
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.
...
Anchor LED Configuration Write LED Configuration Write
LED Configuration Write Command - ( PH:0x55, SH:0x28 )
| LED Configuration Write | |
| LED Configuration Write |
The LED Configuration Write command is sent by the Host to the Module to set the LED behavior 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.
...
Anchor Serial ACK Config Write Serial ACK Config Write
Serial ACK Config Write Command - ( PH:0x55, SH:0x30 )
| Serial ACK Config Write | |
| Serial ACK Config Write |
The Serial ACK Config Write command is sent by the Host to the Module in order to enable or disable mandatory serial acknowledgements.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Anchor Serial ACK Config Response Serial ACK Config Response
Serial ACK Config Response Command - ( PH:0x55, SH:0x32 )
| Serial ACK Config Response | |
| Serial ACK Config Response |
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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 behaviorbehaviour.
Payload for Sleepy Parameters Write CMD Command
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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
Byte Index | Field Name | Notes |
|---|---|---|
0 | Status | 0x00 = Success |
| Anchor | ||||
|---|---|---|---|---|
|
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.
Byte Index | Field Name | Notes |
|---|---|---|
| 0.. 18 | Filler Bytes | Stuff all payload bytes with 0xFF |
| Anchor | ||||
|---|---|---|---|---|
|
The Error frame is sent by the Module to the Host to report an application error.
Payload for Error Command
Byte Index | Field Name | Notes |
|---|---|---|
0 | Error Condition | An enumeration of Error Conditions: Network Error Conditions: 0x00 – Reserved Reset Error Conditions: 0x10 – Reset Error Synchronization Error Conditions: 0x20 – Synchronization Error Bootload Error Conditions: 0xB0 – Local Bootload Error |
1 | Sub-Error | Sub-Errors associated with the given Error Condition. Associated with FORMING_NETWORK_ERROR (0x04) Associated with LOCAL_BOOTLOAD_ERROR (0xB0) Associated with OTA_BOOTLOAD_ERROR (0xB1) |
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
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Frame Name | Secondary Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|---|
| Join Network | 0x00 | Network Down Only | Host |
| Form Network | 0x01 | Network Down Only | Host |
| Permit Join | 0x03 | Network Up Only | Host |
| Leave Network | 0x04 | All Contexts | Host |
| Rejoin Network | 0x05 | Network Up Only | Host |
| Network Status Request | 0x08 | All Contexts | Host |
| Network Status Response | 0x09 | N/A | Module |
| Trust Center Device Update | 0x10 | Network Up Only | Module |
| Network Auto Join | 0x11 | Network Down Only | Host |
| Network Reset Auto Join | 0x12 | All Contexts | Host |
| Anchor | ||||
|---|---|---|---|---|
|
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
Byte Index | Field Name | Notes |
|---|---|---|
0..3 | Channel Mask | Four-byte channel mask. Each bit represents channels 0 – 31. Example: Channel 11 = 0x00000800 or interpreted as a 32-bit bitmap - 0000 0000 0000 0000 0000 1000 0000 0000 - bit 11 would be flipped Channel 13 = 0x00002000 or interpreted as a 32-bit bitmap - 0000 0000 0000 0000 0010 0000 0000 0000 - bit 13 would be flipped ZigBee HA and SE operate on only channels 11 through 26. It should be noted that |
Networks formed on this channel are in violation of FCC rules and regulations.
in order to comply with FCC regulations, a MMB Networks device on channel 26 will operate in a reduced power mode. | ||
4 | Auto Options | Bit 0 = 1 – Auto PAN ID If both bits are “1” and multiple networks exist on the channel, |
5,6 | Short PAN ID | The Short PAN ID of the network that the Module must join. |
7..14 | Extended PAN ID | The Extended PAN ID of the network Module must join to. |
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.
| Anchor | ||||
|---|---|---|---|---|
|
Status Response | Enum | Description |
|---|---|---|
Success | 0x00 | The Module successfully processed the command, and shall start the scan and join sequence. |
Invalid Call | 0x01 | The Module is already on a network. The command is only valid when the application’s network state is Network Down. |
Invalid Data | 0x02 | No channels have been selected in the Channel Mask defined in the command. |
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0..3 | Channel Mask | 4-byte channel mask. Each bit represents channels 0 – 31. The least significant bit, bit 0, corresponds to channel 0, bit 1 to channel 1, etc. Example: Channel 11 = 0x00000800 or interpreted as a 32-bit bitmap - 0000 0000 0000 0000 0000 1000 0000 0000 - bit 11 would be flipped Channel 13 = 0x00002000 or interpreted as a 32-bit bitmap - 0000 0000 0000 0000 0010 0000 0000 0000 - bit 13 would be flipped ZigBee HA and SE only operate on channels 11-26 (inclusive). If multiple channels are selected, the Module will form a network on the channel with the least interference. Please note: In order to comply with FCC regulations, MMB Networks devices operate at a reduced power level on channel 26 is restricted. Networks formed on this channel are in violation of FCC rules and regulations. 26 to stay within FCC regulations. It's not recommended to form a network on this channel as it will have a reduced range. |
4 | Auto Options | Bit 0 = 1 – Auto PAN ID |
5,6 | Short PAN ID | The Short PAN ID of the new network. |
7..14 | Extended PAN ID | The Extended PAN ID of the new network. |
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
The Network Status Response is sent by the Module to the Host, either as a response to the Network Status Requestcommand, 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).
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Network State | 0x00 = Network Down |
1 | ZigBee Device Type | 0x00 = Coordinator |
2 | Channel | 0xFF = Unknown |
3,4 | Node ID | 0xFFFF = Unknown |
5,6 | PAN ID | 0xFFFF = Unknown |
7..14 | Extended PAN ID | All 0’s = Unknown |
15 | Permit Join Time | The remaining Permit Join Duration at the time of issuance. |
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Node ID of the device attempting to join or leave the network |
2..9 | EUI64 | EUI64 of the device attempting to join or leave the network |
10 | Device Update Event | Event that triggered the update. 0x00 = MAC Association |
11,12 | Parent Node ID | Node ID of the device’s parent |
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.
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Status Response | Enum | Description |
|---|---|---|
Success | 0x00 | The Module successfully processed the command, and shall start the scan and join sequence. |
...
Back to Top
| Anchor | ||||
|---|---|---|---|---|
|
This section describes commands that set and report on security keys.
| Frame Name | Secondary Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|---|
| Preconfigured Key Option Write | 0x00 | Network Down Only | Host |
| Preconfigured Key Option Request | 0x01 | All Contexts | Host |
| Preconfigured Key Option Response | 0x02 | N/A | Module |
| Install Code Request | 0x03 | All Contexts | Host |
| Install Code Response | 0x04 | N/A | Module |
| Link Key Write | 0x05 | Network Down Only | Host |
| Link Key Request | 0x06 | All Contexts | Host |
| Link Key Response | 0x07 | N/A | Module |
| Network Key Write | 0x08 | Network Down Only | Host |
| Network Key Request | 0x09 | All Contexts | Host |
| Network Key Response | 0x0A | N/A | Module |
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Anchor | ||||
|---|---|---|---|---|
|
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 Writecommand.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Anchor | ||||
|---|---|---|---|---|
|
The Install Code Response frame is sent by the Module to the Host when queried with an Install Code Request.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0..15 | Network Key |
...
Back to Top
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Frame Name | Secondary Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|---|
| Device Type Write | 0x00 | Startup Config Only | Host |
| Device Type Request | 0x01 | All Contexts | Host |
| Device Type Response | 0x02 | All Contexts | Module |
| Add Endpoint | 0x10 | Startup Config Only | Host |
| Endpoint List Request | 0x11 | All Contexts | Host |
| Endpoint List Response | 0x12 | All Contexts | Module |
| Endpoint Descriptor Request | 0x13 | All Contexts | Host |
| Endpoint Descriptor Response | 0x14 | All Contexts | Module |
| Add Attributes to Cluster | 0x20 | Startup Config Only | Host |
| Attribute List Request | 0x21 | All Contexts | Host |
| Attribute List Response | 0x22 | All Contexts | Module |
| Attribute Request | 0x23 | All Contexts | Host |
| Attribute Response | 0x24 | All Contexts | Module |
| Attribute Write | 0x25 | All Contexts | Host |
| Attribute Report Passthrough Control | 0x26 | All Contexts | Host |
| Clear Endpoint Config | 0x30 | Startup Config Only | Host |
| Register Commands Passthrough | 0x80 | Startup Config Only | Host |
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
The Device Type Requestis sent by the Host to the Module in order to query the application IEEE functional device type. The command has no payload.
...
| Anchor | ||||
|---|---|---|---|---|
|
The Device Type Response is sent by the Module to the Host in response to a Device Type Request.
...
Anchor Add Endpoint Add Endpoint
Add Endpoint Command - ( PH:0x03, SH:0x10 )
| Add Endpoint | |
| Add Endpoint |
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.
...
| Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | Valid range 1 - 240 |
1,2 | Profile ID | 0x0104 |
3,4 | Device ID | See /wiki/spaces/SPRHA17/pages/37093556 this page for a list of Device IDs used in the HA profile. |
5 | Device Version | |
6 | Number of Server Clusters | The number of server clusters, n |
7..6+2n | List of Server Clusters | List of 2-byte Cluster IDs, LSB first |
7+2n | Number of Client Clusters | The number of client clusters, m |
8+2n..7+2(n+m) | List of Client Clusters | List of 2-byte Cluster IDs, LSB first |
...
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.
...
Anchor Endpoint List Request Endpoint List Request
Endpoint List Request Command - ( PH:0x03, SH:0x11 )
| Endpoint List Request | |
| Endpoint List Request |
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.
...
Anchor Endpoint List Response Endpoint List Response
Endpoint List Response Command - ( PH:0x03, SH:0x12 )
| Endpoint List Response | |
| Endpoint List Response |
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.
...
Anchor Endpoint Descriptor Request Endpoint Descriptor Request
Endpoint Descriptor Request Command - ( PH:0x03, SH:0x13 )
| Endpoint Descriptor Request | |
| Endpoint Descriptor Request |
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.
...
Anchor Endpoint Descriptor Response Endpoint Descriptor Response
Endpoint Descriptor Response Command - ( PH:0x03, SH:0x14 )
| Endpoint Descriptor Response | |
| Endpoint Descriptor Response |
The Endpoint Descriptor Response is sent by the Module to the Host in response to an Endpoint Descriptor Request.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | Valid range 1 - 240 |
1,2 | Profile ID | |
3,4 | Device ID | See /wiki/spaces/SPRHA17/pages/37093556 this page for a list of Device IDs used in the HA profile. |
5 | Device Version | |
6 | Number of Server Clusters | The number of server clusters, n |
7..6+2n | List of Server Clusters | List of 2-byte Cluster IDs, LSB first |
7+2n | Number of Client Clusters | The number of client clusters, m |
8+2n..7+2n+2m | List of Client Clusters | List of 2-byte Cluster IDs, LSB first |
...
Anchor Add Attributes to Cluster Add Attributes to Cluster
Add Attributes to Cluster Command - ( PH:0x03, SH:0x20 )
| Add Attributes to Cluster | |
| Add Attributes to Cluster |
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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | |
1,2 | Cluster ID | |
3 | Cluster Server/Client | 0x00 = Client |
4 | Number of Attributes to Add | |
5..n | Attribute Definition Records | Record format is shown in the following table. |
Anchor Attribute Definition Record Format Attribute Definition Record Format
Attribute Definition Record Format
| Attribute Definition Record Format | |
| Attribute Definition Record Format |
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Attribute ID | |
2 | Attribute Type | See the ZCL Data TypesSpecification References page for possible values. |
3 | Attribute Property Bitmask | Bit Description 0 0 = Not Readable |
...
Anchor Attribute List Request Attribute List Request
Attribute List Request Command - ( PH:0x03, SH:0x21 )
| Attribute List Request | |
| Attribute List Request |
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
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | The target endpoint to query. |
1,2 | Cluster ID | The target cluster to query on the given endpoint. |
3 | Cluster Server/Client | 0x00 = Client |
Effect on Receipt
If the Module supports the target endpoint and cluster, it will relay an appropriate number of AttributeList Response commandsto the Host. Otherwise, a Status Response is generated indicating an error, as described in the following table.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | |
1,2 | Cluster ID | |
3 | Cluster Server/Client | 0x00 = Client |
4 | Total Number of Pages | The total number of pages (i.e., command frames) that will be sent to complete the response. |
5 | Current Page | The current page of a multi-page response. The first page is 1, a second page, if any, is 2, etc. |
6 | Number of Attributes | Number of attributes in the current page. |
7…n | List of Attribute IDs | Each Attribute ID is sent LSB first |
Expected Host Action
None.
Anchor Attribute Request Attribute Request
Attribute Request Command - ( PH:0x03, SH:0x23 )
| Attribute Request | |
| Attribute Request |
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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | The target endpoint to query. |
1,2 | Cluster ID | The target cluster to query on the given endpoint. |
3 | Cluster Server/Client | 0x00 = Client |
4,5 | Attribute ID | The ID of the attribute to query. |
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.
...
Anchor Attribute Response Attribute Response
Attribute Response Command - ( PH:0x03, SH:0x24 )
| Attribute Response | |
| Attribute Response |
An Attribute Response is sent by the Module to the Host in response to an Attribute Request.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | |
1,2 | Cluster ID | |
3 | Cluster Server/Client | 0x00 = Client |
4,5 | Attribute ID | |
6 | Attribute Property Bitmask | Bit Description 0 0 = Not Readable |
7 | Attribute Type | See the ZCL Data TypesSpecification References page for possible values. |
8..n | Attribute Value | Size dependent on Attribute Type. For strings, the length of the string will immediately precede the string itself. |
Expected Host Action
None.
Anchor Attribute Write Attribute Write
Attribute Write Command - ( PH:0x03, SH:0x25 )
| Attribute Write | |
| Attribute Write |
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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | |
1,2 | Cluster ID | |
3 | Cluster Server/Client | 0x00 = Client |
4,5 | Attribute ID | |
6 | Attribute Type | See the ZCL Data TypesSpecification References page for possible values. |
7..n | Attribute Value | Size dependent on Attribute Type. For strings, the length of the string must immediately precede the string itself. |
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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
Byte Index | Field Name | Notes |
|---|---|---|
0 | Attribute Passthrough Control | 0x00 = Disabled |
...
When enabled, RapidHA will pass all ZCL Attribute Reports through via the ZCL Passthrough functionality.
| Anchor | ||||
|---|---|---|---|---|
|
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.
Anchor Register Commands Passthru Register Commands Passthru
Register Commands Passthru Command - ( PH:0x03, SH:
| Register Commands Passthru | |
| Register Commands Passthru |
...
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 Moduleon their reception, or commands not supported by the Module that would otherwise not be passed to the Host on their reception.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | Endpoint on which the cluster commands are supported. |
1,2 | Cluster ID | The cluster on which the commands are supported. |
3 | Cluster Server/Client | 0x00 = Client |
4 | Commands Count | 0x00 = Pass through all commands |
5..n | Command IDs List | The Command ID(s) of the command(s) to pass through. Each Command ID is 1 byte. |
Effect on Receipt
The Module will register the given commands in non-volatile memory and refer to the list on reception of ZCLcommands. The following table lists the possible Status Responses on reception of the command.
...
Status Response | Enum | Description |
|---|---|---|
Success | 0x00 | Commands were successfully registered. |
Storage Full | 0x04 | There was insufficient storage for the registration list. |
Incorrect Length | 0x07 | The size of the attribute value does not match what is expected. |
Endpoint Not Found | 0x08 | The endpoint cannot be found. |
Cluster Not Found | 0x09 | The cluster cannot be found. |
...
...
Back to Top
| Anchor |
|---|
...
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.
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.
| Frame Name | Secondary Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|---|
| Send ZDO Unicast | 0x01 | Network Up Only | Host |
| Send ZDO Broadcast | 0x02 | Network Up Only | Host |
| ZDO Send Status | 0x03 | All Contexts | Module |
| ZDO APS Ack | 0x04 | All Contexts | Module |
| ZDO Response Received | 0x05 | All Contexts | Module |
| ZDO Response Timeout | 0x06 | All Contexts | Module |
| ZDO Device Announce Received | 0x1E | All Contexts | Module |
| Anchor | ||||
|---|---|---|---|---|
|
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:
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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 Optionsindicating 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).
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
The ZDO Device Announce Received frame is sent by the Module to the Host when a new device announces itself on the network.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Node ID of the new device. |
2..9 | EUI64 | The 64 bit Extended Universal Identifier of the new device. |
10 | Capability | MAC capability bitmap of the device. Bit Description |
...
Back to Top
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Frame Name | Secondary Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|---|
| Send ZCL Unicast | 0x00 | Network Up Only | Host |
| Send ZCL Multicast | 0x01 | Network Up Only | Host |
| Send ZCL Broadcast | 0x02 | Network Up Only | Host |
| ZCL Send Status | 0x03 | All Contexts | Module |
| ZCL APS Ack | 0x10 | All Contexts | Module |
| ZCL Response Received | 0x11 | All Contexts | Module |
| ZCL Response Timeout | 0x12 | All Contexts | Module |
| Received Attribute Write | 0x14 | All Contexts | Module |
| ZCL Passthru Message | 0x20 | All Contexts | Module |
| ZCL Read Attribute Request | 0x30 | Network Up Only | Host |
| ZCL Read Attribute Response | 0x31 | All Contexts | Module |
| ZCL Write Attribute Request | 0x32 | Network Up Only | Host |
| ZCL Write Attribute Response | 0x33 | All Contexts | Module |
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Byte Index | Field Name | Notes | ||
|---|---|---|---|---|
0,1 | Group ID | The Group ID of the Group to which the target devices belong. | ||
1 | Enable reception of APS ACK status messages (not used) | 2 | Local Endpoint ID | |
3,4 | Cluster ID | |||
5 | Radius | Number of Network Hops that this message may travel. 0 = Maximum | ||
6 | Non-Member Radius | Number of Network Hops that this message will be forwarded to by devices not in the target Group. 0x07 or higher indicates an infinite Non-Member Radius. | ||
7 | Response Options | 8-bit Bitmap: Bit 0: Custom Sequence Number | ||
8 | Frame Control | 8-bit Bitmap: Bits 0-1: 00 = ZCL General Command | ||
9,10 | Manufacturer Code | Applicable if Bit 2 of Frame Control is enabled. | ||
11 | Transaction Sequence Number | Only used if bit 0 in the Response Options field is set. Otherwise, the application ignores this value and automatically assigns the next outgoing sequence number. The Host must apply a number in the range of 0-127. The range 128-255 is reserved for commands generated by the Module. | ||
12 | Command ID | |||
13 | Payload Length | |||
14..n | Payload |
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
The ZCL Send Status message is sent by the Module to the Host after the transmission of a Send ZCL Unicast, Send ZCL MulticastorSend 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 Numberassigned to it.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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 Optionsindicating 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).
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Source Node ID | The Source Node ID of the received Attribute Write command. |
2 | Source Endpoint ID | The source Endpoint ID of the received Attribute Write command. |
3 | Local Endpoint ID | The target local Endpoint ID to which the received Attribute Write command was directed. |
4,5 | Cluster ID | |
6 | Cluster Client/Server | 0x00 = Client |
7,8 | Attribute ID | |
9 | Attribute Type | See the ZCL Data TypesSpecification References page for possible values. |
10..n | New Attribute Value | The new value of the target attribute, as modified by the received Attribute Write command. For strings, the length of the string will immediately precede the string itself. |
...
Anchor ZCL Passthru Message ZCL Passthru Message
ZCL Passthru Message Command - ( PH:0x05, SH:0x20 )
| ZCL Passthru Message | |
| ZCL Passthru Message |
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
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Source Node ID | |
2 | Source Endpoint ID | |
3 | Local Endpoint ID | |
4,5 | Cluster ID | |
6 | Encryption Level | 0x00 = Network Encryption Only |
7 | Frame Control | 8-bit Bitmap: Bits 0-1: 00 = ZCL General Command |
8,9 | Manufacturer Code | Applicable if Bit 2 of Frame Control is enabled. |
10 | Transaction Sequence Number | The Transaction Sequence Number of the original request. |
11 | Command ID | |
12 | Payload Length | |
13..n | Payload |
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Source Node ID | Address of the responding device |
2 | Source Endpoint ID | Endpoint where attribute is hosted |
3,4 | Source Cluster ID | Cluster of the attribute |
5 | Client/Server Cluster | 0x00 = Client |
6,7 | Attribute ID | Corresponds to Attribute ID in request |
8 | ZCL Status | 0x00 = Success See /wiki/spaces/SPRHA17/pages/37093554 this page for ZCL Status values |
9 | Attribute Data Type | See this page for valid values |
10..n | Attribute Value | Byte length of the Value dependent on Attribute Data Type. For strings, the length of the string will immediately precede the string itself. |
...
| Anchor | ||||
|---|---|---|---|---|
|
The ZCLAttribute 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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Attribute ID | The target attribute to write to |
2 | Attribute Data Type | See this page for details on the ZCL Data Types used in this field |
3..2 + m | Attribute Value | Byte length of the Attribute Value where m ≥ 1 is dependent on Attribute Data Type. For strings, the length of the string will immediately precede the string itself. |
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Expected Host Action
None.
...
Back to Top
| Anchor | ||||
|---|---|---|---|---|
|
The General Clusters command set encompasses the following mandatory ZCL clusters in the general domain:
...
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.
| Frame Name | Secondary Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|---|
| Received Reset to Factory Default | 0x00 | All Contexts | Module |
| Identify Start | 0x10 | All Contexts | Module |
| Identify Stop | 0x11 | All Contexts | Module |
| Time Client Get Time | 0x40 | All Contexts | Host |
| Time Client Get Time Response | 0x41 | All Contexts | Module |
| Time Client Time Changed | 0x42 | All Contexts | Module |
| Network Time Sync Period Write | 0x43 | All Contexts | Host |
| Network Time Sync Period Request | 0x44 | All Contexts | Host |
| Network Time Sync Period Response | 0x45 | All Contexts | Module |
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Sync Period | The time period, in minutes, for the Time client to sync with the Time server 0x0001-0xFFFF: Valid range for time period |
...
Back to Top
| Anchor | ||||
|---|---|---|---|---|
|
The HA clusters command set encompasses the following ZCL clusters for common HA applications:
...
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.
| Frame Name | Secondary Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|---|
| On Off State Update | 0x00 | Network Up Only | Module |
| Move to Level | 0x20 | Network Up Only | Module |
| Level Move | 0x21 | Network Up Only | Module |
| Level Step | 0x22 | Network Up Only | Module |
| Level Stop | 0x23 | Network Up Only | Module |
| Check Battery Attribute | 0x24 | Network Up Only | Host |
| Move to level with On/Off Status | 0x25 | Network Up Only | Module |
| Lock Door | 0x60 | Network Up Only | Module |
| Unlock Door | 0x61 | Network Up Only | Module |
| Lock Confirm | 0x63 | Network Up Only | Host |
| Anchor | ||||
|---|---|---|---|---|
|
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/Offstate and indicates if it was updated by a local or remote source.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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
Byte Index | Field Name | Notes |
|---|---|---|
0 | Endpoint ID | Endpoint ID of the application Level Control server cluster. |
Expected Host Action
The Host shall stop all Level Control movement on the specified hardware endpoint.
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
- (Indicating Level 100, Transition Time 0, On/Off Status ON) F1 12 25 BB 05 16 64 00 00 01 72 01 [RHAMoveToLevel]
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
Payload for Lock Confirm Command
Byte Index | Field Name | Notes |
|---|---|---|
0 | Lock State | 0x00 = Unlocked |
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
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Frame Name | Secondary Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|---|
| Query Next Image Response | 0x02 | All Contexts | Host |
| Image Block Request | 0x03 | All Contexts | Module |
| Image Block Response | 0x05 | All Contexts | Host |
| Upgrade End Request | 0x06 | All Contexts | Module |
| Upgrade End Response | 0x07 | All Contexts | Host |
| Anchor | ||||
|---|---|---|---|---|
|
The Query Next Image Response frame is sent from the Host to the Moduleand prompts the Module to prepare its external flash memory to receive a new image. Any existing firmware image in flash is erased.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
The Upgrade End Response frame is sent from the Host to Module in response to an Upgrade End Requestand serves to specify the time at which the Module will switch to the new image.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Node ID of Module |
2..9 | EUI64 | EUI64 of Module |
10 | Endpoint ID | Endpoint of Module |
11,12 | Manufacturer Code | |
13,14 | Image Type | Unused - for backwards compatibility. Set to 0x0000 |
15..18 | File Version | Will contain the value initially set in the Query Next Image Response / OTA Query Next Image Response frames by the Host. |
19..22 | Current Time | UTC Time, where 0x00000000 = Now |
23..26 | Upgrade Time | UTC Time, where 0x00000000 = Now |
...
Back to Top
| Anchor | ||||
|---|---|---|---|---|
|
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.
| Frame Name | Secondary |
|---|
| Header Byte | Allowed Context | Sent By Host/Module |
|---|---|---|
| OTA Query Configuration Request |
0x21 -
| 0x20 | All Contexts | Host | |
| OTA Query Configuration Response |
| 0x21 | All Contexts | Module |
| OTA Query Configuration Write |
0x23 -
| 0x22 | All Contexts | Host | |
| Image Progress Notification |
-
No Restriction
-
0x25 - OTA Version Configuration Response
0x26 - OTA Version Configuration Write
-
No Restriction
| 0x23 | All Contexts | Module | |
| OTA Version Configuration Request | 0x24 | All Contexts | Host |
| OTA Version Configuration Response | 0x25 | All Contexts | Module |
| OTA Version Configuration Write | 0x26 | All Contexts | Host |
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Query Configuration Request frame is sent from the Host to the Moduleto request the intervals at which the Modulequeries the OTA server for data. The Module will respond with an OTA Query Configuration Response frame. The command has no payload.
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Query Configuration Response frame is sent from the Module to the Host in response to an OTA Query Configuration Request.
Payload for OTA Query Configuration Response Command
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Discovery Retry Rate | The rate, in minutes, at which the Module performs discovery for an OTA server when it has knowledge of none. Default = 15 minutes |
2..5 | First Image Query Delay | The delay, in milliseconds, after discovery of an OTA server and prior to the first Next Image Request (i.e., querying the server to determine if a new image is available). Default = 1 minute. |
6..9 | Image Query Rate | The delay, in milliseconds, between consecutive Next Image Request queries (i.e., querying the server to determine if a new image is available). Default = 15 minutes. |
10..13 | Block Request Rate | The delay, in milliseconds, between Image Block Requests (i.e., the rate at which a new image will be retrieved from the server). Default = 1 millisecond. |
| Anchor | ||
|---|---|---|
|
...
|
...
|
...
Write Command - ( PH:0x0B, SH:0x22 )
The OTA Query Configuration Request Write frame is sent from the Host to the Moduleto request set the various intervals at which the Modulequeries the OTA server for data. The Module will respond with an OTA Query Configuration Response frame. The command has no payload.
...
The OTA Query Configuration Response frame is sent from the Module to the Host in response to an OTA Query Configuration RequestThese settings may not be modified during an OTA upgrade and will persist in non-volatilememory.
Payload for OTA Query Configuration
...
Write Command
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Discovery Retry Rate | The rate, in minutes, at which the Module performs discovery for an OTA server when it has knowledge of none. Default = Set to 0xFFFF to retain default (15 minutes). |
2..5 | First Image Query Delay | The delay, in milliseconds, after discovery of an OTA server and prior to the first Next Image Request (i.e. , querying the server to determine if a new image is available). Default = Set to 0xFFFFFFFF to retain default (1 minute). |
6..9 | Image Query Rate | The delay, in milliseconds, between consecutive Next Image Request queries (i.e. , querying the server to determine if a new image is available). Default = Set to 0xFFFFFFFF to retain default (15 minutes). |
10..13 | Block Request Rate | The delay, in milliseconds, between Image Block Requests (i.e. , the rate at which a new image will be retrieved from the server). Default = Set to 0xFFFFFFFF to retain default (1 millisecond). |
| Anchor |
|---|
...
|
The Image Progress Notification frame is sent from the Host Module to the ModuleHost to set the various intervals at which the Modulequeries the OTA server for data. These settings may not be modified during an OTA upgrade and will persist in non-volatilememory.
...
notify the Host of the reception of every 512 bytes of firmware downloaded through the OTA Bootload cluster. The frame is also sent on completion of the download.
Payload for Image Progress Notification Command
Byte Index | Field Name | Notes | ||
|---|---|---|---|---|
0,1 | Discovery Retry Rate | The rate, in minutes, at which the Module performs discovery for an OTA server when it has knowledge of none. Set to 0xFFFF to retain default (15 minutes). | ||
2..5 | First Image Query Delay | The delay, in milliseconds, after discovery of an OTA server and prior to the first Next Image Request (i.e. querying the server to determine if a new image is available). Set to 0xFFFFFFFF to retain default (1 minute). | ||
6..9 | Image Query Rate | The delay, in milliseconds, between consecutive Next Image Request queries (i.e. querying the server to determine if a new image is available). Set to 0xFFFFFFFF to retain default (15 minutes). | ||
10..13 | Block Request Rate | The delay, in milliseconds, between Image Block Requests (i.e. the rate at which a new image will be retrieved from the server). Set to 0xFFFFFFFF to retain default (1 millisecond). | Status | Maps to ZCL Status codes: 0x00 = Success See /wiki/spaces/SPRHA17/pages/37093554 for all ZCL Status values. |
1,2 | Manufacturer Code | |||
3,4 | Image Type | Unused - for backwards compatibility. Set to 0x0000 | ||
5..8 | File Version | Will contain the value initially set in the Query Next Image Response / OTA Query Next Image Response frames by the Host. | ||
9..12 | File Offset | |||
13..16 | File Size |
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Version Configuration Request frame is sent from the Host to the Moduleto query the version and image type information used to verify a new OTA image. The Module will respond with an OTA Version Configuration Response frame. The command has no payload.
| Anchor |
|---|
...
|
...
...
OTA Version Configuration Response Command
...
Byte Index
...
Field Name
...
Notes
...
0,1
...
Image Type
...
Unused - for backwards compatibility. Set to 0x0000
...
2..5
...
Firmware Version
...
Default value corresponds to that of the Application Version attribute of the Basic cluster.
...
6,7
...
Hardware Version
...
0x00 = Reserved
0x01 = EM250
0x02 = EM357 (default value)
0x03 = STM32W108
...
8..15
...
Signer EUI
...
Default 0x0024460000078074
...
- ( PH:0x0B, SH:0x25 )
The OTA Version Configuration Write Response frame is sent from the Host to the Module to configure the version and image type information used to verify an OTA imagethe Hostin response to an OTA Version Configuration Request.
Payload for OTA Version Configuration
...
Response Command
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Image Type | Unused - for backwards compatibility. Set to 0x0000 |
2..5 | Firmware Version | Set to 0xFFFFFFFF to retain defaultDefault value corresponds to that of the Application Version attribute of the Basic cluster. |
6,7 | Hardware VersionSet to 0xFFFF to retain default (EM357) | 0x00 = Reserved |
8..15 | Signer EUI | Set to 0xFFFFFFFF to retain default (0x0024460000078074).Default 0x0024460000078074 |
| Anchor |
|---|
...
|
The OTA Version Configuration Write frame is sent from the Host to the Moduleto the Hostto notify the Host of the reception of every 512 bytes of firmware downloaded through the OTA Bootload cluster. The frame is also sent on completion of the downloadconfigure the version and image type information used to verify an OTA image.
Payload for
...
OTA Version Configuration Write Command
Byte Index | Field Name | Notes | ||||||
|---|---|---|---|---|---|---|---|---|
0 | Status | Maps to ZCL Status codes: 0x00 = Success See /wiki/spaces/SPRHA17/pages/37093554 for all ZCL Status values. | 1,2 | Manufacturer Code | 3,4||||
Notes | ||||||||
0,1 | Image Type | Unused - for backwards compatibility. Set to 0x0000 | ||||||
2..5..8 | File Version | Will contain the value initially set in the Query Next Image Response / OTA Query Next Image Response frames by the Host. | 9..12 | File Offset | 13..16 | File Size | Firmware Version | Set to 0xFFFFFFFF to retain default. |
6,7 | Hardware Version | Set to 0xFFFF to retain default (EM357) 0x00 = Reserved | ||||||
8..15 | Signer EUI | Set to 0xFFFFFFFF to retain default (0x0024460000078074). |
...
Back to Top
| Anchor | ||||
|---|---|---|---|---|
|
The commands in this section facilitate over the air (OTA) server of the application operating on the Module. These commands have been implemented per the ZigBee HA 1.2 guidelines.
| Frame Name | Secondary Header Byte |
|---|
| Allowed Context | Sent By Host/Module |
|---|---|
| OTA Image Notification |
0x01 -
| 0x00 | All Contexts | ||
| OTA Query Next Image Request | 0x01 | All Contexts |
| OTA Query Next Image Response |
| 0x02 | All Contexts | |
| OTA Image Block Request |
No Restriction
No Restriction
No Restriction
No Restriction
| 0x03 | All Contexts | |
| OTA Image Block Response | 0x05 | All Contexts |
| OTA Upgrade End Request | 0x06 | All Contexts |
| OTA Upgrade End Response |
No Restriction
No Restriction
| 0x07 | All Contexts |
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Image Notification Command frame is sent from the Host to the Module. The Module will send an Image Notify ZCL command either broadcast or unicast depending on the received serial frame.
NOTE: Allow a wait time of 5000ms for the Image Notification Command Frame
Payload for OTA Image Notification Command
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Target Device Node ID |
2..9 | EUI64 Address | Target Device EUI64. All 0xFF indicates broadcast |
10 | Endpoint | 0xFF indicates a request on all endpoints. |
11 | Payload Type | 0x00 = Query jitter |
12 | Query Jitter | |
(13,14) | Manufacturer Code | Optional field, it is needed for payload type 0x01-0x03 |
(15,16) | Image Type | Unused - for backwards compatibility. Set to 0x0000 |
(17..20) | File Version | Will contain the value initially set in the Query Next Image Response / OTA Query Next Image Response frames by the Host. |
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Query Next Image Request frame is sent from the Module to the Host. The Module expects to receive an OTA Query Next Image Response frame in return.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Request OTA Device Node ID |
2..9 | EUI64 Address | Request OTA Device EUI64 |
10 | Endpoint | Request OTA Device Endpoint |
11 | Field Control | 8-bit Bitmap |
12,13 | Manufacturer Code | |
14,15 | Image Type | Unused - for backwards compatibility. Set to 0x0000 |
16..19 | File Version | Optional. Number used here will be echoed back in all subsequent frames for the transaction. For example, this field can be used by the Host to differentiate multiple concurrent updates, or for any other purpose the Host requires. |
(20,21) | Hardware Version | Optional. Bit 0 of "Field Control" must equal "1" to use this optional field. |
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Query Next Image Response frame is sent from the Host to the Module. The Module relays the frame to the OTA target device. If the target EUI64 is the module’s own EUI64, the module will process it locally.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Target Device Node ID. 0xFFFF indicates that the EUI64 is used |
2..9 | EUI64 Address | Target Device EUI64 |
10 | Endpoint | Target Device Endpoint |
11 | Status | 0x00 – Success |
12,13 | Manufacturer Code | |
14,15 | Image Type | Unused - for backwards compatibility. Set to 0x0000 |
16..19 | File Version | Will contain the value initially set in the Query Next Image Response / OTA Query Next Image Response frames by the Host. |
20..23 | Image Size |
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Image Block Request frame is sent from the Module to the Host. The Module expects to receive an OTA Image Block Response frame in response.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Request OTA Device Node ID |
2..9 | EUI64 Address | Request OTA Device EUI64 |
10 | Endpoint | Request OTA Device Endpoint |
11 | Field Control | 8-bit Bitmap |
12,13 | Manufacturer Code | |
14,15 | Image Type | Unused - for backwards compatibility. Set to 0x0000 |
16..19 | File Version | Will contain the value initially set in the Query Next Image Response / OTA Query Next Image Response frames by the Host. |
20..23 | File Offset | |
24 | Maximum Data Size | N < 50 |
Expected Host Action
The Host must process and respond to Image Block Request messages until the Module sends a Upgrade End Request
The Host must set status to MALFORMED_COMMAND (0x80) and return a 0 length data block if the Image Offset is outside the range of the file length.
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Image Block Response frame is sent from the Host to the Module. The Module relays the frame to the OTA target device. If the target EUI64 is the module’s own EUI64, the module will process it locally.
There are three possible return values for the OTA Image Block Response: Success, Wait for Data, and Abort. The payload differs for each one.differs for each one.
NOTE: Allow a wait time of 250ms for the Image Block Response Frame(except for last reponse in the sequence!)
Allow a wait time of 15000ms for the Last Image Block Response Frame
Payload for OTA Image Block Response Command on Success
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Target Device Node ID. 0xFFFF indicates that the EUI64 is used |
2..9 | EUI64 Address | Target Device EUI64 |
10 | Endpoint | Target Device Endpoint |
11 | Status | 0x95 = Abort |
| Anchor | ||||
|---|---|---|---|---|
|
The Upgrade End Request frame is sent from the Module to the Host. The Module expects to receive an Upgrade End Response frame in response.
NOTE: Allow a wait time of 30000ms for the Upgrade End Request Command Frame
Payload for OTA Upgrade End Request Command
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Request OTA Device Node ID |
2..9 | EUI64 Address | Request OTA Device EUI64 |
10 | Endpoint | Request OTA Device Endpoint |
11 | Status | 0x00 – Success |
12,13 | Manufacturer Code | |
14,15 | Image Type | Unused - for backwards compatibility. Set to 0x0000 |
16..19 | File Version | Will contain the value initially set in the Query Next Image Response / OTA Query Next Image Response frames by the Host. |
| Anchor | ||||
|---|---|---|---|---|
|
The OTA Upgrade End Response frame is sent from the Host to the Module in response to an OTA Upgrade End Request with success status. The Module relays the frame to the OTA target device. If the target EUI64 is the module’s own EUI64, the module will process it locally,
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Target Device Node ID. 0xFFFF indicates that the EUI64 is used. |
2..9 | EUI64 Address | Target Device EUI64. All 0xFF indicates broadcast |
10 | Endpoint | 0xFF indicates a request on all endpoints. |
11,12 | Manufacturer Code | |
13,14 | Image Type | Unused - for backwards compatibility. Set to 0x0000 |
15..18 | File Version | Will contain the value initially set in the Query Next Image Response / OTA Query Next Image Response frames by the Host. |
19..22 | Current Time | |
23..26 | Upgrade Time |
...
Back to Top
| Anchor | ||||
|---|---|---|---|---|
|
This section describes the commands that initiate and respond to network scans.
| Frame Name | Secondary Header Byte |
|---|
0x01 - Network Scan Response
0x02 -
| Allowed Context | Sent By Host/Module | ||
|---|---|---|---|
| Network Scan Request | 0x00 | All Contexts | Host |
| Network Scan Response | 0x01 | All Contexts | Module |
| Network Scan Complete |
Network Down Only
-
-
0x11 - Latency Response
-
| 0x02 | All Contexts | Module | |
| Latency Request | 0x10 | All Contexts | Host |
| Latency Response | 0x11 | All Contexts | Module |
| Anchor | ||||
|---|---|---|---|---|
|
The Network Scan Request is sent by the Host to the Module and serves to initiate Network Discovery. This command may only be transmitted when the application is in the Network Down state. The Module will respond with a Network Scan Response for each available network discovered and will also respond with a Network Scan Complete command once the scan request is complete.
...
Error Status | Enum | Description |
|---|---|---|
Success | 0x00 | Request successfully transmitted |
Invalid Call | 0x01 | Network down |
Invalid Data | 0x02 | The channel mask or scan duration value is invalid |
| Anchor | ||||
|---|---|---|---|---|
|
The Network Scan Response is sent by the Module to the Host for every response retrieved subsequent to the issuance of a Network Scan Request. Each response represents a beacon from a node within an active network that is in communications range of the Module.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Channel | 0x0B – 0x1A: channel of the responding network |
1,2 | Short PAN ID | |
3..10 | Extended PAN ID | |
11 | Permitting Joining | 0x00 = False - network does not permit joining |
12 | Stack Profile | 0x02 = ZigBee Pro |
13 | LQI | 0x00 – 0xFF LQI (Link Quality Indication) is a unit-less measurement range with the upper range (0xFF) representing the highest link quality. |
14 | RSSI | The RSSI (Received Signal Strength Indication) in dBm, represented as a signed integer. |
| Anchor | ||||
|---|---|---|---|---|
|
The Modulesends theNetwork Scan Completecommand to the Host on completion of a Network Scan Request. It should be noted that the issuance of the Network Scan Complete command does not necessarily indicate that all Network Scan Responses have yet been retrieved for the aforementioned request.
...
Byte Index | Field Name | Notes |
|---|---|---|
0 | Status | 0x00 = scan completed successfully |
| Anchor | ||||
|---|---|---|---|---|
|
The Latency Request frame is sent from Host to Module to test the round-trip latency between the Module and a destination node on the network. Upon receipt of this frame, the Module will send a packet to the destination node, and measure the time it takes to receive the acknowledgement.
...
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Destination Node ID | LSB first |
2 | Options Bitmask | Bit 0 = Enable Retry |
| Anchor | ||||
|---|---|---|---|---|
|
The Latency Response frame is sent from the Module to the Host with the result of the latency test initiated with a Latency Request.
...