(0x05) ZCL Message Frames

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.

Secondary Headers

Primary Headers

( 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 Bit 1: Enable reception of APS ACK status messages Bit 2: Enable reception of ZCL Response Received with corresponding Transaction Sequence Number
7	Encryption Level	0x00 = Network Encryption Only 0x01 = Network + APS Encryption
8	Frame Control	8-Bit Bitmap: Bits 0-1: 00 = ZCL General Command 01 = Cluster-Specific Command Bit 2: 1 = Manufacturer-Specific Command Bit 3: 0 = Client to Server 1 = Server to Client Bit 4: 1 = Disable Default Response Bit 5-7: Reserved
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 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 Bit 1: Enable reception of APS ACK status messages Bit 2: Enable reception of ZCL Response Received command with corresponding Transaction Sequence Number
8	Frame Control	8-bit Bitmap: Bits 0-1: 00 = ZCL General Command 01 = Cluster-Specific Command Bit 2: 1 = Manufacturer-Specific Command Bit 3: 0 = Client to Server 1 = Server to Client Bit 4: 1 = Disable Default Response Bit 5-7: Reserved
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 0xFD = All Non-Sleepy Devices 0xFC = All routers and coordinator 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 Bit 1: Enable reception of APS ACK status messages Bit 2: Enable reception of ZCL Response Received command with corresponding Transaction Sequence Number
8	Frame Control	8-bit Bitmap: Bits 0-1: 00 = ZCL General Command 01 = Cluster-Specific Command Bit 2: 1 = Manufacturer-Specific Command Bit 3: 0 = Client to Server 1 = Server to Client Bit 4: 1 = Disable Default Response Bit 5-7: Reserved
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 0x01 = Invalid Call, the network is down or the application is not joined to a network 0x02 = Invalid Data 0x03 = Unsupported Command 0x04 = Storage Full 0x05 = No Entry Found 0x06 = Invalid Data Type 0x07 = Incorrect Length 0x08 = Endpoint Not Found 0x09 = Cluster Not Found 0x10 = Duplicate Data 0x11 = Busy 0x0C = Insufficient Memory, there is not enough available memory to transmit the message 0x0D = Send Failure 0x0F = Endpoint Configuration Locked 0xFF = Unknown Failure
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 0x0E = APS Ack Timed Out
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 0x01 = Network + APS Encryption
7	Frame Control	8-bit Bitmap: Bits 0,1: 00 = ZCL General Command 01 = Cluster-Specific Command Bit 2: 1 = Manufacturer-Specific Command Bit 3: 0 = Client to Server 1 = Server to Client Bit 4: 1 = Disable Default Response Bit 5-7: Reserved
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 0x01 = Server
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 0x01 = Network + APS Encryption
7	Frame Control	8-bit Bitmap: Bits 0-1: 00 = ZCL General Command 01 = Cluster-Specific Command Bit 2: 1 = Manufacturer-Specific Command Bit 3: 0 = Client to Server 1 = Server to Client Bit 4: 1 = Disable Default Response Bit 5-7: Reserved
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 0x01 = Server
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 0x01 = Server
6,7	Attribute ID	Corresponds to Attribute ID in request
8	ZCL Status	0x00 = Success 0x86 = Unsupported attribute 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 0x01 = Server
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 0x01 = Server
6	Overall Status	0x00 = All attribute write operations successful 0x01 = Some or all attribute write operations failed 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	Src 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.