Issue Launching ZAP GUI with Custom Cluster in NCS v3.0.0-preview2

[Rahul_Chauhan]

Hello Team,

I’m working on creating a custom Matter cluster using the instructions provided in the Nordic documentation: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/protocols/matter/getting_started/custom_clusters.html#ug-matter-creating-custom-cluster

I’m currently using NCS v3.0.0-preview2 and have successfully completed Step 1 using the following command:

1.west zap-append /home/rahul/Downloads/MyCluster.xml \
-b /home/rahul/ncs/v3.0.0-preview2/modules/lib/matter/src/app/zap-templates/zcl/zcl.json \
-o ~/nrf/template/zcl.json

This correctly created the zcl.json file at ~/nrf/template/zcl.json, which includes both standard and my custom cluster.

However, when I proceed to Step 2 and try launching the ZAP GUI with the following command:

cd ~/nrf/template
2.west zap-gui -j ./zcl.json --clusters /home/rahul/Downloads/MyCluster.xml

I encounter an error.

I also tried running just:

west zap-gui -j ./zcl.json

But that also results in an error. Unfortunately, the documentation doesn’t specify what the exact requirements are for this version of NCS, or how to troubleshoot west zap-gui issues.

Could you please help me understand how to resolve this? Is there a known issue with west zap-gui in v3.0.0-preview2, or is there an alternative method I should try?

Please let me know what logs or details would be helpful to share further.

Thanks in advance,
Rahul Chauhan

   

[AHaug]

Hi Rahul,

I see that you're using the preview release of NCS v3.0.0. Unless there is any specific reasons for using the preview release. Could you try by following the documentation for a more stable, fully tagged release such as NCS v2.9.1?

Kind regards,
Andreas

[Rahul_Chauhan]

Hi Andreas,

Thanks again for the suggestion.

I’ve used NCS v2.9.1 before, but it doesn’t support west zap-append or custom Matter clusters—so I moved to the v3.0.0 series.

I tested with:

• v3.0.0-rc1

• v3.0.0-preview1

• v3.0.0-preview2

But I’m still getting this error when launching ZAP or generating output:

This Error show

FATAL ERROR: command exited with status -6: /home/rahul/ncs/v3.0.0-rc1/modules/lib/matter/.zap-install/zap /home/rahul/nrf/template/src/default_zap/template.zap --zcl /home/rahul/ncs/v3.0.0-rc1/modules/lib/matter/src/app/zap-templates/zcl/zcl.json --gen /home/rahul/ncs/v3.0.0-rc1/modules/lib/matter/src/app/zap-templates/app-templates.json --tempState

It seems related to the ZAP environment or how zcl.json and templates are handled in these versions.

Is there a known fix or workaround?

Happy to share logs or files if needed.

Best,
Rahul Chauhan

[AHaug]

Hi,

Both me and several of my colleagues have tried to reproduce the issue without any success. Here's the following steps we've used

1. cd nrf/samples/template
2. Copy  MyCluster.xml content from step 2 of the mentioned guide into a new file in the Template sample directory.
3. west zap-gui -j ./zcl.json --clusters ./MyCluster.xml

Could you triple check that you've followed these exact steps?

Kind regards,
Andreas

[rahul@123]

Hi AHaug ,

I am trying to open zap-gui tool for manufacturer_specific sample using below command

west zap-gui -j ./src/default_zap/zcl.json

but getting below error

Errro:

