Skip to content

Commit 0a87dca

Browse files
rbultmanandy31415
rbultman
and
andy31415
authored
Move add new device howto to docs (#32950)
* Move add new device howto * Add words * Update docs/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md Co-authored-by: Andrei Litvin <andy314@gmail.com> * Remove word * Update docs/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md Co-authored-by: Andrei Litvin <andy314@gmail.com> * Update docs/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md * Update docs/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md * Remove word from wordlist --------- Co-authored-by: Andrei Litvin <andy314@gmail.com>
1 parent 2002c0c commit 0a87dca

File tree

4 files changed

+254
-5
lines changed

4 files changed

+254
-5
lines changed

‎.github/.wordlist.txt

+2
Original file line numberDiff line numberDiff line change
@@ -369,6 +369,7 @@ DelayedActionTime
369369
delayedApplyActionTimeSec
370370
delayedQueryActionTimeSec
371371
delayQuery
372+
deliverables
372373
demangle
373374
deployable
374375
depottools
@@ -729,6 +730,7 @@ JLink
729730
JLinkExe
730731
JLinkRTTClient
731732
JN
733+
jni
732734
jpg
733735
jre
734736
js

‎docs/cluster_and_device_type_dev/cluster_and_device_type_dev.md

+3-5
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,9 @@ types in the SDK.
3636
- XML defines conformance
3737
- [src/app/zap-templates/zcl/data-model/chip/matter-devices.xml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/matter-devices.xml)
3838

39-
The following wiki page has a detailed description of how and where to add
40-
cluster and device type definitions so they are picked up properly by ZAP/ember
41-
and the SDK.
42-
43-
[https://groups.csa-iot.org/wg/matter-tsg/wiki/howto-add-a-new-device-type](https://groups.csa-iot.org/wg/matter-tsg/wiki/howto-add-a-new-device-type)
39+
See [How To Add New Device Types & Clusters](how_to_add_new_dts_and_clusters.md)
40+
for a detailed description of how and where to add cluster and device type
41+
definitions so they are picked up properly by ZAP/ember and the SDK.
4442

4543
Note that the output should also be verified against the spec using the
4644
[.matter parser tools](https://project-chip.github.io/connectedhomeip-doc/guides/matter_idl_tooling.html).

‎docs/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md

+248
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# How to Add New Device Types & Clusters
2+
3+
This document outlines the process needed to add a new Matter device type and
4+
related clusters. Obviously, the steps below assume that the related Matter
5+
specifications were properly reviewed and approved.
6+
7+
## Add the cluster definitions to the SDK
8+
9+
The following steps should be followed to add new cluster definitions to the
10+
SDK.
11+
12+
**Add your new cluster definition to an appropriately-name file in this
13+
directory:**
14+
[src/app/zap-templates/zcl/data-model/chip](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip)
15+
16+
**Add references to each new cluster definition to these files:**
17+
18+
1. [.github/workflows/tests.yaml](https://github.com/project-chip/connectedhomeip/tree/master/.github/workflows/tests.yaml)
19+
2. [scripts/rules.matterlint](https://github.com/project-chip/connectedhomeip/tree/master/scripts/rules.matterlint)
20+
3. [src/app/zap-templates/zcl/data-model/all.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/all.xml)
21+
4. [src/app/zap-templates/zcl/zcl-with-test-extensions.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/zcl-with-test-extensions.json)
22+
5. [src/app/zap-templates/zcl/zcl.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/zcl.json)
23+
6. If it is a derived cluster, add a reference to the base cluster definition.
24+
(e.g. in mode-base-cluster.xml you may need to add cluster codes - otherwise
25+
you may get strange exceptions which aren't clear when running regen_all.py)
26+
27+
> ```
28+
> <struct name="ModeOptionStruct">
29+
> <cluster code="0x0051"/> <!-- Laundry Washer Mode -->
30+
> <cluster code="YOUR NEW CLUSTER ID"/>
31+
> </struct>
32+
> ```
33+
34+
7. [src/controller/python/chip/clusters/\_\_init\_\_.py](https://github.com/project-chip/connectedhomeip/tree/master/src/controller/python/chip/clusters/__init__.py)
35+
36+
**Enable your new cluster in the Python and Android clients** in
37+
[src/controller/data_model/controller-clusters.zap](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/data_model/controller-clusters.zap)
38+
39+
You will need the ZAP tool to edit the ZAP file.
40+
41+
- Unless you already have the tool installed, you can use one of the
42+
[nightly builds](https://github.com/project-chip/zap/releases)
43+
- [ZAP tool info](https://developers.home.google.com/matter/tools/zap)
44+
- [ZAP tool repo](https://github.com/project-chip/zap)
45+
46+
Use the ZAP GUI tool to edit the file above:
47+
48+
1. From the command line, navigate to the directory containing
49+
[controller-clusters.zap](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/data_model)
50+
2. Run zap: `../../../scripts/tools/zap/run_zaptool.sh controller-clusters.zap`.
51+
Alternatively, run the zap tool and navigate to the zap file that you wish to
52+
open, or run as
53+
`./scripts/tools/zap/run_zaptool.sh src/controller/data_model/controller-clusters.zap`.
54+
3. In the gui, select `Endpoint-1` from the left pane.
55+
4. Open the cluster group, for example, `Appliances`.
56+
5. Find the cluster to be enabled, e.g. `Dishwasher Control`.
57+
6. In the Enable column, select "Client" from the drop-down box.
58+
7. Click `File->Save` to save the configuration.
59+
8. Close the GUI.
60+
61+
**Add entries for your new cluster to
62+
[BUILD.gn](c/src/controller/data_model/BUILD.gn)** in the outputs section of the
63+
java-jni-generate bits. The entries should look like
64+
"jni/YourClusterNameClient-InvokeSubscribeImpl.cpp" and
65+
"jni/YourClusterNameClient-ReadImpl.cpp".
66+
67+
**Add an entry to the ClientDirectories** section of
68+
[src/app/zap_cluster_list.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap_cluster_list.json).
69+
70+
**Update `chip-tool`**
71+
72+
1. Regenerate all zap generated code using `./scripts/tools/zap_regen_all.py`
73+
2. Rebuild chip-tool and it will have new cluster support:
74+
`./scripts/examples/gn_build_example.sh examples/chip-tool SOME-PATH/`
75+
76+
## Add the device type definition to the SDK
77+
78+
1. Add the XML definition of the device to
79+
[matter-devices.xml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/matter-devices.xml)
80+
2. Implement the incoming command behaviors common to all applications. The
81+
parsing of the payload from TLV to a C++ struct is done by code
82+
auto-generated from the XML (see
83+
[zap-generated](https://github.com/project-chip/connectedhomeip/blob/master/zzz_generated/app-common/app-common/zap-generated))
84+
The rest of the functionality must be manually implemented. Note: for the
85+
auto-generated code run one of the following:
86+
1. for everything: `./scripts/tools/zap_regen_all.py`
87+
2. just for the app-common part:
88+
`./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`
89+
3. Implement the read/write/storage operations for the attributes of any type,
90+
list, or struct which are not the global attributes present in all clusters.
91+
For example, there's no need to implement CommandList, AttributeList etc. For
92+
the attributes which are not list of struct type, the handling code is
93+
implemented generically so most likely no work is needed for them.
94+
4. Implement any attribute spec requirements that are common to all
95+
applications. For example: code to enforce specific ranges, code for handling
96+
the interactions between attributes etc.
97+
98+
## Implement Code and Tests
99+
100+
Implement the clusters, the example cluster server application and add the
101+
related SDK tests.
102+
103+
1. Implement new clusters here:
104+
[src/app/clusters](https://github.com/project-chip/connectedhomeip/tree/master/src/app/clusters)
105+
2. Implement tests here:
106+
[src/app/tests/suites](https://github.com/project-chip/connectedhomeip/tree/master/src/app/tests/suites)
107+
3. Implement the example cluster server application:
108+
1. The YAML tests will run against this server
109+
2. Depending on the clusters, there are two options:
110+
1. Enable them in the all-clusters-app and use that as the example
111+
cluster server app. If choosing this option, consider adding an
112+
example application that has just the relevant clusters enabled; this
113+
part is a nice to have.
114+
2. If the clusters have complicated global application requirements
115+
consider using a separate example app. see the door lock, bridge, TV,
116+
OTA clusters.
117+
3. NOTES: If adding a new cluster derived from `mode-base` into
118+
[examples/all-clusters-app/](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/)
119+
(Assume your new cluster is called `XZYMode`):
120+
1. Create your new `xyz-mode-cluster.xml` in
121+
[src/app/zap-templates/zcl/data-model/chip](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip)
122+
(as above). Note that this is a much cut down cluster definition
123+
compared to normal clusters, since it derives from
124+
[mode-base-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/mode-base-cluster.xml).
125+
See
126+
[dishwasher-mode-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/dishwasher-mode-cluster.xml)
127+
as an example. Note you should review if you need the `StartUpMode`
128+
and `OnMode` attributes based on the spec.
129+
2. Check that you have added your cluster code into
130+
[mode-base-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/mode-base-cluster.xml)
131+
1. `<struct name="ModeTagStruct"> <cluster code="0xXXXX">` - replace
132+
`XXXX` with your cluster ID
133+
2. `<struct name="ModeOptionStruct"> <cluster code="0xXXXX">` -
134+
replace `XXXX` with your cluster ID
135+
3. `<bitmap name="Feature" type="bitmap32"> <cluster code="0xXXXX">` -
136+
replace `XXXX` with your cluster ID
137+
3. Add your new Mode definitions in `xyz-mode.h`. In this header you
138+
define the modes / labels and tags. See
139+
[dishwasher-mode.h](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/all-clusters-common/include/dishwasher-mode.h)
140+
as an example.
141+
4. Add your new stub to instantiate the mode. See
142+
[dishwasher-mode.cpp](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/all-clusters-common/src/dishwasher-mode.cpp)
143+
as an example.
144+
5. In
145+
[examples/all-clusters-app/linux/main-common.cpp](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux/main-common.cpp):
146+
1. Add `#include "xyz-mode.h"`
147+
2. In `ApplicationShutdown()`, add a call to your
148+
`Clusters::XYZMode::Shutdown();`.
149+
6. In
150+
[examples/all-clusters-app/linux/BUILD.gn](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux/BUILD.gn),
151+
add the `xyz-mode.cpp` file to the `sources` section.
152+
7. In
153+
[src/app/common/templates/config-data.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/common/templates/config-data.yaml):
154+
1. Add a `<XYZMode>::ModeTag` to the `EnumsNotUsedAsTypeInXML`
155+
section.
156+
2. Add an `XYZ Mode` entry to the
157+
`CommandHandlerInterfaceOnlyClusters` section.
158+
8. In
159+
[src/app/util/util.cpp](https://github.com/project-chip/connectedhomeip/blob/master/src/app/util/util.cpp),
160+
in the `// Cluster Init Functions...` section, add a void
161+
`MatterXYZModePluginServerInitCallback() {}` definition.
162+
9. In
163+
[src/app/zap-templates/zcl/zcl-with-test-extensions.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/zcl-with-test-extensions.json):
164+
1. Add the `xyz-mode-cluster.xml` to the `xmlFile` list
165+
2. In the `attributeAccessInterfaceAttributes` entry, add your new
166+
entry
167+
`"XYZ Mode": [ "SupportedModes", "CurrentMode", "FeatureMap" ]` -
168+
this will mean ZAP won't generate code to handle these attributes
169+
10. In
170+
[src/app/zap_cluster_list.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap_cluster_list.json):
171+
1. Add your `XYZ_MODE_CLUSTER: []` to `ClientDirectories: { }`
172+
object
173+
2. Add your `"XYZ_MODE_CLUSTER": ["mode-base-server"]` to
174+
`"ServerDirectories": { }`
175+
4. The code under
176+
[src/app/tests/suites/certification](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification)
177+
for YAML or
178+
[src/python_testing](https://github.com/project-chip/connectedhomeip/tree/master/src/python_testing)
179+
for Python should ideally implement the test plan (section 4 below).
180+
5. A test under
181+
[src/app/tests/suites](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites)
182+
(not certification) can test anything, in addition to, or preceding the
183+
official YAML representing the official test plan.
184+
4. Add the test plan, using the templates below:
185+
186+
1. [cluster_test_plan_template.adoc](https://github.com/CHIP-Specifications/chip-test-plans/blob/master/src/template/cluster_test_plan_template.adoc)
187+
2. [test_plan_template.adoc](https://github.com/CHIP-Specifications/chip-test-plans/blob/master/src/template/test_plan_template.adoc)
188+
189+
Also, ask to be added to the private `csg-tt-test-plans` Slack channel.
190+
191+
5. Note: the CHIP-Tool reference client is generated from XML
192+
6. If applicable, add tests:
193+
1. For relatively simple tests, add YAML tests here:
194+
[src/app/tests/suites/certification](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification).
195+
Remember to update this file:
196+
[src/app/tests/suites/certification/PICS.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification/PICS.yaml)
197+
2. For more complex tests, add Python tests here:
198+
[src/python_testing](https://github.com/project-chip/connectedhomeip/tree/master/src/python_testing)
199+
3. To add tests to CI, if applicable:
200+
1. Add the Python tests here:
201+
[.github/workflows/tests.yaml](https://github.com/project-chip/connectedhomeip/tree/master/.github/workflows/tests.yaml).
202+
Remember to provide all arguments required for each Python script,
203+
such as the endpoint PIXIT.
204+
2. Add the YAML tests by editing this file:
205+
[src/app/tests/suites/ciTests.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/tests/suites/ciTests.json)
206+
1. Create a section ("MyDevice") which lists all YAML tests for your
207+
device
208+
2. Add the section's name to the list of items named "collection"
209+
3. Do a ZAP code regen: `./scripts/tools/zap_regen_all.py`.
210+
7. Add the device type spec to the test plan tools:
211+
212+
1. [tools/device_type_requirements](https://github.com/CHIP-Specifications/chip-test-plans/tree/master/tools/device_type_requirements)
213+
2. The file above is used by
214+
[src/app/tests/suites/certification/Test_TC_DESC_2_1.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification/Test_TC_DESC_2_1.yaml)
215+
216+
Note: the plan is to make the DM tools generate the device type requirements
217+
data based on the spec, so the above will become obsolete.
218+
219+
8. Add the device type to Chef:
220+
[examples/chef/devices](https://github.com/project-chip/connectedhomeip/tree/master/examples/chef/devices)
221+
222+
## Q & A
223+
224+
**Q1**: What kind of devices can be used for the test events? Can one of them be
225+
the example cluster server app running on a RasPI? Do the independent
226+
realizations need to run on vendor hardware or can they also run on generic
227+
hardware, such as ESP32 or RasPI?
228+
229+
**A1**: one realization can be the test harness + the all clusters example app +
230+
RasPI. the two independent realizations need to run on target hardware, which
231+
may be mock-ups, prototypes etc
232+
233+
**Q2**: How can the Chef tool be used for any of the deliverables above?
234+
235+
**A2**: TBD
236+
237+
**Q3**: What is the process for using the Zap tool in order to auto-generate
238+
code and to commit the results to the git repo?
239+
240+
**A3**: Search for zap_regen above. Add all the changed files to the repo after.
241+
242+
**Q4**: Where can the older cluster definitions be found?
243+
244+
**A4**: src/app/zap-templates/zcl/data-model/silabs/general.xml
245+
246+
**Q5**: Where can I find ZAP documentation?
247+
248+
**A5**: https://github.com/project-chip/zap/blob/master/README.md

‎docs/cluster_and_device_type_dev/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ types in the SDK.
1313
```
1414

1515
- [Cluster and device type development](./cluster_and_device_type_dev.md)
16+
- [How To Add New Device Types & Clusters](how_to_add_new_dts_and_clusters.md)

0 commit comments

Comments
 (0)