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 <[email protected]> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <[email protected]> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <[email protected]> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <[email protected]> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <[email protected]> * Update examples/chef/NEW_CHEF_DEVICES.md Co-authored-by: Erwin Pan <[email protected]> * 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 <[email protected]> Co-authored-by: Erwin Pan <[email protected]>
project-chip · Sep 28, 2023 · dd4b607 · dd4b607
1 parent f9a8660
commit dd4b607
Show file tree

Hide file tree

Showing 9 changed files with 10,215 additions and 15 deletions.
diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -47,6 +47,8 @@ esp32/README
 -   [Python Matter-Repl](./matter-repl.md)
 -   [python-chip-controller - Advanced](./python_chip_controller_advanced_usage.md)
 -   [python-chip-controller - Building](./python_chip_controller_building.md)
+-   [CHEF test devices](../../examples/chef/README.md)
+    -   [New device type adding](../../examples/chef/NEW_CHEF_DEVICES.md)
 
 ## Development Guides
 

diff --git a/examples/chef/NEW_CHEF_DEVICES.md b/examples/chef/NEW_CHEF_DEVICES.md
@@ -0,0 +1,117 @@
+---
+orphan: true
+---
+
+# CHEF devices
+
+Device definitions reside in `examples/chef/devices` as .zap and .matter files.
+
+Generally you need to follow these steps to use a new device:
+
+-   Create a zap/matter configuration (forking an existing one is the easiest)
+-   Rename to a final/stable name
+-   Test
+
+## Creating a new zap configuration
+
+The easiest way to get started is using an existing configuration. A template is
+provided in `./examples/chef/devices/template.zap`.
+
+To open the zap GUI for this device, run:
+
+```
+./examples/chef/chef.py -g -d template
+```
+
+### Editing the zap configuration:
+
+Using the ZAP UI, make the following changes:
+
+-   Leave Endpoint 0 unchanged
+-   Click the Edit/Pencil icon to change Endpoint 1
+    (![Edit device type](img/endpoint1_edit_pencil.png))
+    -   Update the device type to the new device and click "save"
+        (![edit device type](img/endpoint_edit_type.png))
+    -   In the "Filter" section select "Enabled Clusters" and validate what
+        clusters are set
+        (![filter enabled clusters](img/select_enabled_clusters.png))
+        -   Ensure clusters for the device type are enabled (this is generally
+            automatically the case)
+        -   Click the gear icon on the cluster to further edit enabled
+            attributes and commands
+        -   You can add additional optional clusters if needed (disable
+            filtering and use the search option)
+
+Once all edits are done, click "File" => "Save as..." to save it under a **NEW**
+name inside `examples/chef/devices/`.
+
+NOTE: make sure you save under `examples/chef/devices` since internal paths
+inside the saved file will be relative to the save location (it cannot simply be
+moved later without manual editing).
+
+It is suggested to name this `rootnode_<device_type_name>.zap` (e.g.,
+`rootnode_smokecoalarm.zap` for Matter Smoke CO Alarm device type)
+
+## Establishing a "final name"
+
+General naming convention for chef is `<ep0>_<ep1>_<hash>` where `<epN>` is the
+type of endpoint (and `<ep0>` is almost always `rootnode`).
+
+The hash is a one-time uniquely generated identifier to allow separate
+configurations for the same devices (e.g different features enabled).
+
+You can read more in `examples/chef/sample_app_util/README.md`, however the
+short version is that you can determine a recommended name using:
+
+```
+./examples/chef/sample_app_util/sample_app_util.py zap --generate-name <saved_zap_file_name>
+```
+
+and generally you want to just rename it via:
+
+```
+./examples/chef/sample_app_util/sample_app_util.py zap --rename-file <saved_zap_file_name>
+```
+
+## Running code generation (to generate .matter file)
+
+To generate the matter file for your target, run
+
+```
+./scripts/tools/zap/generate.py <new_device_zap_name>
+```
+
+This should generate the corresponding `.matter` file for the zap file you
+created.
+
+## Testing
+
+Basic device availability should show when running:
+
+```
+./examples/chef/chef.py -h | less
+```
+
+### Compilation
+
+This example uses `rootnode_contactsensor_lFAGG1bfRO` for commands. Substitute
+your own device for testing newly created devices.
+
+```
+./examples/chef/chef.py                 \
+   -t linux                             \
+   -d rootnode_contactsensor_lFAGG1bfRO \
+   -b
+```
+
+Where options used are:
+
+-   `-t` specifies the target platform
+-   `-d` specifies the device to build
+-   `-b` asks for build to be run
+
+### Execution
+
+Build will be available in
+`examples/chef/linux/out/rootnode_contactsensor_lFAGG1bfRO` (path will vary
+based on platform and device being built)
diff --git a/examples/chef/README.md b/examples/chef/README.md
@@ -51,12 +51,7 @@ All device types available (.zap files) are found inside the `devices` folder.
 
 ## Creating a new device type in your device library
 
