examples/chef/sample_app_util/README.md - third_party/github/project-chip/connectedhomeip - Git at Google

 # 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 hash[^hash_note] 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
 ```

 [^hash_note]:

     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](zap_file_parser.py) 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.

 ### 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](test_files/sample_zap_file_hashmeta.yaml) which
 was generated from [sample_zap_file.zap](test_files/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](test_files/sample_zap_file.yaml)

 ## Utility Usage

 There are a few primary usage cases for the utility
 [sample_app_util.py](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
 ```
	# 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 hash[^hash_note] 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
	```

	[^hash_note]:

	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](zap_file_parser.py) 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.

	### 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](test_files/sample_zap_file_hashmeta.yaml) which
	was generated from [sample_zap_file.zap](test_files/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](test_files/sample_zap_file.yaml)

	## Utility Usage

	There are a few primary usage cases for the utility
	[sample_app_util.py](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
	```