In this section, you will find examples of how to describe a cluster with multiple revisions. You will also learn how to use dependencies to describe more dynamic structures of parameters.

Defining Clusters and Cluster Revisions

The following example demonstrates writing a manufacturer specific cluster:

<zigbee-metadata xsi:noNamespaceSchemaLocation="../../../../../../modules/zcl.metadata.service/src/main/resources/zcl-metadata-schema.xsd">

<clusters>

  <cluster name="Counter Cluster" id="0xfc03" version="1.0.0" manufacturer-code="0xcafe">

   <description>

   The Counter Cluster keeps a counter which can be incremented and decremented.

   </description>

   <server>

    <attributes>

     <attribute id="0x0000" name="CurrentCount" type="0x20">

      <description>The CurrentCount has 8-bits unsigned int value, incremented and decremented by the corresponding cluster commands.

      </description>

      <default-value>0x0000</default-value>

      <access>RE</access>

     </attribute>

    </attributes>

    <received-commands>

     <command id="0x0000" name="Increment" generated-command-id="default">

     <description>Increments the CurrentCount attribute.</description>

      </command>

     <command id="0x0001" name="Decrement" generated-command-id="default">

     <description>Decrements the CurrentCount attribute.</description>

     </command>

    </received-commands>

   </server>

  </cluster>

</clusters>

</zigbee-metadata>

The next example shows how to use or re-use the xml descriptions of previous cluster revisions:

<zigbee-metadata xsi:noNamespaceSchemaLocation="../../../../../../modules/zcl.metadata.service/src/main/resources/zcl-metadata-schema.xsd">

<clusters>

  <cluster name="Counter Cluster" id="0xfc03" version="1.0.0" cluster-revision="1" inherits-rev="0" manufacturer-code="0xcafe">

   <server>

    <attributes>

     <attribute id="0xfffd" name="ClusterRevision" type="0x21">

      <description>The ClusterRevision global attribute is mandatory for all cluster instances, client and server,

conforming to ZCL revision 6 (ZCL6) and later ZCL revisions. This cluster attribute represents the revision

of the cluster specification that has been implemented.

      </description>

      <default-value>0x01</default-value>

      <access>R</access>

     </attribute>

     <attribute id="0x0001" name="LastAccessTime" type="0xE2">

      <description>LastAccessTime attribute is a UTC_TIME value. It records the time of the last change of the

CurrentCount attribute.

      </description>

      <default-value>0x01</default-value>

      <access>R</access>

     </attribute>

    </attributes>

    <received-commands>

     <command id="0x0002" name="Increment+2" generated-command-id="default"></command>

      <description>Increments the CurrentCount attribute with 2.</description>

     <command id="0x0003" name="Decrement-2" generated-command-id="default">

      <description>Decrements the CurrentCount attribute with 2.</description></command>

    </received-commands>

   </server>

   <client>

    <attributes>

     <attribute id="0xfffd" name="ClusterRevision" type="0x21">

      <description>The ClusterRevision global attribute is mandatory for all cluster instances, client and server, conforming to ZCL revision 6 (ZCL6) and later ZCL revisions. This cluster attribute represents the revision of the cluster specification that has been implemented.

      </description>

      <default-value>0x01</default-value>

      <access>R</access>

     </attribute>

    </attributes>

   </client>

  </cluster>

</clusters>

</zigbee-metadata>

The below is an example of a revision 2 of the cluster above:

<zigbee-metadata xsi:noNamespaceSchemaLocation="../../../../../../modules/zcl.metadata.service/src/main/resources/zcl-metadata-schema.xsd">

<clusters>

  <cluster name="Counter Cluster" id="0xfc03" version="1.0.0" cluster-revision="2" inherits-rev="1" manufacturer-code="0xcafe">

   </cluster>

     <server>

       <attributes>

        <attribute id="0xfffd" name="ClusterRevision" type="0x21">

          <description>The ClusterRevision global attribute is mandatory for all cluster instances, client and server, conforming to ZCL revision 6 (ZCL6) and later ZCL revisions. This cluster attribute represents the revision of the                                            cluster specification that has been implemented.

          </description>

          <default-value>0x02</default-value>

          <access>R</access>

        </attribute>

       </attributes>

       <received-commands>

         <command id="0x0002" removed="true"/>

          <command id="0x0003" removed="true"/>

        </received-commands>

     </server>

     <client>

      <attributes>

        <attribute id="0xfffd" name="ClusterRevision" type="0x21">

        </attribute>

         <description>The ClusterRevision global attribute is mandatory for all cluster instances, client and server, conforming to ZCL revision 6 (ZCL6) and later ZCL revisions. This cluster attribute represents the revision of the                                cluster specification that has been implemented.

         </description>

         <default-value>0x02</default-value>

         <access>R</access>

      </attributes>

     </client>

</clusters>

</zigbee-metadata>

The following example demonstrates how to make a manufacturer-specific extension of a standard cluster:

<zigbee-metadata schema-version="2" xsi:noNamespaceSchemaLocation="../../../../../../modules/zcl.metadata.service/src/main/resources/zcl-metadata-schema.xsd">

 <clusters>

  <cluster name="Thermostat" id="0x0201" version="1.0.2" manufacturer-code="0x105E">

   <description>This cluster description contains a manufacturer-extension of the standard Thermostat Cluster.It adds the Zone Mode attribute.

   </description>

   <server>

    <attributes>

     <attribute id="0xE010" name="Zone Mode" type="0x30">

      <description>Zone Mode

      </description>

      <default-value>0x02</default-value>

      <enumeration>

       <pair key="0x00" value="Off"/>

       <pair key="0x01" value="Manual"/>

       <pair key="0x02" value="Schedule"/>

       <pair key="0x03" value="Manual Energy Saver"/>

       <pair key="0x04" value="Schedule Energy Saver"/>

       <pair key="0x05" value="Off"/>

       <pair key="0x06" value="Frost Protection"/>

       <pair key="0x07" value="System Auto Test"/>

      </enumeration>

      <access>RWE</access>

     </attribute>

    </attributes>

   </server>

  </cluster>

 </clusters>

