Chef Build Conventions#

Overview#

It is convenient to follow some naming and build conventions for Chef tool due to the large volume of sample apps that may be created and the ambiguity that may result from arbitrary names.

There are three components to the convention proposed here:

The naming convention for the sample matter device and clusters (referred to here as the sample app).
The naming convention to use for the build files which will be flashed on the devices.
The usage of metadata files that shall accompany build files to provide more detailed information about builds.

The convention proposed here should be adopted by the zap files provided in examples/chef/devices and the builds generated from Chef tool in CI.

Limitations#

The largest filename that can be used on MacOS and Linux is 255 characters. If a sample app name would exceed this limit by following this convention, then the sample app should be given an arbitrary name.

This limitation is called out, but, with the given naming conventions, this should rarely happen.

Convention#

Sample App Naming Convention#

Sample apps should be named by concatenating the name of all endpoints in the order of their index. Endpoint names are separated by underscores (_) and a 10 character hash1 which is randomly generated.

The naming convention tool should be used for every newly created app. The name should only need to be updated if the endpoints of the app are changed.

Valid sample app names conform to the following format:

<endpoint_0>_<endpoint_1>_<hash>

For example, here are some valid names:

rootnode_extendedcolorlight_H1l9gnQDYl
rootnode_speaker_8qRQaEj0Hy
rootnode_lightsensor_L6dEbmVDah
rootnode_dimmablelight_rWsDiwzw2t
rootnode_pressuresensor_03quf7tPOL
rootnode_flowsensor_ixbAboycie
rootnode_windowcovering_b9QoiScjOq
rootnode_doorlock_d5wtU7sjFR
rootnode_thermostat_KuQYArmwl7
rootnode_dimmablelight_7pNE3GVarn
rootnode_temperaturesensor_i0wGnDVUAc
rootnode_occupancysensor_wyGeQSokNp
rootnode_humiditysensor_pv0comNKyT
bridgednode_temperaturesensor_onofflight_onoffpluginunit_MI9DSdkH8H

Sample App Build Naming Convention#

The sample app builds formats will be named by pre-pending the zap file name (described above) with the platform and appending connectivity info.

Valid build names conform to the following format:

<platform>_<sample_app_name>

Note that <sample_app_name> follows the convention: <endpoint_0>_<endpoint_1>_<hash>.

Together that is:

<platform>_<endpoint_0>_<endpoint_1>_<hash>

The list of platforms supported here (as of writing this) are:

m5stack
brd4187c
nrf52840dk
linux_x86

For example, here are some valid names:

m5stack_rootnode_humiditysensor_pv0comNKyT
brd4187c_rootnode_humiditysensor_pv0comNKyT
nrf52840dk_rootnode_humiditysensor_pv0comNKyT
linux_x86_rootnode_humiditysensor_pv0comNKyT

Metadata file convention#

Metadata files are yaml files that should accompany build files.

The metadata files have a structure as follows:

- <endpoint_0_name>:
      client_clusters:
          <client_cluster_name>:
              attributes:
                  <attribute_name>: <attribute_value>
                  ...
              commands:
                  - <command_name>
                  - ...
      server_clusters:
          <server_cluster_name>:
              attributes:
                  <attribute_name>: <attribute_value>
                  ...
              commands:
                  - <command_name>
                  - ...
- <endpoint_1_name>: ...

For an example, see sample_zap_file_meta.yaml which was generated from sample_zap_file.zap.

The following conventions are used:

All lists are sorted alphabetically.
If a list contains dictionaries, it will be sorted by the “name” key. If it does not contain “name” key, it will be sorted by the first key common to all dictionaries that comes first alphabetically.
The list of endpoints is excluded from the above conventions. Endpoints are ordered according to their endpoint number; here, the endpoint number is the same as the order they are read from the zap file.

As an example, take a look at sample_zap_file.yaml

Utility Usage#

There are a few primary usage cases for the utility sample_app_util.py. Details are provided by using python sample_app_util.py zap --help. Below is a summary.

Command	Description
`python sample_app_util.py zap <zap_file> --generate-name`	Generates the name for a zap file per the specified convention
`python sample_app_util.py zap <zap_file> --rename-file`	Renames the zap file per specified convention
`python sample_app_util.py zap <zap_file> --generate-metadata [output_path]`	Generates the metadata file adjacent to the zap file with `.yaml` extension. If `[output_path]` is provided then the metadata file will be stored at the location specified.

Running Tests#

Navigate to the base directory of this README.

cd <project_root>/examples/chef/sample_app_util

Run unit tests.

python -m unittest

1: The 10 character hash used to be generated by consuming the JSON encoded metadata. This is no longer the case. It was found that the hash encoding only served to differentiate one app from another (the initial goal) and there was little value in tying the generated hash to the config data because there wasn’t a use case for decoding it as long as the config file was packaged with the generated app.

Chef Build Conventions

Contents