This document outlines the process needed to add a new Matter device type and related clusters. Obviously, the steps below assume that the related Matter specifications were properly reviewed and approved.
The following steps should be followed to add new cluster definitions to the SDK.
Add your new cluster definition to an appropriately-name file in this directory: src/app/zap-templates/zcl/data-model/chip
Add references to each new cluster definition to these files:
If it is a derived cluster, add a reference to the base cluster definition. (e.g. in mode-base-cluster.xml you may need to add cluster codes - otherwise you may get strange exceptions which aren't clear when running regen_all.py)
<struct name="ModeOptionStruct"> <cluster code="0x0051"/> <!-- Laundry Washer Mode --> <cluster code="YOUR NEW CLUSTER ID"/> </struct>
Enable your new cluster in the Python and Android clients in src/controller/data_model/controller-clusters.zap
You will need the ZAP tool to edit the ZAP file.
Use the ZAP GUI tool to edit the file above:
../../../scripts/tools/zap/run_zaptool.sh controller-clusters.zap
. Alternatively, run the zap tool and navigate to the zap file that you wish to open, or run as ./scripts/tools/zap/run_zaptool.sh src/controller/data_model/controller-clusters.zap
.Endpoint-1
from the left pane.Appliances
.Dishwasher Control
.File->Save
to save the configuration.Add entries for your new cluster to BUILD.gn in the outputs section of the java-jni-generate bits. The entries should look like “jni/YourClusterNameClient-InvokeSubscribeImpl.cpp” and “jni/YourClusterNameClient-ReadImpl.cpp”.
Add an entry to the ClientDirectories section of src/app/zap_cluster_list.json.
Update chip-tool
./scripts/tools/zap_regen_all.py
./scripts/examples/gn_build_example.sh examples/chip-tool SOME-PATH/
./scripts/tools/zap_regen_all.py
./scripts/tools/zap/generate.py -t src/app/common/templates/templates.json -o zzz_generated/app-common/app-common/zap-generated src/controller/data_model/controller-clusters.zap
Implement the clusters, the example cluster server application and add the related SDK tests.
Implement new clusters here: src/app/clusters
Implement tests here: src/app/tests/suites
Implement the example cluster server application:
mode-base
into examples/all-clusters-app/ (Assume your new cluster is called XZYMode
):xyz-mode-cluster.xml
in src/app/zap-templates/zcl/data-model/chip (as above). Note that this is a much cut down cluster definition compared to normal clusters, since it derives from mode-base-cluster.xml. See dishwasher-mode-cluster.xml as an example. Note you should review if you need the StartUpMode
and OnMode
attributes based on the spec.<struct name="ModeTagStruct"> <cluster code="0xXXXX">
- replace XXXX
with your cluster ID<struct name="ModeOptionStruct"> <cluster code="0xXXXX">
- replace XXXX
with your cluster ID<bitmap name="Feature" type="bitmap32"> <cluster code="0xXXXX">
- replace XXXX
with your cluster IDxyz-mode.h
. In this header you define the modes / labels and tags. See dishwasher-mode.h as an example.#include "xyz-mode.h"
ApplicationShutdown()
, add a call to your Clusters::XYZMode::Shutdown();
.xyz-mode.cpp
file to the sources
section.<XYZMode>::ModeTag
to the EnumsNotUsedAsTypeInXML
section.XYZ Mode
entry to the CommandHandlerInterfaceOnlyClusters
section.// Cluster Init Functions...
section, add a void MatterXYZModePluginServerInitCallback() {}
definition.xyz-mode-cluster.xml
to the xmlFile
listattributeAccessInterfaceAttributes
entry, add your new entry "XYZ Mode": [ "SupportedModes", "CurrentMode", "FeatureMap" ]
- this will mean ZAP won't generate code to handle these attributesXYZ_MODE_CLUSTER: []
to ClientDirectories: { }
object"XYZ_MODE_CLUSTER": ["mode-base-server"]
to "ServerDirectories": { }
Add the test plan, using the templates below:
Also, ask to be added to the private csg-tt-test-plans
Slack channel.
Note: the CHIP-Tool reference client is generated from XML
If applicable, add tests:
./scripts/tools/zap_regen_all.py
.Add the device type spec to the test plan tools:
Note: the plan is to make the DM tools generate the device type requirements data based on the spec, so the above will become obsolete.
Add the device type to Chef: examples/chef/devices
Q1: What kind of devices can be used for the test events? Can one of them be the example cluster server app running on a RasPI? Do the independent realizations need to run on vendor hardware or can they also run on generic hardware, such as ESP32 or RasPI?
A1: one realization can be the test harness + the all clusters example app + RasPI. the two independent realizations need to run on target hardware, which may be mock-ups, prototypes etc
Q2: How can the Chef tool be used for any of the deliverables above?
A2: TBD
Q3: What is the process for using the Zap tool in order to auto-generate code and to commit the results to the git repo?
A3: Search for zap_regen above. Add all the changed files to the repo after.
Q4: Where can the older cluster definitions be found?
A4: src/app/zap-templates/zcl/data-model/silabs/general.xml
Q5: Where can I find ZAP documentation?
A5: https://github.com/project-chip/zap/blob/master/README.md