rahul@rahul-H510M-H-V2:~/nrf/manufacturer_specific$ west zap-gui -j ./src/default_zap/zcl.json
Using ZAP file: /home/rahul/nrf/manufacturer_specific/src/default_zap/manufacturer_specific.zap
Using ZCL file: /home/rahul/nrf/manufacturer_specific/src/default_zap/zcl.json
Using app templates: /home/rahul/ncs/v3.0.0/modules/lib/matter/src/app/zap-templates/app-templates.json
ZAP installation directory: /home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install
Found ZAP 2024.8.14 (up to date)
🔧 Using temporary state directory: /tmp/zap.Ax6DuA
[121749:0429/172609.960302:ERROR:bus.cc(407)] Failed to connect to the bus: '=' character not found or has no value following it
[121749:0429/172609.960336:ERROR:bus.cc(407)] Failed to connect to the bus: '=' character not found or has no value following it
[121749:0429/172609.960346:ERROR:bus.cc(407)] Failed to connect to the bus: '=' character not found or has no value following it
[121749:0429/172609.960353:ERROR:bus.cc(407)] Failed to connect to the bus: '=' character not found or has no value following it
Xlib:  extension "NV-GLX" missing on display ":0".
[121781:0429/172610.066499:ERROR:viz_main_impl.cc(196)] Exiting GPU process due to errors during initialization
Xlib:  extension "NV-GLX" missing on display ":0".
Error: 

Unknown cluster "Access Control" in attributeAccessInterfaceAttributes


    at loadZclJsonOrProperties (/home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install/resources/app.asar/dist/src-electron/zcl/zcl-loader-silabs.js:2066:27)
    at loadZclMetaFilesCommon (/home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install/resources/app.asar/dist/src-electron/zcl/zcl-loader.js:63:19)
    at Object.loadZclMetafiles (/home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install/resources/app.asar/dist/src-electron/zcl/zcl-loader.js:150:28)
    at startNormal (/home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install/resources/app.asar/dist/src-electron/main-process/startup.js:62:9)
    at Object.startUpMainInstance (/home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install/resources/app.asar/dist/src-electron/main-process/startup.js:744:20)
FATAL ERROR: Error::ThrowAsJavaScriptException napi_throw
FATAL ERROR: command exited with status -6: /home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install/zap /home/rahul/nrf/manufacturer_specific/src/default_zap/manufacturer_specific.zap --zcl /home/rahul/nrf/manufacturer_specific/src/default_zap/zcl.json --gen /home/rahul/ncs/v3.0.0/modules/lib/matter/src/app/zap-templates/app-templates.json --tempState
rahul@rahul-H510M-H-V2:~/nrf/manufacturer_specific$

We will try with the template sample if its working for it or not.

BR,

Rahul

[AHaug]

Hi Rahul,

Has anything changed on your end since last week? If not, could you try to follow the steps that resolved this case  Failedto customize Cluster as per document ?

Kind regards,
Andreas

[rahul@123]

Hi AHaug ,

I am able to add custom cluster with one boolean attribute in matter template application. The XML file generated through "nRF Connect Matter Manufacturer Cluster Editor tool" is buggy, I have to fix that manually. After that I have to add stub call back function in the zcl_callbacks.cpp file as I was getting undefined reference error.

I want to add attribute with struct type in my custom cluster. Through the editor tool it is not generating data in XML file. So I have manually added data in XML file which I don't know correct or not.

My structure type:

struct MyStruct

{

uint8_t width;

uint8_t length;

uint8_t height;

};

My XML File:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configurator>

   <struct name="MyStruct" isFabricScoped="true">
      <cluster code="0xFFF1FC01"/>
      <item fieldId="1" name="width" type="int8u" min="0" max="10" isFabricSensitive="true"/>
      <item fieldId="2" name="length" type="int8u" min="0" max="10" isFabricSensitive="true"/>
      <item fieldId="3" name="height" type="int8u" min="0" max="10" isFabricSensitive="true"/>
   </struct>

   <cluster>
      <domain>General</domain>
      <name>Mangoe</name>
      <code>0xFFF1FC01</code>
      <define>MANGOE</define>
      <description>The MyNewCluster cluster showcases a cluster manufacturer extensions</description>

      <attribute side="server" code="0xFFF10000" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>

      <attribute side="server" code="0xFFF10001" define="MY_STRUCT_ATTRIBUTE" type="MyStruct" length="1" writable="true" optional="false">MyStructAttribute</attribute>

      <command source="client" code="0xFFF10000" name="MyCommand" optional="false">
         <description>Command that takes two uint8 arguments and returns their sum.</description>
         <arg name="arg1" type="int8u"/>
         <arg name="arg2" type="int8u"/>
      </command>

      <event side="server" code="0xFFF10000" name="MyEvent" priority="info" optional="false">
         <description>Event that is generated by the server.</description>
         <arg name="arg1" type="int8u"/>
      </event>
   </cluster>

