App Layer Protocol - ZCL

You can revisit “Endpoint and Cluster”.

Commands and Attributes

A device endpoint is a functional logical device. It could be either an “actuator” or a “sensor”.

There are two types of standard ZCL messages a device can send and receive, commands and attributes.

Note, commands and attributes are always associated with a cluster.

Attributes

Attributes are a list of properties of an endpoint, for example,

• An on/off device, is it currently on? or off?
• A “level control device” (such as a light dimmer), what is the current level?
• A sensor, what is the current reading?

Attributes can be values of configurations, as well, such as,

• A “level control device” (such as a light dimmer), what is the rate/speed to surn full on from full off?

Attribute ID

Each attribute within a cluster has a unique 16 bit ID.

Here is a list of attribute ID defined in Libertas IoT App.

Persistent Attributes and Control Attributes

Hornet and Libertas further defined the convept of persistent and control attributes.

An attribute shall be either persistent or control.

• Persistent attributes are also called config attributes. They change very infrequently, sometimes never change at all throughout lifetime.
• Control attributes represents the control state of a device, or sensor readings. They may change very frequently, for example, every time a user changes the control state.

Command

A command is usually a control signal that tells a device to “move”.

Commands are used for control signals that logically shouldn’t be expressed as attributes (properties change), for example,

• Tells a dimmer to turn full on at a specific rate, such as turon to level 255 in 2 seconds, in order to create a “glow effect”.
• Tells a on/off relay to turn on and hold for 10 minutes, then automatically turn off.

Command Structure

A command within a cluster always has a unique command ID, which is 8 bits (0-255).

This is a list of commands defined in Libertas Hub.

A command may define argument lists. It is an ordered list. Each argument in the list may have a different data type.

The command arguments can be perfectly represented as a C struct.

Commands and Attributes - Difference

Certain control signals are better expressed as commands, for example, “turn dimmer to maximum (255) at the rate of 2 seconds”. It makes less sense to design it as attributes.

However, attributes can also be used to represent user actions. Hornet, like Zigbee, has two different ways to update attributes:

1. Write - Shalled be interpreted as user action (control signal).
2. Report - The attribute values may not be changed immediately, though it is the up-to-date value! Thus it shall not be interpreted as user control. A device may periodically report it’s states.
3. Query - A device may send a query request to another device for a list of attributes. The attributes as query response shall not be interpreted as user control.

Firmware Developer’s Responsibility

Implementing zcl_data_indication

/**
 * @brief Developer implemented function to process incoming ZCL messages.
 * 
 * @param apsdu The APS message that carries the ZCL message.
 * @param header The ZCL message header, for convinence.
 * @param payload_end The end of ZCL mesaage payload. Note the start of payload is `(void *)(header + 1)`.
 * @param status The status. See below return value for more details.
 * @return uint8_t Returns 1 if the message is processed and responded, the status will be ignored.
 * Returns 0 if the message is not processed, then *status is the error code.
 */
extern uint8_t zcl_data_indication(apsdu_in_t *apsdu,
		const zcl_header_t *header,
		const uint8_t *payload_end,
		uint8_t *status);

Note:

• If ZCL_FRAME_TYPE_PROFILE_CMD == header->fcf.type then it is an attributes message.
  • header->cmd represents the attributes operation command, it can be the following:
    • ZCL_CMD_WRITE - Wriite attributes
    • ZCL_CMD_REPORT - Report attributes
    • ZCL_CMD_READ - Query attributes
    • ZCL_CMD_READ_RSP - Query response
  • Payload contains the encoded attributes list.
• If ZCL_FRAME_TYPE_SPECIFIC_CMD == header->fcf.type then it is an command message.
  • header->cmd represents the command ID.
  • Payload is the content of the command.
• Again, payload is between (void *)(header + 1) and payload_end.

Sending ZCL Messages

Firmware may send a ZCL message as an APSDU message.

Helper API

Mapping C Struct to List of Attributes

Process ZCL Attribute Messages

Create ZCL Attribute messages

ZCL Command Messages