Added a new Matter west command and a guide for adding a custom cluster to ZCL #20163

ArekBalysNordic · 2025-02-03T14:19:11Z

Added zap_append command to the west.

use west zap-append -h to see all options.

Now you can add new clusters to the matter ZCL datamodel.
Use a west zap-append and provide the new cluster definitions as XML files to add them to the zcl.json file.
You can generate the new zcl.json file by providing -o, --output argument, or overwrite the existing one.

The zcl_generate is integrated with west zap-gui commands.
If you want to use it call the west zap-gui command with the additional argument --clusters.
You can provide multiple clusters at once.
If you provide an additional -j / --zcl-json argument alongside the --clusters argument to the west zap-gui command, the new zcl.json will be created and contain the new clusters.

NordicBuilder · 2025-02-03T14:20:21Z

The following west manifest projects have changed revision in this Pull Request:

Name	Old Revision	New Revision	Diff
matter	nrfconnect/sdk-connectedhomeip@`a0aea7e`	nrfconnect/sdk-connectedhomeip@`9dc37b1` (`master`)	nrfconnect/[email protected]

✅ All manifest checks OK

Note: This message is automatically posted and updated by the Manifest GitHub Action.

NordicBuilder · 2025-02-03T14:23:24Z

CI Information

^{To view the history of this post, clich the 'edited' button above}
Build number: 9

Inputs:

Sources:

sdk-nrf: PR head: e716887a1c7c8ac3895f4b375d7f43707b2e17cb
matter: PR head: 9dc37b19ff5ef1d1f467dc45e741b669e1f1afd5

more details

sdk-nrf:

PR head: e716887a1c7c8ac3895f4b375d7f43707b2e17cb
merge base: 161221a9aad455cb839cc06f8571e50bb288dfe2
target head (main): 0cccc03fa18953e2d9ba7c07c9e0fe42b01af04f
Diff

matter:

PR head: 9dc37b19ff5ef1d1f467dc45e741b669e1f1afd5
merge base: a0aea7ec002eab768238613bb18bd6562c04a160
Diff

Github labels

Enabled	Name	Description
	ci-disabled	Disable the ci execution
	ci-all-test	Run all of ci, no test spec filtering will be done
	ci-force-downstream	Force execution of downstream even if twister fails
	ci-run-twister	Force run twister
	ci-run-zephyr-twister	Force run zephyr twister

List of changed files detected by CI (13)

doc
│  ├── nrf
│  │  ├── protocols
│  │  │  ├── matter
│  │  │  │  ├── getting_started
│  │  │  │  │  ├── adding_clusters.rst
│  │  │  │  │  ├── images
│  │  │  │  │  │  ├── matter_create_accessory_custom_cluster.png
│  │  │  │  │  │  ├── matter_create_accessory_custom_cluster_attributes.png
│  │  │  │  │  │  ├── matter_create_accessory_custom_cluster_commands.png
│  │  │  │  │  │  │ matter_create_accessory_custom_cluster_events.png
│  │  │  │  │  │ tools.rst
│  │  ├── releases_and_maturity
│  │  │  ├── releases
│  │  │  │  │ release-notes-changelog.rst
modules
│  ├── lib
│  │  ├── matter
│  │  │  ├── .github
│  │  │  │  ├── workflows
│  │  │  │  │  │ release_tools.yaml
│  │  │  ├── scripts
│  │  │  │  ├── west
│  │  │  │  │  ├── west-commands.yml
│  │  │  │  │  ├── zap_append.py
│  │  │  │  │  ├── zap_common.py
│  │  │  │  │  │ zap_gui.py
west.yml

Outputs:

Toolchain

Version: 342151af73
Build docker image: docker-dtr.nordicsemi.no/sw-production/ncs-build:342151af73_bbe5b33786

Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped; ⚠️ Quarantine

◻️ Toolchain - Skipped: existing toolchain is used
✅ Build twister - Skipped: Skipping Build & Test as it succeeded in a previous run: 8
✅ Integration tests
- ✅ test-fw-nrfconnect-chip

Disabled integration tests

- desktop52_verification
- doc-internal
- test_ble_nrf_config
- test-fw-nrfconnect-apps
- test-fw-nrfconnect-ble_mesh
- test-fw-nrfconnect-ble_samples
- test-fw-nrfconnect-boot
- test-fw-nrfconnect-fem
- test-fw-nrfconnect-nfc
- test-fw-nrfconnect-nrf-iot_lwm2m
- test-fw-nrfconnect-nrf-iot_mosh
- test-fw-nrfconnect-nrf-iot_positioning
- test-fw-nrfconnect-nrf-iot_samples
- test-fw-nrfconnect-nrf-iot_serial_lte_modem
- test-fw-nrfconnect-nrf-iot_thingy91
- test-fw-nrfconnect-nrf-iot_zephyr_lwm2m
- test-fw-nrfconnect-nrf_crypto
- test-fw-nrfconnect-ps
- test-fw-nrfconnect-rpc
- test-fw-nrfconnect-rs
- test-fw-nrfconnect-tfm
- test-fw-nrfconnect-thread
- test-fw-nrfconnect-zigbee
- test-low-level
- test-sdk-audio
- test-sdk-dfu
- test-sdk-find-my
- test-sdk-mcuboot
- test-sdk-pmic-samples
- test-sdk-sidewalk
- test-sdk-wifi
- test-secdom-samples-public

Note: This message is automatically posted and updated by the CI

NordicBuilder · 2025-02-03T14:36:12Z

You can find the documentation preview for this PR at this link.

