examples/chef/sample_app_util/README.md

# 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] 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
```

[^hash_note]:

    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.

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