</configurator>

zap-gui command works fine, I am able to see my cluster and attribute in the gui tool.

west zap-gui -j zcl.json --cluster ./MyCluster.xml 

After that west zap-generate --full failed with below error:

rahul@rahul-H510M-H-V2:~/nrf/template_bh$ west zap-generate --full
ZAP installation directory: /home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install
Found ZAP 2024.8.14 (up to date)
Searching for zcl file from /home/rahul/nrf/template_bh/src/default_zap/template.zap
🔧 Using temporary state directory: /tmp/zapb5bbfdmw/zap.jK6eJ7
🤖 ZAP generation started:
    🔍 input files: /home/rahul/nrf/template_bh/src/default_zap/template.zap
    🔍 output pattern: /home/rahul/nrf/template_bh/src/default_zap/zap-generated
    🔍 using templates: /home/rahul/ncs/v3.0.0/modules/lib/matter/src/app/zap-templates/app-templates.json
    🔍 using zcl data: /home/rahul/nrf/template_bh/zcl.json
    🔍 zap version: ver. 2024.8.14, featureLevel 103, commit: dca1ad01b8affd07eae1a6ca23afc284067c151c from 2024-08-14T15:52:25.000Z, mode: binary, exe: /home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install/zap-cli
🕐 Setup time: 14s 91ms 
👉 using input file: /home/rahul/nrf/template_bh/src/default_zap/template.zap


🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨

Application is failing the Device Type Specification as follows: 

  - ⚠ Check Device Type Compliance on endpoint: 0, device type: MA-rootdevice, cluster: Localization Configuration, attribute: ActiveLocale needs to be enabled
  - ⚠ Check Device Type Compliance on endpoint: 0, device type: MA-rootdevice, cluster: Localization Configuration, attribute: SupportedLocales needs to be enabled

Application is failing the Cluster Specification as follows: 


🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨


👉 using output destination: /home/rahul/nrf/template_bh/src/default_zap/zap-generated
🕐 File loading time: 520ms
Error in endpoint_config helper: ERROR: Unknown size for non-external attribute: MyStructAttribute / 4293984257
🤖 Generating files:
    ✍  /home/rahul/nrf/template_bh/src/default_zap/zap-generated/callback-stub.cpp
    ✍  /home/rahul/nrf/template_bh/src/default_zap/zap-generated/gen_config.h
    ✍  /home/rahul/nrf/template_bh/src/default_zap/zap-generated/IMClusterCommandHandler.cpp
    ✍  /home/rahul/nrf/template_bh/src/default_zap/zap-generated/PluginApplicationCallbacks.h
    ✍  /home/rahul/nrf/template_bh/src/default_zap/zap-generated/access.h
⚠️  Errors:
    👎  /home/rahul/nrf/template_bh/src/default_zap/zap-generated/endpoint_config.h: ⛔ TypeError: Cannot read properties of undefined (reading 'toHTML')
Stack trace:

TypeError: Cannot read properties of undefined (reading 'toHTML')
    at replacePlaceholdersRecursivelyIn (/snapshot/zap/node_modules/promised-handlebars/lib/markers.js:96:31)
    at /snapshot/zap/node_modules/promised-handlebars/lib/markers.js:106:22
    at /snapshot/zap/node_modules/promised-handlebars/lib/replaceP.js:44:47
    at String.replace (<anonymous>)
    at replaceP (/snapshot/zap/node_modules/promised-handlebars/lib/replaceP.js:37:14)
    at replacePlaceholdersRecursivelyIn (/snapshot/zap/node_modules/promised-handlebars/lib/markers.js:102:20)
    at /snapshot/zap/node_modules/promised-handlebars/lib/markers.js:111:18
    at produceContent (/snapshot/zap/dist/src-electron/generator/template-engine.js:152:19)
    at generateSingleTemplate (/snapshot/zap/dist/src-electron/generator/generation-engine.js:540:27)
    at async Promise.all (index 5)
