The Zigbee Cluster Library  (ZCL) defines a set of attributes and commands (clusters) that can be supported in multiple Zigbee profiles. The ZCL commands are typically required when developing a Zigbee product that will interoperate in a public profile such as home automation or smart energy, or when communicating with Zigbee devices from other vendors.

Transmitting ZCL Commands

Having accessed a device's endpoints, as described in the "Device and Service Discovery" section here, it is possible to check - which profiles and clusters are supported by an endpoint from its simple descriptor. To do so:

Get a ClusterDescription object from the ZCL Metadata Service and then get either its:

• server section: getServerSectionDescription() and a CommandDescription through getReceivedCommandDescription(int cmdId) or
• client section: getClientSectionDescription() and a CommandDescription through getGeneratedCommandDescription(int cmdId)

Bundles that define ZCL metadata contain interfaces, which contain IDs of the metadata elements. These interfaces enable retrieving a specific metadata element without having to look up its ID. Although not required, using these interfaces when specifying an ID is strongly recommended as it greatly improves code readability.

Once you have obtained a CommandDescription object, use getParameterDescriptions() to get an array of ParameterDescription objects, which specify the parameters that need to be passed when sending the command in the exact order in which they need to be passed.

ParameterDescription objects contain name, description, ZCL data type, default value, minimum value, maximum value and dependencies. A ParameterDescription holds dependencies when the presence or data type of a parameter depends on the value(s) of previous parameters. All dependencies specify the ParameterDescription object that describes the parameter, which the original parameter depends on (getDependencyParameter()). Currently there are 3 main types of dependencies (you can determine a dependency's type with getDependencyType()):

• PresenceDependency - A parameter will only be present if its value specified by getDependencyParameter() has a specific value (getDesiredValue()). Also we might only be interested in a specific bit of the value and then usegetBitPosition.
• DataSizeDependency - A parameter which determines the size of parameter, how much octets is occupied in the payload.
• DataTypeDependency - A parameter with this dependency has an unknown data type. The data type will be determined by the value of the parameter specified by getDependencyParameter().

Use com.prosyst.mbs.services.zigbee.metadata.provider.ZCLFrameParser's createZCLFrame methods to construct a ZCLFrame:

The methods require to be specified: the CommandDescription object, an Object array of parameters, the frame control ID and (optionally) manufacturer code if the cluster is a cluster extension.

The Object array of parameters has to contain the parameters of the command and the ZCL data types need to be correctly mapped to Java types (see com.prosyst.mbs.services.zigbee.datatype.DataTypes).

Dependencies need to be taken into account when constructing the parameter array.

The two most common frame IDs are specified as constants in ZCLFrameParser - CLUSTER_SPECIFIC_FRAME_CONTROL for cluster specific commands and GENERAL_COMMANDS_FRAME_CONTROL for general commands.

Get the resulting ZCLFrame and pass it to the ZigBeeMessage instance used for sending requests over the TransmitService (see "Transmit Commands to ZigBee Nodes" here).

Sending ZCL General Commands

Use a utility (com.prosyst.mbs.services.zigbee.zcl.utils.ZCLGeneralCommandsUtils) to easily send general messages by directly specifying: the target ZigBee device, profile ID, cluster ID and the command-specific input arguments. The utility offers Java methods to send commands "discover attributes", "read attributes" and "write attributes" and to configure reporting. In order to send general commands:

• Use device discovery to access the ZigBeeDevice object for the target device.
• Obtain reference to the ZCLMetaDataService from the OSGi registry.
• Use ZCLGeneralCommands static methods.

Processing Metadata for General ZCL Commands

If the ZCL General Commands utility is not capable of handling a specific case of general command usage, processing ZCL metadata and retrieving the required payload is possible, the same way as using a cluster specific command. Use GENERAL_COMMANDS_FRAME_CONTROL as a frame control int when constructing the ZCL Frame.

The ZCL Metadata API contains special extensions to CommandDescription and ParameterDescription representing the general profile-wide commands ("read attributes", "read attributes response", "write attributes", etc.) of the ZCL specification. They are available in the com.prosyst.mbs.services.zigbee.metadata.provider package.

The IDs of the ZCL general commands are available as fields of the com.prosyst.mbs.services.zigbee.zcl.general.metadata.GeneralCommands interface.