Telink Python脚本生成工厂数据的步骤介绍

工厂数据是在制造过程中写入非易失性存储器的一组设备参数。

所有的工厂数据参数都受保护，以避免被软件修改。在设备使用周期内，固件的数据参数集必须保持不变。在生成固件时，除了某些厂商定义的情况，必须确保在设备固件更新或恢复出厂设置期间，工厂数据不会被重写或覆盖。

在生成固件的时候，可以用多种方式实现Matter工厂数据，只要保证最终的 HEX/BIN 文件包含工厂数据组件表中定义的所有强制要求的组件。

在本次分享中，我们描述了一种由我们的平台维护者创建的工厂数据集的实现方式。在完成后，将得到一个包含 `CBOR` 格式的工厂数据分区的十六进制和二进制文件。

1

工厂数据组件表和数据格式

工厂数据参数集包括不同类型的信息，例如设备证书、加密密钥、设备标识符，以及硬件等等。所有的这些参数都是特定于厂商的，并且在制造过程中，必须保存到设备的持久性存储器中。工厂数据参数将会在设备启动时被读取，然后可以被用在 Matter 协议栈和用户应用程序中（例如在配网过程中）。下表列出了工厂数据集中包含的参数：

工厂数据集需要被写入到Matter设备的闪存中，所以在我们的示例中，工厂数据集以 `CBOR` 格式表示，并存储在十六进制或二进制文件中。然后，该文件将被烧录到设备上。

工厂数据集的参数包括强制参数和可选参数：

必须始终提供强制性参数，因为设备在进行配网进入Matter网络时需要它们。

可选参数可用于开发和测试目的。例如，用户数据参数包含了特定制造商所需要的且不包含在强制性参数中的所有数据。

在工厂数据集中，使用了以下格式：

`uint16` 和 `uint32` -- 这些是分别表示两字节长度无符号整数，和四字节长度无符号整数的数字格式。此值以大端顺序存储在十六进制文件中`Byte string` -- 该参数表示在0到255之间（包括255）的整数序列，没有任何编码。由于JSON格式不允许使用字节字符串，因此将 `hex:` 前缀添加到参数中，并将其转换为十六进制字符串。

`ASCII string` 是ASCII编码中的字符串表示形式，没有空终止。

`ISO 8601` 格式是一种日期格式，表示以`YYYY-MM-DD`或`YYYYMMDD`格式提供的日期。

存储在工厂数据中的所有证书都以X.509格式提供。

2

启用工厂数据支持

在所有的 Telink 示例中，要开始使用存储在闪存和 Telink 平台中的工厂数据和 Telink 平台的 Factory Data Provider，请使用以下编译选项构建一个示例：

1、west build -- -DCONFIG_CHIP_FACTORY_DATA=y

3

生成工厂数据

本节介绍使用以下 Telink Python 脚本生成工厂数据的步骤。

检查和安装Matter依赖项

在使用生成器工具之前，请确保已具备以下工具。

CHIP Certificate Tool 

SPAKE2P Parameters Tool 

chip-tool 

安装的详细描述：

使用以下命令在 `path/to/connectedhomeip/build/out/host` 生成 chip-tool, spake2p 和chip-cert

cd path/to/connectedhomeip

source scripts/activate.sh

gn gen build/out/host

ninja -C build/out/host

在 $PATH 中加入工具路径

export PATH="$PATH:path/to/connectedhomeip/build/out/host"

在设备固件上准备工厂数据分区

工厂数据分区是设备持久存储中存储工厂数据集的区域。这个区域在 DeviceTrees 文件里进行配置。

对于 Matter v1.0-branch 分支，配置文件在Zephyr工程中，路径为：`zephyrproject/zephyr/boards/riscv/tlsr9518adk80d/tlsr9518adk80d.dts`。

对于 Matter v1.1-branch 分支，配置文件在Matter工程中，路径为：`connectedhomeip/src/platform/telink/tlsr9518adk80d.overlay`。

对于 Matter master 分支，配置文件在Matter工程中。不过，将对分区的声明从 `tlsr9518adk80d.overlay` 中提取出来，分别写作 `1m_flash.overlay`，`2m_flash.overlay`，和 `4m_flash.overlay`。那么，可以根据所选的芯片的 Flash 尺寸，去选择合适的配置文件。

