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:

  1. The naming convention for the sample matter device and clusters (referred to here as the sample app).

  2. The naming convention to use for the build files which will be flashed on the devices.

  3. 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 of the sample app metadata is appended to the end.

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
brd4161a
nrf52840dk
linux_x86

For example, here are some valid names:

m5stack_rootnode_humiditysensor_pv0comNKyT
brd4161a_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_hashmeta.yaml which was generated from sample_zap_file.zap.

Note that it is more readable in yaml format. Since hashes are generated from the metadata info, additional conventions are needed to ensure consistency for the metadata structure.

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 is a base64 encoding of the md5 hash generated by digesting the JSON string encoding of the metadata information. The code for generating the hash can be found in generate_hash in zap_file_parser There are some notable details here: 1) The full base64 encoded hash is 16 characters, but only 10 are used. This still gives us a sufficiently low probability of collision (~1.2 x 10^-8). 2) _ and - are replaced in the base64 encoding because they have other uses in the naming. 3) Platform specific information is omitted from the hash. E.g. the networking_commissioning cluster is excluded. This is to make the hashes platform agnostic.