Matter : manufacturer specific cluster

[abollaert]

Hi,

We're currently developing a Matter product based on the nRF5340 SoC, and we would want to add some custom (manufacturer specific) functionality. According to the specification (coren, §7.19, Manufacturer Specific Extensions) this is possible if you define a cluster in the manufacturer-specific range (0xFC00 - 0xFFFE).

So what I did is create an XML file defining my custom cluster, like so:

<?xml version="1.0"?>
<configurator>
  <domain name="Manufacturer"/>

  <cluster manufacturerCode="0xFFF1">
    <domain>Manufacturer</domain>
    <name>MyCluster</name>
    <code>0xfc00</code>
    <define>MY_CUSTOM_CLUSTER</define>
    <description>Manufacturer specific cluster test.</description>
    
    <attribute side="server" code="0x0000" define="MY_ATTRIBUTE" type="INT32U" min="0x00000000" max="0xFFFFFFFF" writable="false" optional="false">Test manufacturer specific attribute.</attribute>

    <command source="client" code="0x00" name="Command" optional="false">
      <description>Test command.</description>
    </command>
  </cluster>
</configurator>

and I added it through the ZCL extension in my zap tool. It loads, and I can see my cluster:

I can now select my attribute, command, and save.

However, when generating the resulting code I get an error:

Error: group_id not found.
    at enhancedItem (/snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js)
    at /snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js
    at Array.forEach (<anonymous>)
    at /snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js
    at Array.forEach (<anonymous>)
    at enhancedCommands (/snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js)
    at Object.init (/snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js)
Error: group_id not found.
    at enhancedItem (/snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js)
    at /snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js
    at Array.forEach (<anonymous>)
    at /snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js
    at Array.forEach (<anonymous>)
    at enhancedCommands (/snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js)
    at Object.init (/snapshot/zap/dist/src-electron/generator/matter/app/zap-templates/common/ClustersHelper.js)

So how does one add a custom cluster to a device? The documentation does not seem to mention anything outside already defined clusters.

Kind regards and thanks

-Alex

[Sigurd Hellesvik]

Hi,

I do not know of any such guide.

Here is a quote from out developers:

"It is possible to add some custom clusters and control them over Matter, however they will not be Matter certified data objects. They would need to add support for such cluster on the both sides of a communication, so cluster server and a cluster client. If it would be supported by the nRF based accessory and Matter controller it should work fine. Unfortunately we don't have much experience in such area, as we didn't add any custom clusters, but I think they would need to create a .xml file describing the cluster in a way compatible with the ZAP Tool, so the tool that is the used in Matter to generate code to handle this cluster data in the stack."

So it looks like you are on the right track here.

I can help you look into why your test fails, but first, can you refer me to where you learned how to create that XML file? (So we are on the same page)

Regards,
Sigurd Hellesvik

[abollaert]

I don't particularly care about certification for this cluster, I just want to expose some specific end of line test related functionality that gets disabled later on (there's some calibration and self test that needs to happen before the product gets shipped, so we want to do this over Matter (or Thread at least so we also tested the whole Matter communication as well). It would also allow us to use chip-tool to invoke the commands and read the attributes.

As for the XML files : I just took a look at how the standard clusters are defined, the ZCL templates are in ${NCS_ROOT}/modules/lib/matter/src/app/zap-templates/zcl/data-model/chip.

The format seems to be something that came from SiLabs that came from Ember (suppose that was the original Zigbee stack). Couldn't find an XSD to go with it though, although there should be one somewhere.

[abollaert]

I also asked the same question in the #zap channel of the CSA alliance slack, and they told me I had to update the zcl.json file that seems to function as a sort of manifest for the whole datamodel. That would mean I would have to patch up the NCS itself as well to do this.

In any case it appears that it's not a use case that has been really worked out yet, so it's rather messy.

[Sigurd Hellesvik]

abollaert said:

I also asked the same question in the #zap channel of the CSA alliance slack, and they told me I had to update the zcl.json file that seems to function as a sort of manifest for the whole datamodel. That would mean I would have to patch up the NCS itself as well to do this.

They know this better than me.
But yea, if they say you have to update the zcl.json file, it could sound like you need a patch.

abollaert said:

In any case it appears that it's not a use case that has been really worked out yet, so it's rather messy.

That is my view of the use case as well.

Let me know if you have any other questions

Regards,
Sigurd Hellesvik