From 54aff51eb773afa76ab64faf2adb88d8156c05b9 Mon Sep 17 00:00:00 2001 From: Doug Ferraz Date: Tue, 5 Jul 2022 11:53:34 -0400 Subject: [PATCH] chg: improvements to chef readme file --- examples/chef/README.md | 45 +++++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/examples/chef/README.md b/examples/chef/README.md index cacd895b2c0342..03c8506d2072fa 100644 --- a/examples/chef/README.md +++ b/examples/chef/README.md @@ -1,25 +1,23 @@ # MATTER CHEF APP -The purpose of the chef app is to to increase the coverage of device types in -Matter. +The purpose of the chef app is to to: +1. Increase the coverage of device types in Matter +2. Provide a sample application that may have its data model easily configured. -It uses the shell app a starting point, adding the processing of ZAP files and -the support of a few targets under a unified build script: `chef.py`. +Chef uses the shell app a starting point, but processes the data model defined +on ZAP files during build time. This procedure is handled by its unified build +script: `chef.py`. As it incorporates the processing of ZAP files as part of the build process, it does not use `zzz_generated`, but rather places the auto-generated zap artifacts -under its `zap-generated` temporary folder. +under its `out` temporary folder. -All device types available (DM/IM .zap files) are found inside the `devices` +All device types available (.zap files) are found inside the `devices` folder. -## Building a Sample Application - -Run `chef.py -h` to see the available commands - ## Building your first sample -1. Make sure you have the toolchain installed for your desired target +1. Make sure you have the toolchain installed for your desired target. 2. Run `chef.py` the first time to create a `config.yaml` configuration file. If you already have SDK environment variables such as IDF_PATH (esp32) and ZEPHYR_BASE (nrfconnect) it will use those values as default. @@ -44,11 +42,12 @@ Run `chef.py -h` to see the available commands TTY: /dev/ttyUSB0 ``` -4. Run `$ chef.py -u` to update zap and the toolchain (on selected platforms) +4. Run `$ chef.py -u` to update zap and the toolchain (on selected platforms). 5. Run `$ chef.py -gzbf -t -d lighting`. This command will run the ZAP GUI opening the `devices/lighting.zap` file and will allow editing. It will then generate the zap artifacts, place them on the `zap-generated` - folder, run a build and flash the binary in your target + folder, run a build and flash the binary in your target. +6. Run `chef.py -h` to see all available commands. ## Creating a new device type in your device library @@ -59,6 +58,26 @@ Run `chef.py -h` to see the available commands into the `devices` folder. This device is now available for the script. See `chef.py -h` for a list of devices available. +## Folder Structure and Guidelines + +- ``: build system and `main.cpp` file for every supported platform. + When porting a new platform, please minimize the source code in this folder, + favoring the `common` folder for code that is not platform related. +- `common`: contains code shared between different platforms. It may contain + source code that enables specific features such as `LightingManager` class or + `LockManager`, as long as the application dynamically identify the + presence of the relevant cluster configurations and it doesn't break the use + cases where chef is built without these clusters. +- `devices`: contains the data models that may be used with chef. As of Matter + 1.0 the data models are defined using .zap files. +- `out`: temporary folder used for placing ZAP generated artifacts. +- `sample_app_util`: guidelines and scripts for generating file names for new + device types committed to the `devices` folder. +- `config.yaml`: contains general configuration for the `chef.py` script. As of + Matter 1.0 this is used exclusively for toolchain and TTY interface paths. +- `chef.py`: main script for generating samples. More info on its help + `chef.py -h`. + ## CI All CI jobs for chef can be found in `.github/workflows/chef.yaml`.