-1. Run `$ chef.py -g -d <device>` to open in the ZAP GUI a device to be used as
-   a starting point.
-2. Edit your cluster configurations
-3. Click on `Save As` and save the file with the name of your new device type
-   into the `devices` folder. This device is now available for the script. See
-   `chef.py -h` for a list of devices available.
+Follow guide in [NEW_CHEF_DEVICES.md](NEW_CHEF_DEVICES.md).
 
 ## Folder Structure and Guidelines
 

diff --git a/examples/chef/chef.py b/examples/chef/chef.py
@@ -264,7 +264,7 @@ def main() -> int:
     # Arguments parser
     #
 
-    deviceTypes = "\n  ".join(_DEVICE_LIST)
+    deviceTypes = "\n            ".join(_DEVICE_LIST)
 
     usage = textwrap.dedent(f"""\
         usage: chef.py [options]
@@ -310,11 +310,11 @@ def main() -> int:
     parser.add_option("-t", "--target", type='choice',
                       action='store',
                       dest="build_target",
-                      help="specifies target platform. Default is esp32. See info below for currently supported target platforms",
+                      help="specifies target platform. See info below for currently supported target platforms",
                       choices=['nrfconnect', 'esp32',
                                'linux', 'silabs-thread', 'ameba'],
                       metavar="TARGET",
-                      default="esp32")
+                      default="linux")
     parser.add_option("-r", "--rpc",
                       help=("enables Pigweed RPC interface. Enabling RPC disables the shell interface. "
                             "Your sdkconfig configurations will be reverted to default. Default is PW RPC off. "
@@ -475,8 +475,10 @@ def main() -> int:
         zephyr_sdk_dir = config['nrfconnect']['ZEPHYR_SDK_INSTALL_DIR']
         shell.run_cmd("export ZEPHYR_TOOLCHAIN_VARIANT=zephyr")
         shell.run_cmd(f"export ZEPHYR_SDK_INSTALL_DIR={zephyr_sdk_dir}")
-        shell.run_cmd(f"export ZEPHYR_BASE={config['nrfconnect']['ZEPHYR_BASE']}")
-        shell.run_cmd(f'source {config["nrfconnect"]["ZEPHYR_BASE"]}/zephyr-env.sh')
+        shell.run_cmd(
+            f"export ZEPHYR_BASE={config['nrfconnect']['ZEPHYR_BASE']}")
+        shell.run_cmd(
+            f'source {config["nrfconnect"]["ZEPHYR_BASE"]}/zephyr-env.sh')
         # QUIRK:
         # When the Zephyr SDK is installed as a part of the NCS toolchain, the build system will use
         # build tools from the NCS toolchain, but it will not update the PATH and LD_LIBRARY_PATH
@@ -485,8 +487,10 @@ def main() -> int:
         ncs_toolchain_dir = os.path.abspath(f"{zephyr_sdk_dir}/../..")
         if os.path.exists(os.path.join(ncs_toolchain_dir, 'manifest.json')):
             shell.run_cmd(f"export PATH=$PATH:{ncs_toolchain_dir}/usr/bin")
-            shell.run_cmd(f"export PATH=$PATH:{ncs_toolchain_dir}/usr/local/bin")
-            shell.run_cmd(f"export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:{ncs_toolchain_dir}/usr/lib")
+            shell.run_cmd(
+                f"export PATH=$PATH:{ncs_toolchain_dir}/usr/local/bin")
+            shell.run_cmd(
+                f"export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:{ncs_toolchain_dir}/usr/lib")
             shell.run_cmd(
                 f"export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:{ncs_toolchain_dir}/usr/local/lib")
     elif options.build_target == "linux":
@@ -560,8 +564,6 @@ def main() -> int:
         shell.run_cmd(
             f"{_REPO_BASE_PATH}/scripts/tools/zap/generate.py "
             f"{_CHEF_SCRIPT_PATH}/devices/{options.sample_device_type_name}.zap -o {gen_dir}")
-        # af-gen-event.h is not generated
-        shell.run_cmd(f"touch {gen_dir}/af-gen-event.h")
 
     #
     # Setup environment