(0x05) ZCL Message Frames
( PH:0x05, SH:0x00 ) - Send ZCL Unicast Command
Overview
The Send ZCL Unicast command is sent by the Host to the Module in order to transmit a custom ZCL message to a target node. The command provides facilities for configuring the Encryption Level of the message, either with Network or Network + APS Encryption, as well as available Response Options, including custom sequence numbers, requiring an APS ACK or enabling processing of a corresponding response with a matching transaction sequence number.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Destination Node ID | |
2 | Destination Endpoint ID | |
3 | Local Endpoint ID | |
4,5 | Cluster ID | |
6 | Response Options | 8-Bit Bitmap: Bit 0: Custom Sequence Number |
7 | Encryption Level | 0x00 = Network Encryption Only |
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. 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 |
Effect on Receipt
The Module will attempt to issue the ZCL message over the network. The status of the transmission and its assigned sequence number will be relayed to the Host via a ZCL Send Status command.
If the Host wishes to know whether the Destination Node has successfully received a message, it should enable reception of APS ACK status messages via the Response Options field. On reception the Module relays these messages to the Host as ZCL APS Ack commands.
If the given message is a request (e.g., Read Attribute Request, Add Group, etc.) and the Host expects a response, it should enable the option to receive a ZCL Response Received command, via the same field. On reception of a message with a matching sequence number, the Module will relay the response to the Host via the ZCL Response Received command. If no response is received within a given interval, the Module will instead issue a ZCL Response Timeout command to the Host.
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x05, SH:0x01 ) - Send ZCL Multicast Command
Overview
The Send ZCL Multicast command is sent by the Host to the Module in order to prompt the latter to multicast a ZCL Message to a select Group of target devices on the network. Unlike Send ZCL Unicast messages, multicast messages cannot be APS-encrypted; that is, they are encrypted on the Network layer only.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Group ID | The Group ID of the Group to which the target devices belong. |
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 |
Effect on Receipt
The Module will try to transmit the message over the network, for reception and processing by the devices in the target Group. The status of the transmission and its assigned sequence number will be relayed to the Host via a ZCL Send Status command.
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x05, SH:0x02 ) - Send ZCL Broadcast Command
Overview
The Send ZCL Broadcast command is sent by the Host to the Module in order to prompt the latter to broadcast a ZCL Message to the network. Unlike Send ZCL Unicast messages, broadcast messages cannot be APS-encrypted; they are encrypted on the Network layer only.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0 | Broadcast Address | 0xFF = All Devices Any other address entered will default to 0xFD |
1 | Enable reception of APS ACK status messages (not used) | |
2 | Destination Endpoint ID | |
3 | Local Endpoint ID | |
4,5 | Cluster ID | |
6 | Radius | Number of Network Hops that this message may travel. 0 = Maximum |
7 | Response Options | 8-bit Bitmap: Bit 0: Custom Sequence Number |
8 | Frame Control | 8-bit Bitmap: Bits 0-1: 00 = ZCL General Command Bit 2: 1 = Manufacturer-Specific Command Bit 3: 0 = Client to Server Bit 4: 1 = Disable Default Response |
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 |
Effect on Receipt
The Module will try to broadcast the message over the network. The status of the transmission and its assigned sequence number will be relayed to the Host via a ZCL Send Status command.
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x05, SH:0x03 ) - ZCL Send Status Command
Overview
The ZCL Send Status message is sent by the Module to the Host after the transmission of a Send ZCL Unicast, Send ZCL Multicast or Send ZCL Broadcast. The message conveys the success or failure of the preceding transmission. If the Status indicates success, the message will also convey a value for the Transaction Sequence Number assigned to it.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0 | Status | 0x00 = Success, the message was successfully transmitted |
1 | Transaction Sequence Number | The ZCL Transaction Sequence Number assigned to this message, with a valid value in place only if the Status indicates Success. |
Effect on Receipt
No action is expected of the Host as the command is for notification purposes only. The Host may choose to display the Status in some manner, or it may also choose to re-send the message if the Status indicates an error occurred.
The Host also retains the option to store the Transaction Sequence Number associated with any outgoing message, such that it may match received ZCL Send Status messages to the requests that triggered them.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x05, SH:0x10 ) - ZCL APS Ack Command
Overview
The ZCL APS Ack command is sent by the Module to the Host on reception of an equivalent acknowledgement from the network, triggered by the initial transmission of a ZCL message that required an APS Ack among its Response Options. The Module will also generate the command when a given acknowledgment is not received and therefore times out.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0 | APS Ack Status | 0x00 = APS Ack Received |
1 | Transaction Sequence Number | Transaction Sequence Number that identifies the ZCL message that the Host originally sent out. |
Effect On Receipt
No action is expected from the Host. The command is for notification purposes only. If an APS Ack times out, the Host retains the option of retransmitting the original message.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x05, SH:0x11 ) - ZCL Response Received Command
Overview
The ZCL Response Received command is sent by the Module to the Host on reception of ZCL message from the network. That is, the command is generated if the Host had configured an outgoing Send ZCL Unicast or Send ZCL Broadcast with Response Options indicating that a response is expected (i.e. enable reception of ZCL Response Received with corresponding Transaction Sequence Number, though the application will also verify the Source Node ID and Command ID).
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Source Node ID | |
2 | Source Endpoint | |
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 Bit 2: 1 = Manufacturer-Specific Command Bit 4: 1 = Disable Default Response |
8,9 | Manufacturer Code | Applicable if Bit 2 of Frame Control field is enabled. |
10 | Transaction Sequence Number | The Transaction Sequence Number of the original request. |
11 | Command ID | |
12 | Payload Length | |
13..n | Payload |
Effect On Receipt
None.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x05, SH:0x12 ) - ZCL Response Timeout Command
Overview
The ZCL Response Timeout command is sent by the Module to the Host when an expected ZCL Response Received to an outgoing Send ZCL Unicast or Broadcast request is not received within a given interval after transmission. The fixed timeout period is 10 seconds.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Source Node ID | Expected Source Node ID of the response. |
2 | Source Endpoint ID | Expected source Endpoint ID of the response. |
3 | Local Endpoint ID | Expected ID of local endpoint on which the response will be received. |
4,5 | Cluster ID | Expected Cluster ID of the response. |
6 | Transaction Sequence Number | The Transaction Sequence Number of the original request. |
Effect On Receipt
None. The Host retains the option of retransmitting the original message or may otherwise register an error condition.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x05, SH:0x14 ) - Received Attribute Write Command
Overview
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
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 Specification 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. |
Effect On Receipt
None. The Host retains the option to handle a change to an attribute value in any desired manner.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x05, SH:0x20 ) - ZCL Passthru Message Command
Overview
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
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 |
Effect On Receipt
None.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x05, SH:0x30 ) - ZCL Read Attribute Request Command
Overview
The ZCL Read Attribute Request command is sent from the Host to the Module to query attributes on a target network device. The command may be used to query multiple attributes on a cluster, with the subsequent responses relayed to the Host one attribute at a time.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Address of the target device to query |
2 | Endpoint ID | Endpoint of the target device to query |
3,4 | Cluster ID | Cluster on the target device and application endpoint to query |
5 | Client/Server Cluster | 0x00 = Client |
6 | Number of Attributes | Number of attributes to query n |
7..6+2n | Attribute ID(s) | The Attribute ID(s) to query |
Effect on Receipt
The Module will transmit the query to the target device. The response is forwarded to the Host as a ZCL Read Attribute Response. If the response conveys multiple attributes, the Module relays each to the Host as an individual ZCL Read Attribute Response.
The table below lists the possible error statuses returned by the Status Response for this command.
Status Responses to ZCL Read Attribute Request Command
Error Status | Enum | Description |
|---|---|---|
Success | 0x00 | Request successfully transmitted |
Invalid Call | 0x01 | Network Down |
Invalid Data | 0x02 | Tried to read more than 15 attributes |
Incorrect Length | 0x07 | Tried to read 0 attributes or the length of the Attribute IDs list does not match what was indicated by the Number of Attributes field |
Not Enough Memory | 0x0C | Insufficient memory to send this message |
Unknown Failure | 0xFF |
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x05, SH:0x31 ) - ZCL Read Attribute Response Command
Overview
The ZCL Read Attribute Response command is sent by the Module to the Host in response to a successful ZCL Read Attribute Request. A response conveys the properties of a single queried attribute. As such, if the request successfully queried multiple attributes, the Host will in turn receive multiple responses.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | 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 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. |
Effect On Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Module.
( PH:0x05, SH:0x32 ) - ZCL Write Attribute Request Command
Overview
The ZCL Attribute Write Request is sent by the Host to the Module to modify the value of an attribute on a target network device. The command allows for multiple attributes on the same endpoint and cluster to be written to in one operation.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Node ID | Address of the target device |
2 | Endpoint | Endpoint of the target device |
3,4 | Cluster ID | Cluster on the target device and application endpoint |
5 | Client/Server Cluster | 0x00 = Client |
6 | Number of Attribute Write Records | Number of attributes to write to n each target attribute specified by an Attribute Write Record. |
7..n(3 + m) | Attribute Write Record(s) | Each target attribute specified by an (0x05) ZCL Message Frames#Attribute Write Record. |
Attribute Write Record
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. |
Effect on Receipt
The Module will transmit the command to the target device. The response is forwarded to Host as a ZCL Write Attribute Response.
The table below lists the possible status return values for this command.
Status Responses to ZCL Write Attribute Request Command
Error Status | Enum | Description |
|---|---|---|
Success | 0x00 | Request successfully transmitted |
Invalid Call | 0x01 | Network Down |
Invalid Data | 0x02 | Tried to read more than 10 attributes |
Incorrect Length | 0x07 | Tried to read 0 attributes or the length of the Attribute IDs list does not match what was indicated by the Number of Attributes field |
Not Enough Memory | 0x0C | Insufficient memory to send this message |
Unknown Failure | 0xFF |
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x05, SH:0x33 ) - ZCL Write Attribute Response Command
Overview
The ZCL Write Attribute Response is sent by the Module to the Host in response to a successful ZCL Write Attribute Request. The frame conveys the Overall Status of the write request. Note that if the Overall Status indicates success no Attribute Write Failed Records are included in the payload.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Source Node ID | Address of the responding device |
2 | Source Endpoint ID | Endpoint wherein attribute is hosted |
3,4 | Source Cluster ID | Cluster of the attribute |
5 | Client/Server Cluster | 0x00 = Client |
6 | Overall Status | 0x00 = All attribute write operations successful If the Overall Status indicates success no Attribute Write Failed Records are included in the payload. |
7 | Number of Attribute Write Failed Record(s) | The number of Attribute Write Failed Records n, where n corresponds to the number of attributes whose write operation failed. |
8..n | Attribute Write Failed Record(s) | Information on all attributes whose write operation failed. See the following table for details. |
If there are any attributes not written (i.e., the write attempt failed) then the payload of the ZCL Write Attribute Response command will contain an Attribute Write Failed Record for each one of the attributes not written.
Attribute Write Failed Record
Byte Index | Field Name | Notes |
|---|---|---|
0 | ZCL Status | 0x7E = Not Authorized 0x86 = Unsupported Attribute 0x87 = Invalid Value / Out of Range 0x88 = Read Only 0x8D = Invalid Data Type See this page for all ZCL Status values. |
1,2 | Attribute ID |
Effect on Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Host.
( PH:0x05, SH:0x09 ) - Set Up Reporting Config Request Command
Overview
The Set Up Reporting Config Request command is sent by Host to Module to modify the reporting configurations of an attribute on a target device. The configurations control how often the target device reports changes to the attribute.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
| 0..1 | Node ID | Node ID of the target |
2 | Local Endpoint ID | |
3 | Dest Endpoint ID | |
4..5 | Cluster ID | |
6 | Cluster Side | 0x00 = Client 0x01 = Server |
7..8 | Attribute ID | |
| 9 | Attribute Data Type | |
| 10..11 | Min Reporting Interval | |
| 12..13 | Max Reporting Interval | |
| 14..13+n | Reportable Change | where n is the length of the attribute value |
Effect on Receipt
Host will receive a Status Response indicating whether Module successfully sent out the request to the target device. If it is successful, then Host will also receive Set Up Reporting Config Response from the target device indicating whether or not the configuration is set up successfully.
Status Response to Set Up Reporting Config Request
| Error Status | Value | Notes |
|---|---|---|
Success | 0x00 | Request successfully transmitted |
Invalid Call | 0x01 | Network Down |
| Invalid Data | 0x02 | payload data invalid |
| Out of Memory | 0x0C | Outgoing queue full |
| Send Failure | 0x0D | network stack fail to send |
Allowed Context
All Context.
Sent By Host/Module
Host.
( PH:0x05, SH:0x0A ) - Set Up Reporting Config Response Command
Overview
The Set Up Reporting Config Response command is sent by Module to Host after Host has sent Set Up Reporting Config Request. The command indicates the status of whether or not the target device successfully set up the reporting configuration.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
| 0 | Status | 0x00 = Success |
Effect on Receipt
None.
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x05, SH:0x40 ) - Send Raw Unicast Command
Overview
Note: This feature is available in RapidConnect 3.4.x and above.
The Send Raw Unicast command is sent by the Host to the Module to unicast a raw message that does not follow the ZCL format. The Host may use this command to send unsecured, proprietary messages to a target device.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Destination Node ID | |
2 | Destination Endpoint ID | |
3 | Source Endpoint ID | |
4,5 | Cluster ID | |
6 | Payload Length | |
7..n | Payload |
Effect on Receipt
None.
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x05, SH:0x41 ) - Raw Passthru Message Command
Overview
Note: This feature is available in RapidConnect 3.4.x and above.
The Raw Passthru Message command is sent by the Module to the Host on reception of a message on a network with a proprietary profile.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Source Node ID | |
2 | Source Endpoint ID | |
3 | Local Endpoint ID | |
4,5 | Cluster ID | |
6 | Payload Length | |
7..n | Payload |
Effect on Receipt
None.
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x05, SH:0x42 ) - Send Raw Broadcast Command
Overview
Note: This feature is available in RapidConnect 3.4.x and above.
The Send Raw Broadcast command is sent by the Host to the Module to broadcast a raw message that does not follow the ZCL format. The Host may use this command to broadcast unsecured, proprietary messages to devices on the network.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
0,1 | Destination Node ID | 0xFF = All Devices 0xFD = All Non-Sleepy Devices 0xFC = All Routers and the Coordinator Any other address entered will default to 0xFD. |
2 | Destination Endpoint ID | |
3 | Source Endpoint ID | |
4,5 | Cluster ID | |
| 6 | Radius | Number of network hops this message may travel 0x00 = Maximum |
7 | Payload Length | |
8..n | Payload |
Effect on Receipt
None.
Allowed Context
Network Up.
Sent By Host/Module
Module.
Legal Notices
Copyright © 2020 MMB Networks, Inc. All rights reserved.
Confidential materials prepared and delivered by MMB Networks for receipt and review only by any partner subject to a valid and enforceable MMB Networks confidentiality agreement. Any receipt, review, or misuse of any of the content exchanged hereunder by any party not a party to this confidential exchange shall be subject to any and all rights available under the law. All rights, title and interest to the materials shall remain with MMB Networks.
Any suggestions provided to MMB Networks with respect to MMB Networks' products or services shall be collectively deemed “Feedback.” You, on behalf of yourself, or if you are providing Feedback on behalf of your employer or another entity, represent and warrant that you have full legal authority to bind such entity to these terms, agree to grant and hereby grant to MMB Networks a nonexclusive, perpetual, irrevocable, royalty free, worldwide license to use and otherwise exploit such Feedback within any MMB Networks products and services.