Skip to content

Commit e5df2c9

Browse files
andy31415restyled-commitserwinpan1
authored
Document how to add new devices via CHEF (#27900)
* Fix help output * Write docs * Add missing file * Restyled by prettier-markdown * Restyled by autopep8 * Fix link * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <erwinpan1@gmail.com> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <erwinpan1@gmail.com> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <erwinpan1@gmail.com> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <erwinpan1@gmail.com> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <erwinpan1@gmail.com> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <erwinpan1@gmail.com> * af-gen-event.h should not be needed anymore * Make doc builder happy ... at some point we may want to place this in a tree though * Add some more links * Fix link * Restyled by prettier-markdown * Add a template zap file and add image examples * Ignore tempalte from zap-regen-all * Restyled by prettier-markdown * Quoting add to make spell checker happy --------- Co-authored-by: Restyled.io <commits@restyled.io> Co-authored-by: Erwin Pan <erwinpan1@gmail.com>
1 parent c1d82c5 commit e5df2c9

9 files changed

+10215
-15
lines changed

‎docs/guides/index.md

+2
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ esp32/README
4747
- [Python Matter-Repl](./matter-repl.md)
4848
- [python-chip-controller - Advanced](./python_chip_controller_advanced_usage.md)
4949
- [python-chip-controller - Building](./python_chip_controller_building.md)
50+
- [CHEF test devices](../../examples/chef/README.md)
51+
- [New device type adding](../../examples/chef/NEW_CHEF_DEVICES.md)
5052

5153
## Development Guides
5254

‎examples/chef/NEW_CHEF_DEVICES.md

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
orphan: true
3+
---
4+
5+
# CHEF devices
6+
7+
Device definitions reside in `examples/chef/devices` as .zap and .matter files.
8+
9+
Generally you need to follow these steps to use a new device:
10+
11+
- Create a zap/matter configuration (forking an existing one is the easiest)
12+
- Rename to a final/stable name
13+
- Test
14+
15+
## Creating a new zap configuration
16+
17+
The easiest way to get started is using an existing configuration. A template is
18+
provided in `./examples/chef/devices/template.zap`.
19+
20+
To open the zap GUI for this device, run:
21+
22+
```
23+
./examples/chef/chef.py -g -d template
24+
```
25+
26+
### Editing the zap configuration:
27+
28+
Using the ZAP UI, make the following changes:
29+
30+
- Leave Endpoint 0 unchanged
31+
- Click the Edit/Pencil icon to change Endpoint 1
32+
(![Edit device type](img/endpoint1_edit_pencil.png))
33+
- Update the device type to the new device and click "save"
34+
(![edit device type](img/endpoint_edit_type.png))
35+
- In the "Filter" section select "Enabled Clusters" and validate what
36+
clusters are set
37+
(![filter enabled clusters](img/select_enabled_clusters.png))
38+
- Ensure clusters for the device type are enabled (this is generally
39+
automatically the case)
40+
- Click the gear icon on the cluster to further edit enabled
41+
attributes and commands
42+
- You can add additional optional clusters if needed (disable
43+
filtering and use the search option)
44+
45+
Once all edits are done, click "File" => "Save as..." to save it under a **NEW**
46+
name inside `examples/chef/devices/`.
47+
48+
NOTE: make sure you save under `examples/chef/devices` since internal paths
49+
inside the saved file will be relative to the save location (it cannot simply be
50+
moved later without manual editing).
51+
52+
It is suggested to name this `rootnode_<device_type_name>.zap` (e.g.,
53+
`rootnode_smokecoalarm.zap` for Matter Smoke CO Alarm device type)
54+
55+
## Establishing a "final name"
56+
57+
General naming convention for chef is `<ep0>_<ep1>_<hash>` where `<epN>` is the
58+
type of endpoint (and `<ep0>` is almost always `rootnode`).
59+
60+
The hash is a one-time uniquely generated identifier to allow separate
61+
configurations for the same devices (e.g different features enabled).
62+
63+
You can read more in `examples/chef/sample_app_util/README.md`, however the
64+
short version is that you can determine a recommended name using:
65+
66+
```
67+
./examples/chef/sample_app_util/sample_app_util.py zap --generate-name <saved_zap_file_name>
68+
```
69+
70+
and generally you want to just rename it via:
71+
72+
```
73+
./examples/chef/sample_app_util/sample_app_util.py zap --rename-file <saved_zap_file_name>
74+
```
75+
76+
## Running code generation (to generate .matter file)
77+
78+
To generate the matter file for your target, run
79+
80+
```
81+
./scripts/tools/zap/generate.py <new_device_zap_name>
82+
```
83+
84+
This should generate the corresponding `.matter` file for the zap file you
85+
created.
86+
87+
## Testing
88+
89+
Basic device availability should show when running:
90+
91+
```
92+
./examples/chef/chef.py -h | less
93+
```
94+
95+
### Compilation
96+
97+
This example uses `rootnode_contactsensor_lFAGG1bfRO` for commands. Substitute
98+
your own device for testing newly created devices.
99+
100+
```
101+
./examples/chef/chef.py \
102+
-t linux \
103+
-d rootnode_contactsensor_lFAGG1bfRO \
104+
-b
105+
```
106+
107+
Where options used are:
108+
109+
- `-t` specifies the target platform
110+
- `-d` specifies the device to build
111+
- `-b` asks for build to be run
112+
113+
### Execution
114+
115+
Build will be available in
116+
`examples/chef/linux/out/rootnode_contactsensor_lFAGG1bfRO` (path will vary
117+
based on platform and device being built)

‎examples/chef/README.md

+1-6
Original file line numberDiff line numberDiff line change
@@ -51,12 +51,7 @@ All device types available (.zap files) are found inside the `devices` folder.
5151

5252
## Creating a new device type in your device library
5353

54-
1. Run `$ chef.py -g -d <device>` to open in the ZAP GUI a device to be used as
55-
a starting point.
56-
2. Edit your cluster configurations
57-
3. Click on `Save As` and save the file with the name of your new device type
58-
into the `devices` folder. This device is now available for the script. See
59-
`chef.py -h` for a list of devices available.
54+
Follow guide in [NEW_CHEF_DEVICES.md](NEW_CHEF_DEVICES.md).
6055

6156
## Folder Structure and Guidelines
6257

‎examples/chef/chef.py

+11-9
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,7 @@ def main() -> int:
264264
# Arguments parser
265265
#
266266

267-
deviceTypes = "\n ".join(_DEVICE_LIST)
267+
deviceTypes = "\n ".join(_DEVICE_LIST)
268268

269269
usage = textwrap.dedent(f"""\
270270
usage: chef.py [options]
@@ -310,11 +310,11 @@ def main() -> int:
310310
parser.add_option("-t", "--target", type='choice',
311311
action='store',
312312
dest="build_target",
313-
help="specifies target platform. Default is esp32. See info below for currently supported target platforms",
313+
help="specifies target platform. See info below for currently supported target platforms",
314314
choices=['nrfconnect', 'esp32',
315315
'linux', 'silabs-thread', 'ameba'],
316316
metavar="TARGET",
317-
default="esp32")
317+
default="linux")
318318
parser.add_option("-r", "--rpc",
319319
help=("enables Pigweed RPC interface. Enabling RPC disables the shell interface. "
320320
"Your sdkconfig configurations will be reverted to default. Default is PW RPC off. "
@@ -475,8 +475,10 @@ def main() -> int:
475475
zephyr_sdk_dir = config['nrfconnect']['ZEPHYR_SDK_INSTALL_DIR']
476476
shell.run_cmd("export ZEPHYR_TOOLCHAIN_VARIANT=zephyr")
477477
shell.run_cmd(f"export ZEPHYR_SDK_INSTALL_DIR={zephyr_sdk_dir}")
478-
shell.run_cmd(f"export ZEPHYR_BASE={config['nrfconnect']['ZEPHYR_BASE']}")
479-
shell.run_cmd(f'source {config["nrfconnect"]["ZEPHYR_BASE"]}/zephyr-env.sh')
478+
shell.run_cmd(
479+
f"export ZEPHYR_BASE={config['nrfconnect']['ZEPHYR_BASE']}")
480+
shell.run_cmd(
481+
f'source {config["nrfconnect"]["ZEPHYR_BASE"]}/zephyr-env.sh')
480482
# QUIRK:
481483
# When the Zephyr SDK is installed as a part of the NCS toolchain, the build system will use
482484
# build tools from the NCS toolchain, but it will not update the PATH and LD_LIBRARY_PATH
@@ -485,8 +487,10 @@ def main() -> int:
485487
ncs_toolchain_dir = os.path.abspath(f"{zephyr_sdk_dir}/../..")
486488
if os.path.exists(os.path.join(ncs_toolchain_dir, 'manifest.json')):
487489
shell.run_cmd(f"export PATH=$PATH:{ncs_toolchain_dir}/usr/bin")
488-
shell.run_cmd(f"export PATH=$PATH:{ncs_toolchain_dir}/usr/local/bin")
489-
shell.run_cmd(f"export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:{ncs_toolchain_dir}/usr/lib")
490+
shell.run_cmd(
491+
f"export PATH=$PATH:{ncs_toolchain_dir}/usr/local/bin")
492+
shell.run_cmd(
493+
f"export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:{ncs_toolchain_dir}/usr/lib")
490494
shell.run_cmd(
491495
f"export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:{ncs_toolchain_dir}/usr/local/lib")
492496
elif options.build_target == "linux":
@@ -560,8 +564,6 @@ def main() -> int:
560564
shell.run_cmd(
561565
f"{_REPO_BASE_PATH}/scripts/tools/zap/generate.py "
562566
f"{_CHEF_SCRIPT_PATH}/devices/{options.sample_device_type_name}.zap -o {gen_dir}")
563-
# af-gen-event.h is not generated
564-
shell.run_cmd(f"touch {gen_dir}/af-gen-event.h")
565567

566568
#
567569
# Setup environment

0 commit comments

Comments
 (0)