Note: This comment is automatically posted by the Documentation Publish GitHub Action.

doc/nrf/protocols/matter/getting_started/adding_clusters.rst

peknis · 2025-02-04T07:33:00Z

doc/nrf/protocols/matter/getting_started/adding_clusters.rst

+
+   .. note::
+      The descriptions of the elements above show only the basic functionality.
+      To see the full list of available elements for each part of the XML file, refer to the Matter Specification.


Link to the Matter spec?

It is not so easy. Matter spec can be obtained on a user's request, and it is not visible globally.

doc/nrf/protocols/matter/getting_started/adding_clusters.rst

doc/nrf/protocols/matter/getting_started/tools.rst

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

doc/nrf/protocols/matter/getting_started/tools.rst

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

doc/nrf/protocols/matter/getting_started/adding_clusters.rst

kkasperczyk-no · 2025-02-05T07:37:07Z

doc/nrf/protocols/matter/getting_started/tools.rst

+
+To simplify adding new custom clusters to the Matter ZCL database and generating the required C++ files, you can use the ``zap-append`` west command.
+The command converts the provided XML files with the cluster definition to the JSON format and adds them to the data model definition file (:file:`zcl.json`).
+Using this command, you can add the cluster to the existing data model definition file located in :file:`<default Matter SDK location>/src/app/zap-templates/zcl/zcl.json` or create a new one.


or create a new one.

A new file, right? Sorry, but from the context it's a bit unclear to me if we create new cluster or new json file.

Changed and explained it better.

doc/nrf/protocols/matter/getting_started/tools.rst

ArekBalysNordic · 2025-02-06T08:43:30Z

@nrfconnect/ncs-doc-leads could you please review?

doc/nrf/protocols/matter/getting_started/adding_clusters.rst

doc/nrf/protocols/matter/getting_started/tools.rst

This guide describes a process of adding the XML file with a new custom cluster definition to the existing Matter database. Described new `west zap` commands and their usage. Signed-off-by: Arkadiusz Balys <[email protected]>

ArekBalysNordic requested a review from a team February 3, 2025 14:19

ArekBalysNordic requested review from a team as code owners February 3, 2025 14:19

github-actions bot added doc-required PR must not be merged without tech writer approval. manifest labels Feb 3, 2025

NordicBuilder added manifest-matter DNM labels Feb 3, 2025

peknis requested changes Feb 4, 2025

View reviewed changes

kkasperczyk-no reviewed Feb 5, 2025

View reviewed changes

ArekBalysNordic force-pushed the zcl_command_description branch from 64b232a to 339ca25 Compare February 5, 2025 10:13

NordicBuilder added the manifest-zephyr label Feb 5, 2025

ArekBalysNordic requested review from peknis and kkasperczyk-no February 5, 2025 10:15

kkasperczyk-no approved these changes Feb 5, 2025

View reviewed changes

ArekBalysNordic force-pushed the zcl_command_description branch 2 times, most recently from 64fde09 to 451c166 Compare February 5, 2025 10:31

peknis requested changes Feb 5, 2025

View reviewed changes

doc/nrf/protocols/matter/getting_started/tools.rst Outdated Show resolved Hide resolved

ArekBalysNordic force-pushed the zcl_command_description branch 3 times, most recently from 32fd758 to 6908057 Compare February 5, 2025 15:09

ArekBalysNordic requested a review from peknis February 5, 2025 15:10

peknis approved these changes Feb 6, 2025

View reviewed changes

maciejbaczmanski approved these changes Feb 6, 2025

View reviewed changes

umapraseeda reviewed Feb 6, 2025

View reviewed changes

ArekBalysNordic force-pushed the zcl_command_description branch from 6908057 to e716887 Compare February 6, 2025 12:54

NordicBuilder removed the DNM label Feb 6, 2025

umapraseeda approved these changes Feb 6, 2025

View reviewed changes

ArekBalysNordic merged commit 93bcd52 into nrfconnect:main Feb 6, 2025
13 of 14 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added a new Matter west command and a guide for adding a custom cluster to ZCL #20163

Added a new Matter west command and a guide for adding a custom cluster to ZCL #20163

ArekBalysNordic commented Feb 3, 2025

NordicBuilder commented Feb 3, 2025 •

edited

Loading

NordicBuilder commented Feb 3, 2025 •

edited

Loading

NordicBuilder commented Feb 3, 2025

peknis Feb 4, 2025

ArekBalysNordic Feb 5, 2025

kkasperczyk-no Feb 5, 2025

ArekBalysNordic Feb 5, 2025

ArekBalysNordic commented Feb 6, 2025

Added a new Matter west command and a guide for adding a custom cluster to ZCL #20163

Added a new Matter west command and a guide for adding a custom cluster to ZCL #20163

Conversation

ArekBalysNordic commented Feb 3, 2025

NordicBuilder commented Feb 3, 2025 • edited Loading

NordicBuilder commented Feb 3, 2025 • edited Loading

CI Information

Inputs:

Sources:

Github labels

Outputs:

Toolchain

Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped; ⚠️ Quarantine

NordicBuilder commented Feb 3, 2025

peknis Feb 4, 2025

Choose a reason for hiding this comment

ArekBalysNordic Feb 5, 2025

Choose a reason for hiding this comment

kkasperczyk-no Feb 5, 2025

Choose a reason for hiding this comment

ArekBalysNordic Feb 5, 2025

Choose a reason for hiding this comment

ArekBalysNordic commented Feb 6, 2025

NordicBuilder commented Feb 3, 2025 •

edited

Loading

NordicBuilder commented Feb 3, 2025 •

edited

Loading