A ZCL Metadata Provider describes a set of clusters, profiles and devices, which are used by the ZCL Metadata service to process ZCL frames received or sent by the IoT Gateway SDK ZigBee implementation. It provides XML-based descriptions of ZCL clusters and profiles to the other ZigBee modules (device access hdm adapter, console commands, visual editors and test tools).

The Zigbee Module has built-in metadata providers for most functional domains which are provided by the ZCL specification. In this case the definition of each functional domain is organized in a separate bundle provider. Home Automation and Smart Energy profile descriptions are also included in the ZigBee Module providers.

When a bundle is installed in the framework, it is checked for availability of zcl-metadata resource folder in its jar file. If present, it is considered as a Metadata Provider. Then based on a check in the ZCL metadata service configuration, the bundle is considered either a Default Provider or an Extension Provider.

• Default Providers - providers which are preliminary built-in and installed with the Bosch Iot Gateway ZigBee module. They are mandatory and persistent for the configuration, they can't be deleted at runtime. The ZCL MetaData Bundle first processes all ZCL definitions from the default providers before registering OSGi service and taking further actions.
• Extension Providers - additional providers which can be installed in order to provide some customization into the ZigBee Module. For some applications ZCL Metadata must be extended with extra clusters and profiles. The extensions are optional depending on the functionality which the ZigBee module must provide. ZCL metadata service configuration will be updated with the symbolic name of the bundle when a provider extension is installed and processed. The provider name will be removed from the configuration in case its bundle was uninstalled.
• Profile specific cluster list - since IoT SDK 9.2 clusters are either public and originating from the ZCL Specification or manufacturer-specific. Profile-specific clusters are supported only for special cases, e.g. to support legacy devices not conforming to the specification. Some devices communicating within a private profile send ZCL Frames without the manufacturer-specific bit but addressing manufacturer-specific clusters. This property defines which XML cluster descriptions should be treated as profile-specific by processing their profile-id attribute.

ZCL Metadata Service is registered asynchronously, it is waiting to parse and store all pending providers, which means all required default providers and initially registered extensions.

For a full list of ZCL metadata provider bundles contained in the Zigbee Module, please refer to the Bundles List.

XML Schema

ZCL Metadata Providers are bundles exporting XML files developed against an XML Schema - zcl-metadata-schema.xsd. The XML schema is located in the com.prosyst.mbs.zigbee.zcl.metadata.service bundle.To view the metadata schema, in your runtime installation, go to Runtime > osgi > bundles and search for the the Metadata Service bundle. You can also view the bundle contents in your Eclipse project, as follows:

Bundle Structure

The XML files reside in a resource folder "/zcl-metadata". This is a mandatory condition to identify bundle providers. A ZCL Metadata Provider is represented with the symbolic name of the bundle provider.

ZCL Metadata describes three types of entities from the Zigbee specification - clusters, profiles and devices. Each of these types appears as a main section in an XML description. One XML file can contain different numbers of clusters, profiles or devices descriptions. There is no restriction about the size of the list. Usually one XML file is used to provide the profile and its devices.

The current structure of the ZCL Metadata Providers follows the rules:

• For each cluster, there is a folder named after the cluster ID.
• For each cluster revision, there is a file inside the folder. For example, the basic cluster description files are: /0x0000/0x0001r0.xml, /0x0000/0x0001r1.xml and /0x0000/0x0001r2.xml.
• Derived cluster names have a "-d" suffix, e.g. 0x0008r2-d - a derived Level Control for Lighting cluster with revision 2.

Here is an example of a typical bundle structure:

Configurations

For a list of ZCL Metadata Providers Configurations in XML format, refer to the Setup Guide.

Adding Metadata for New Pofiles or Clusters

The ZigBee module provides a pluggable mechanism for adding metadata for new profiles (public or manufacturer-specific) as well as for extending the existing profiles and clusters.

In the ZigBee module metadata is defined in XML files which are accessed by the ZCL Metadata service in order to provide the information to users. To add new metadata:

• Write the XML files, according to the ZCL metadata schema definition as described above.
• Arrange the files in folders, according to the ZCL metadata conventions.
• Make them available to the service by packing them in a bundle (.jar file).