How to custom cluster in Matter

[xiongwei.wang]

Hello, Nordic Team,

I'm currently working on implementing a custom cluster in the Matter application. However, I've encountered issues where the methods described in your documentation simply don’t work. Some of the commands mentioned are non-existent.

I followed this documentation: ​​Creating custom clusters in Matter application

But encountered an error stating that the --clusters parameter does not exist:

PS D:\Code\ncs291\custom_cluster> west zap-gui --clusters C:\ncs\v2.9.0\modules\lib\matter\data_model\1.4\clusters\OnOff.xml
usage: west zap-gui [-h] [-z ZAP_FILE] [-j ZCL_JSON] [-m MATTER_PATH]
west zap-gui: error: unexpected arguments: ['--clusters', 'C:\\ncs\\v2.9.0\\modules\\lib\\matter\\data_model\\1.4\\clusters\\OnOff.xml']

Even after manually adding the XML file to the ZAP GUI, issues persist. For example, device types become unavailable (all options disappear, including standard ones like "Generic Switch").

I also reviewed Google’s documentation, but parts of it are outdated. For instance:

Create a sample cluster  |  Matter  |  Google Home Developers

The referenced file all.xml no longer exists at the specified path:
src/app/zap-templates/zcl/data-model/all.xml:

src/app/zap-templates/zcl/data-model/all.xml


<?xml version="1.0"?>
<all xmlns:xi="http://www.w3.org/2001/XInclude">
   <xi:include href="chip/access-control-cluster.xml" />
   (...)
+  <xi:include href="chip/sample-mei-cluster.xml" />
</all>

Additionally, the Matter documentation provides only general guidance, lacking implementation details:

Implementing New Clusters & Device Types — Matter documentation

Adding new clusters and device types to the codegen — Matter documentation

While these documents outline which files to modify, I struggle with the code generation process due to my unfamiliarity with the workflow. Errors occur, but I can’t pinpoint their root cause.

​My questions:​​

1. How can I properly create a custom cluster?
2. Which tutorial is currently valid and functional?
3. Are there known issues with the zap-gui tool or recent changes to the workflow?

Any guidance or examples would be greatly appreciated. Thank you!

[Marte Myrvold]

Hi,

The nRF Connect SDK v2.9.0 does not support adding custom clusters using the west zap-gui or west zap-append commands. This feature will be added in v3.0.0, but you can test it out now using the release candidate (v3.0.0-rc1 tag) or the main branch.

Best regards,
Marte

[xiongwei.wang]

Hello, Marte.

It's great to see your reply, though I also feel a bit apologetic for troubling you again.

How significant are the differences between v3.0.0-rc1 and v3.0.0? Additionally, can I install it manually? Since the nRF plugin in VS Code doesn’t seem to directly support downloading v3.0.0-rc1, is there a manual installation guide?

[Marte Myrvold]

Hi,

If you click on the funnel in the upper right corner when installing the SDK, you can select to show all SDK versions. With this enabled, you should be able to see and install v3.0.0-rc1.

You can also install it using nRF Util on the command line as described under the "Command line" tabs in Installing the nRF Connect SDK. The command to install v3.0.0-rc1

nrfutil sdk-manager toolchain install --ncs-version v3.0.0-rc1

Best regards,
Marte