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.
...
| 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 | ||||
|---|---|---|---|---|
|
...
| Anchor | ||||
|---|---|---|---|---|
|
The Reset command is sent from the Host to the Module, and prompts the Module to reboot. The command has no payload.
...
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. |
...
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 channel 26 is restricted. |
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. |
...
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. |
...
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. |
...
| 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 | ||||
|---|---|---|---|---|
|
...
| 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.
...
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 |
...
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 |
...
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. |
...
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 /wiki/spaces/SPRC2/pages/110563209 ZCL Specification 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. |
...
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 |
...
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. |
...
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 |
...
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. |
...
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. |
...
- (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 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 | 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 | ||||
|---|---|---|---|---|
|
...
There are three possible return values for the OTA Image Block Response: Success, Wait for Data, and Abort. The payload 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
...
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
...