🕐 Generation time: 335ms 
{"endpoint_config.h":{}}
Error: Generation failed: /home/rahul/nrf/template_bh/src/default_zap/template.zap
    at generateSingleFile (/snapshot/zap/dist/src-electron/main-process/startup.js:496:19)
    at startGeneration (/snapshot/zap/dist/src-electron/main-process/startup.js:551:5)
Zap generation error: Error: Generation failed: /home/rahul/nrf/template_bh/src/default_zap/template.zap
Traceback (most recent call last):
  File "/home/rahul/ncs/v3.0.0/modules/lib/matter/scripts/tools/zap/generate.py", line 404, in <module>
    main()
  File "/home/rahul/ncs/v3.0.0/modules/lib/matter/scripts/tools/zap/generate.py", line 382, in main
    runGeneration(cmdLineArgs)
  File "/home/rahul/ncs/v3.0.0/modules/lib/matter/scripts/tools/zap/generate.py", line 240, in runGeneration
    tool.run('generate', *args)
  File "/home/rahul/ncs/v3.0.0/modules/lib/matter/scripts/tools/zap/zap_execution.py", line 109, in run
    subprocess.check_call(
  File "/home/rahul/ncs/toolchains/7cbc0036f4/usr/local/lib/python3.12/subprocess.py", line 413, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['/home/rahul/ncs/v3.0.0/modules/lib/matter/.zap-install/zap-cli', 'generate', '-z', '/home/rahul/nrf/template_bh/zcl.json', '-g', '/home/rahul/ncs/v3.0.0/modules/lib/matter/src/app/zap-templates/app-templates.json', '-o', '/home/rahul/nrf/template_bh/src/default_zap/zap-generated', '-i', '/home/rahul/nrf/template_bh/src/default_zap/template.zap', '--tempState']' returned non-zero exit status 1.
FATAL ERROR: command exited with status 1: /home/rahul/ncs/toolchains/7cbc0036f4/usr/local/bin/python3.12 /home/rahul/ncs/v3.0.0/modules/lib/matter/scripts/tools/zap/generate.py /home/rahul/nrf/template_bh/src/default_zap/template.zap -o /home/rahul/nrf/template_bh/src/default_zap/zap-generated -t /home/rahul/ncs/v3.0.0/modules/lib/matter/src/app/zap-templates/app-templates.json
rahul@rahul-H510M-H-V2:~/nrf/template_bh$ 

Can you please provide some guidance here.

NCS version: v3.0.0

Board: nrf54l15dk

BR,

Rahul

[AHaug]

Hi Rahul,

Looks like the tool complains about multiple things,

• Application is failing the Device Type Specification as follows:

-  Check Device Type Compliance on endpoint: 0, device type: MA-rootdevice, cluster: Localization Configuration, attribute: ActiveLocale needs to be enabled
-  Check Device Type Compliance on endpoint: 0, device type: MA-rootdevice, cluster: Localization Configuration, attribute: SupportedLocales needs to be enabled

•  Length of your custom struct:

Application is failing the Cluster Specification as follows:
 using output destination: /home/rahul/nrf/template_bh/src/default_zap/zap-generated
 File loading time: 520ms
Error in endpoint_config helper: ERROR: Unknown size for non-external attribute: MyStructAttribute / 4293984257

• Reading the zap-generated endpoint.config.h

️ Errors:
 /home/rahul/nrf/template_bh/src/default_zap/zap-generated/endpoint_config.h:  TypeError: Cannot read properties of undefined (reading 'toHTML')

Are you able to resolve these errors? I assume they refer to your configurations of your custom clusters that's causing htis

Kind regards,
Andreas