Extending the Zigbee Cluster Library#
Steps for Adding Custom Clusters and Commands Overview#
These are the high-level steps for adding custom clusters and commands:
Create an XML file with custom cluster and command definitions, using app/zcl/sample-extensions.xml as a template; put the XML file in your project directory.
In the Zigbee Cluster Configurator in the top bar click ZCL EXTENSIONS… and select the XML file from step 1.
The custom clusters should now be selectable in the Zigbee Cluster Configurator GUI along with the standard clusters. The custom clusters will appear under the domain name specified in the XML file—for example, <domain name="Ember"/>.
Implement custom cluster callbacks the same way as ZCL Command Handling callbacks. See ZCL Command Handling Callbacks for detailed instructions.
Manufacturer-Specific Commands and Clusters#
Developers may extend the Zigbee application layer using any of the following techniques:
Private Profile: The profile ID is a two-byte value passed in Zigbee messages in the Zigbee APS frame. For two Zigbee devices to interact at the application layer, they must have the same profile ID. If they do not, they will drop each other’s messages. A private profile is used to completely protect all interaction within a given system. If you are planning to use Zigbee for your network and link layers but in other respects are planning to have a closed system, you may wish to create a private Zigbee Profile. If you use a private profile, your devices will not be interoperable with any other Zigbee devices using other profiles.
Manufacturer-Specific Clusters: Any clusters with cluster IDs in the range 0xfc00 – 0xffff are considered manufacturer-specific and must have an associated two-byte manufacturer code. All commands and attributes within a manufacturer-specific cluster are also considered manufacturer-specific.
Example: In the sample-extensions.xml file included with the Zigbee Application Framework, Silicon Labs has defined a sample manufacturer-specific cluster with Cluster ID 0xfc00 and manufacturer code 0x1002 (Silicon Labs’ manufacturer code).
Manufacturer-Specific Commands: You can augment a standard Zigbee cluster by adding manufacturer-specific commands to that cluster. Manufacturer-specific commands within a standard Zigbee cluster may use the entire range of command IDs 0x00 – 0xff. A two-byte manufacturing code must be provided for the manufacturer-specific command so that the command can be distinguished from the standard Zigbee commands in that cluster.
Example: In the sample-extensions.xml file included with the application framework, Silicon Labs has defined three commands to extend the On/Off cluster: OffWithTransition, OnWithTransition, and ToggleWithTransition. These commands share the same command IDs as the standard Off, On, and Toggle commands in that cluster. However, they also include the manufacturer code 0x1002 indicating that they are Silicon Labs’ manufacturer-specific commands.
Manufacturer-Specific Attributes: Standard Zigbee clusters can be extended by adding manufacturer-specific attributes to your application. Manufacturer-specific attributes within a standard Zigbee cluster may use the entire attribute ID address space from 0x0000 to 0xffff. A two-byte manufacturer code must be included for each manufacturer-specific attribute so that it can be distinguished from non-manufacturer-specific attributes.
Example: In the sample-extensions.xml file included with the Zigbee Application Framework, Silicon Labs has defined a single attribute Transition Time which shares the same attribute ID with the on/off state in the on/off cluster 0x0000. However, the transition time attribute also contains the manufacturer code 0x1002 indicating that it is Silicon Labs’ manufacturer-specific attribute.
Note: Silicon Labs’ manufacturer code 0x1002 is defined by the Connectivity Standards Alliance and is included in the Manufacturer Code database (Zigbee document #053874). Manufacturer codes are required for the implementation of manufacturer-specific clusters, attributes, and commands. Unique manufacturer codes are provided by the Connectivity Standards Alliance for each requesting organization. To get a manufacturer code for your organization contact the Connectivity Standards Alliance at https://csa-iot.org/.
Limitations to Consider#
There are two notable limitations to consider when extending the Zigbee Application Framework with manufacturer-specific clusters, attributes, and commands:
All cluster IDs including those of manufacturer-specific clusters MUST be unique within a single device. The Zigbee Application Framework does not currently support overlapping manufacturer-specific cluster IDs within a single device. In other words, you cannot implement cluster 0xFC00 with manufacturer code 0xFEED AND cluster 0xFC00 with manufacturer code 0xBEEF on the SAME device. The Zigbee Application Framework assumes that ALL cluster IDs are unique regardless of the manufacturer code associated with them.
All attribute and command IDs within a manufacturer-specific cluster MUST be unique and are assumed to have the same manufacturer code as the cluster they are in. The Zigbee protocol does not support overlapping manufacturer-specific attributes or command IDs (with different manufacturer codes) WITHIN a manufacturer-specific cluster. The reason is simply that only a single manufacturer code is passed in the Zigbee application header. If the cluster addressed is in the manufacturer-specific range 0xFC00 – 0xFFFF, then the manufacturer code is assumed to apply to the cluster. This makes it impossible to address, for instance, Attribute 0x0000 with manufacturer code 0xFEED inside cluster 0x0000 with manufacturer code 0xBEEF. The Zigbee Application Framework does not even bother to store individual manufacturer codes for attributes within a manufacturer-specific cluster because the manufacturer code of the cluster is assumed to apply to all the attributes within it.
Defining ZCL Extensions within the Zigbee Application Framework and Project Configurator#
The entire ZCL is defined in XML format in the /SiliconLabs/SimplicityStudio/<version>/developer/sdks/gecko_sdk_suite/<version>/app/zcl directory. In addition to expected XML files such as general.xml or ha.xml that describe the clusters, commands and attributes associated with standard ZCL used by the Zigbee Application Framework, there is a sample extension file called, unsurprisingly, sample-extensions.xml. This XML file contains several sample Zigbee extensions including a custom cluster, custom attributes added to the on/off cluster, and custom commands added to the on/off cluster.
To extend the ZCL, you must create a similar extension file for your extensions and load them in the Zigbee Cluster Configurator as described in Steps for Adding Custom Clusters and Commands Overview. Additional documentation about extending the Zigbee Application Framework is included in the sample-extensions.xml file.
Note: Any multi-byte numeric constant values specified in the XML file should specify the full number of digits as hexadecimal, such as "0x000000000000" (for an int48u) rather than simply "0x00" or "0". This ensures that the proper default value will be added to the GENERATED_DEFAULTS define during generation.
Manufacturer-Specific Attribute APIs#
Some APIs in Zigbee Application Framework used to interact with attributes have been modified to take a manufacturer code as an argument.
Attribute Read and Write#
All of the read and write attribute functions have additional functions that take a manufacturer code along with the rest of the attribute-addressing information. When you read and write to a manufacturer-specific attribute, you must supply the manufacturer code for the attribute you wish to read or write so that it can be found in the attribute table. For example, you may read a standard Zigbee attribute using the function emberAfReadServerAttribute. However, if you call this function for a manufacturer-specific attribute no manufacturer Code argument allows you to properly identify your manufacturer-specific attribute, so the read will fail. If you wish to read a manufacturer-specific attribute, you must use the manufacturer-specific functions emberAfReadManufacturerSpecificServerAttribute and emberAfReadManufacturerSpecificClientAttribute. Both functions take a manufacturer code, which they pass on to the general function emberAfReadOrUpdateAttribute.
Separating the manufacturer-specific APIs into their own interface eliminates the need for code that is non-manufacturer-specific to pass around false manufacturer codes. This would be a waste of code space given the large number of attribute interactions that exist in the application framework.
Attribute Changed Callbacks#
Silicon Labs has also added manufacturer-specific attribute changed callbacks into the Zigbee Application Framework so that standard attribute callbacks do not need to waste code space checking a non-existent manufacturer code.