若要准备一个客制化的支持工厂数据的示例，请在 `tlsr9518adk80d.dts`，`tlsr9518adk80d.overlay` 或 `Xm_flash.overlay` 文件中添加或修改一个名为 `factory-data` 的分区。分区大小应该是一个 flash page 的倍数（单个 page 大小等于 4kB）。

脚本使用

若要使用此脚本，请完成以下步骤：

1、进入 `connectedhomeip` 根目录。

2、使用 `-h` 选项运行脚本，以查看所有可能的选项：

python scripts/tools/telink/mfg_tool.py -h

3、准备一个参数列表：

填写所有强制性参数：

--serial-num --vendor-id, --product-id, --vendor-name, --product-name, --mfg-date, --hw-ver, --hw-ver-str, --enable-rotating-device-id, --spake2-path, --chip-tool-path, --chip-cert-path, --offset, --size

添加输出文件路径：

--output 

添加证书声明路径(必选)：

-cd 

指定使用哪个证书：

用户：

--dac-cert 

--dac-key 

--cert 

--key 

--pai

生成DAC和PAI：

--cert 

--key 

--paa

使用以下选项之一为轮换设备 ID 添加新的唯一 ID：

提供一个已存在的 ID：

--rdid--uid

生成一个新的 ID 并提供：

--enable-rotating-device-id

（可选）指定自己的密码：

--passcode

（可选）指定自己的鉴别码：

--discriminator

 (可选)添加覆盖现有输出文件的请求：

--overwrite

指定分区偏移量和大小：

--offset

--size

这个命令中：

是设备的持久存储区域中的地址，分区数据集将存储在其中。

是设备持久存储区域中分区的大小。根据这个值检查新数据，看它的大小是否适合。

重要提示：

对 Matter v1.0-branch 分支使用：

--offset 0xf4000 --size 0x1000

对 Matter ***v1.1-branch*** 分支使用：

--offset 0x104000 --size 0x1000

对最新的 Matter ***master*** 分支（2MB flash）使用：

--offset 0x107000 --size 0x1000

使用已准备好的参数列表运行该脚本

1、python3 mfg_tool.py

例如，对Python脚本的最终调用看起来类似于下面的用法：

python3 scripts/tools/telink/mfg_tool.py 

--vendor-id 0xFFF2 --product-id 0x8001 

--serial-num AABBCCDDEEFF11223344556677889900 

--vendor-name "Telink Semiconductor" 

--product-name "not-specified" 

--mfg-date 2022-12-12 

--hw-ver 1 

--hw-ver-str "prerelase" 

--enable-rotating-device-id 

--pai 

--key credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Key.pem 

--cert credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Cert.pem 

-cd credentials/test/certification-declaration/Chip-Test-CD-FFF2-8001.der 

--spake2-path build/out/host/spake2p 

--chip-tool-path build/out/host/chip-tool 

--chip-cert-path build/out/host/chip-cert 

--offset 0x107000 --size 0x1000 

--out ./factory_data_for_2mb_flash

作为上述示例的结果，将会生成以下文件：

可选示例/

生成多个工厂分区数据

[可选参数 ：--count]

python3 scripts/tools/telink/mfg_tool.py --count 2 -v 0xFFF2 -p 0x8001 

--serial-num AABBCCDDEEFF11223344556677889900 

--vendor-name "Telink Semiconductor" 

--product-name "not-specified" 

--mfg-date 2022-12-02 

--hw-ver 1 

--hw-ver-str "prerelase" 

--enable-rotating-device-id 

--pai 

--key credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Key.pem 

--cert credentials/test/attestation/Chip-Test-PAI-FFF2-8001-Cert.pem 

-cd credentials/test/certification-declaration/Chip-Test-CD-FFF2-8001.der  

--spake2-path build/out/host/spake2p 

--chip-tool-path build/out/host/chip-tool 

--chip-cert-path build/out/host/chip-cert 

--offset 0x107000 --size 0x1000 

--out ./factory_data_for_2mb_flash

作为上述示例的结果，将会生成以下文件：

*注意：默认情况下，生成的文件不能覆盖现有输出目录。如果想要允许覆盖，请将 `--overwrite` 选项添加到 Python 脚本的参数列表中。

审核编辑：刘清