</zigbee-metadata>

Parameter Dependencies

Oftentimes various parameter properties, such as data type and data size are provided for other parameters to depend on. In these cases ZCL Metadata uses a dependencies mechanism which allows describing more dynamic structures of parameters.

ZCL Metadata defines tree types of parameter dependencies:

• datatype - determine the type of the parameter, the type must be simple or complex ZigBee data type.
• datasize - determine the size of parameter, how much octets is occupied in the payload.
• presence - determine whether this parameter must exist in the payload depending on some condition, usually predefined value of other parameter.

In the following example the "Seconds Remaining" parameter presence depends on the Panel Status parameter. If Panel Status has a value of either 0x04 or 0x05, only then the Seconds Remaining parameter will be part of the payload.

<command name="Panel Status Changed" id="0x0008">
  <parameter-entry name="Panel Status" type="0x30">
    <enumeration>
    <pair key="0x00" value="Panel disarmed (all zones disarmed) and ready to arm"/>
    <pair key="0x01" value="Armed stay"/>
    <pair key="0x02" value="Armed night"/>
    <pair key="0x03" value="Armed away"/>
    <pair key="0x04" value="Exit delay"/>
    <pair key="0x05" value="Entry delay"/>
    <pair key="0x06" value="Not ready to arm"/>
    <!-- 0x07-0xFF - Reserved -->
    </enumeration>
  </parameter-entry>
  <parameter-entry name="Seconds Remaining" type="0x20">
    <description>Indicates the number of seconds remaining for the server to be in the state indicated in the PanelStatus parameter.</description>
    <default-value>0x00</default-value>
    <dependency type="presence">
    <!-- Provided if the PanelStatus parameter has a value of 0x04(Exit delay) or 0x05(Entry delay). -->
     <or>
        <dependency-entry name="Panel Status" value="0x04"/>
        <dependency-entry name="Panel Status" value="0x05"/>
      <or>
    </dependency>
  </parameter-entry>
</command>

In the following example you can see the case of dependency on a bit in a bitmask. PowerProfileStartTime parameter's presence depends on the Options parameter. If Options 0th bit is 1, then PowerProfileStartTime will be available in the payload.

<command name="GetPowerProfilePriceExtended" id="0x000B" optional="true" generated-command-id="0x0008">
    <parameter-entry name="Options" type="0x18">
        <bitmap>
            <field name="PowerProfileStartTime Field Present" bits="0"></field>
            <field name="Provide an estimation of the price" bits="1"/>
        </bitmap>
    </parameter-entry>
    <parameter-entry name="PowerProfileStartTime" type="0x21">
        <dependency type="presence">
            <dependency-entry name="PowerProfileStartTime Field Present" value="1" bits="0"/>
        </dependency>
    </parameter-entry>
</command>

Bellow an example of presence dependency on a range of bits in a bitmask. In this example four bits from "Options" parameter represents an integer value which is used to be compared with the dependency value.

<command name="Example" id="....">
    <parameter-entry name="Options" type="0x18">
        <bitmap>
            <field name="PowerProfileStartTime Field Present" bits="0-3"></field>
            <field name="Provide an estimation of the price" bits="4"/>
        </bitmap>
    </parameter-entry>
    <parameter-entry name="PowerProfileStartTime" type="0x21">
        <dependency type="presence">
            <!-- This parameter depends on the first four (0, 1, 2, 3) bits of Options parameter -->
            <dependency-entry name="PowerProfileStartTime Field Present" value="1" bits="0-3"/>
        </dependency>
    </parameter-entry>
</command>

Bellow you can see an example of data-size dependence on several bits of a bitmask. The length of the Alerts structure list depends on the Alerts Count parameter. Alerts Count first 4 bits define how long the list would be.

<command name="Get Alerts Response" id="0x0000">
    <description>This message is used to return household appliance current events and alerts.</description>
    <parameter-entry name="Alerts Count" type="0x20">
      <description>The Alerts Count field: the data field is a 8 bits in length unsigned integer,
      containing the following alerts structures count and alert structure type.</description>
      <bitmap>
        <field name="Number of Alerts" bits="0-3" />
        <field name="Type of alert" bits="4-7">
          <enumeration>
            <pair key="0x00" value="UNSTRUCTURED" />
          </enumeration>
        </field>
      </bitmap>
    </parameter-entry>
    <parameter-list name="Alerts structure list">
      <dependency type="datasize">
        <dependency-entry name="Alerts Count" bits="0-3"/>
      </dependency>
      <parameter-entry name="Alerts structure" type="0x22">
        <bitmap>
          <field name="Alert id" bits="0-7" />
          <field name="Category" bits="8-11">
            <enumeration>
              <pair key="0x00" value="Reserved" />
              <pair key="0x01" value="WARNING" />
              <pair key="0x02" value="DANGER" />
              <pair key="0x03" value="FAILURE" />
            </enumeration>
          </field>
          <!-- In original E@H docs Presence Recovery field have exactly the opposite values -->
          <field name="Presence recovery" bits="12-13">
            <enumeration>
              <pair key="0x00" value="RECOVERY" />
              <pair key="0x01" value="PRESENCE" />
            </enumeration>
          </field>
        </bitmap>
      </parameter-entry>
    </parameter-list>
  </command>