Matter - 配置工厂数据（2）
部分关键名词参数简介
- PASE(Passcode-Authenticated Session Establishment): 基于密码认证的会话建立，用于在 Commissioning 的时候 Commissioner 与 Matter Deivce 之间建立安全信道，生成对称加密密钥用于 Commissioning 后续通信消息进行加、解密和完整性保护。
- Passcode(or Pincode): 密码或口令，用于在 Commissioning 的时候会话建立过程的输入参数之一。也是 QR 码中包含的一个重要信息。
- Discriminator: 鉴别码。Matter Device 在 Commissioning 时会进行蓝牙广播(Advertising)，广播中包含该信息。Commissioner 通过鉴别码来识别入网设备，两者鉴别码一致才开始 Commissioning 流程。
- Spake2+: 密码认证的密钥交换算法，PASE 建立过程中使用的算法。Matter 规范里有详细的介绍。
- Verifier: 验证器，用于在 Commissioning 的时候 PASE 会话建立过程的输入参数之一。
- Iteration count: 迭代次数，用于在 Commissioning 的时候 PASE 会话建立过程的输入参数之一。
- Salt: 盐值，用于在 Commissioning 的时候 PASE 会话建立过程的输入参数之一。
工厂数据参数
工厂数据是在制造过程中写入非易失性存储器的一组设备参数，在设备启动初始化时读取。所有出厂数据参数均受到保护，不会被软件修改，并且固件数据参数集在设备的使用寿命期间必须保持不变，实施固件时，必须确保在设备固件更新 (DFU) 或恢复出厂设置期间不会重写或覆盖出厂数据参数。对于 nRF Connect 平台，出厂数据默认存储在芯片内部 flash 的单独分区中。这有助于通过应用硬件写保护来保证工厂数据的安全。Fprotect 是硬件闪存保护驱动程序，用它来确保内部闪存中的工厂数据分区写保护。
| Key name | Full name | Length | Format | Conformance | Description |
|---|---|---|---|---|---|
| version | 出厂数据版本 | 2 B | uint16 | 强制 | 当前工厂数据集的版本。用户无法更改它，并且必须与设备端当前版本的 Factory Data Provider 保持一致。 |
| sn | 序列号 | <1, 32> B | ASCII string | 强制 | 序列号参数定义制造设备的唯一编号。序列号的最大长度为 32 个字符。 |
| vendor_id | 供应商ID | 2 B | uint16 | 强制 | CSA 为负责生产设备的组织分配的 ID |
| product_id | 产品编号 | 2 B | uint16 | 强制 | 设备供应商分配的用于识别产品的唯一 ID。它默认为 CSA 分配的 ID，用于指定非生产或测试产品。 |
| vendor_name | 供应商名称 | <1, 32> B | ASCII string | 强制 | 可读的供应商名称，提供一个简单的字符串 |
| product_name | 产品名称 | <1, 32> B | ASCII string | 强制 | 可读的产品名称，提供一个简单的字符串 |
| date | 生产日期 | 10 B | ISO 8601 | 强制 | 使用的日期格式为 ISO 8601，例如 YYYY-MM-DD |
| hw_ver | 硬件版本 | 2 B | uint16 | 强制 | 值的含义和版本由供应商定义 |
| hw_ver_str | 硬件版本字符串 | <1, 64> B | uint16 | 强制 | 值的含义和版本由供应商定义 |
| rd_uid | 旋转设备唯一标识 | <16, 32> B | byte string | 强制 | 由随机生成的 128 位（或更长）八位字节字符串组成。在首次引入设备后，应防止该参数通过无线方式读取或写入，并在设备的使用寿命期间保持固定。使用工厂数据支持构建应用时，必须使用工厂数据分区中存储的实际长度来设置 CONFIG_CHIP_FACTORY_DATA_ROTATING_DEVICE_UID_MAX_LEN。 |
| dac_cert | 设备认证证书 | <1, 602> B | byte string | 强制 | 设备证明证书 (DAC) 和相应的私钥对于每个 Matter 设备都是唯一的。 DAC 用于设备认证过程以及对结构进行调试。 DAC 是符合 RFC 5280 中定义的 DER 编码 X.509v3 兼容证书。 |
| dac_key | 设备认证密钥 | 68 B | byte string | 强制 | 与设备证明证书 (DAC) 关联的密钥。该密钥应该被加密，并且在生成并将其提供给工厂数据时应保证最大的安全性。 |
| pai_cert | PAI 证书 | <1, 602> B | byte string | 强制 | Product Attestation Intermediate Certificate 产品认证机构证书，PAI 证书是 X.509 兼容的，并且以 DER（Distinguished Encoding Rules）格式编码，根据 RFC 5280 的定义。 |
| spake2_it | Spake2+ 迭代次数 | 4 B | uint32 | 强制 | 在 SPAKE2+ 协议中，SPAKE2+ 迭代计数器（iteration counter）指的是在 SPAKE2+ 验证器生成过程中使用的 PBKDF2（密码基密钥导出函数，Password-Based Key Derivation Function 2）的迭代次数 |
| spake2_salt | Spake2+ salt 值 | <32, 64> B | byte string | 强制 | SPAKE2+ 中的 salt 值是一个随机的数据片段，长度至少为 32 字节。它被用作单向函数的额外输入，该函数执行密码学操作。对于每个密码，都应随机生成一个新的盐值。 |
| spake2_verifier | Spake2+ 验证器 | 97 B | byte string | 强制 | SPAKE2+ 验证器是使用 SPAKE2+ salt值、迭代计数器和密码生成的。 |
| discriminator | BLE 配对识别器 | 2 B | uint16 | 强制 | discriminator 在 Matter 协议中是一个用于辅助设备发现和区分的关键字段，通过提供一个唯一的识别码，它帮助确保在设备配置和连接过程中的正确性和有效性 |
| passcode | PASE 会话密码 | 4 B | uint32 | 可选 | 配对密码是一个27位的无符号整数，有效的配对密码值被限制在 0x0000001 到 0x5F5E0FE，有一些特定的数值不被视为有效的配对密码，这些包括所有的重复数字（如 11111111、22222222 等）、以及 12345678 和 87654321 这两个顺序性较强的数字序列。设备的组网（commissioning）过程中，配对密码用作拥有权的证明。当一个新设备被添加到网络中时，需要输入这个密码来验证操作者有权对设备进行配对和配置。 |
| product_appearance | 产品外观 | 2 B | CBOR map | 可选 | 是用来描述产品可见外观的结构。这个字段以 CBOR（Concise Binary Object Representation，简洁二进制对象表示法）映射的形式提供，并且包含两个属性：finish（表面处理，1 字节）和 primary_color（主要颜色，1 字节）。 |
| user | 用户数据 | variable, max 1024 B | CBOR map | 可选 | 用户数据（User Data）以 JSON 格式提供。这个参数是可选的，具体使用取决于设备制造商的用途。它作为一个 CBOR 映射类型从持久存储中提供，并应在用户应用程序中进行解析。需要注意的是，Matter 栈不使用这些用户数据。 |
connectedhomeip 目录下执行 python3 scripts/tools/nrfconnect/generate_nrfconnect_chip_factory_data.py -h，查看生成工厂数据需要提供的相关参数：
必需参数
--sn SN: 设备的序列号，用于在 Matter 证书结构中识别序列号字段。序列号的最大长度为 20 字节。--vendor_id VENDOR_ID: 提供供应商识别号（整数或十六进制）。--product_id PRODUCT_ID: 提供产品识别号（整数或十六进制）。--vendor_name VENDOR_NAME: 提供人类可读的供应商名称。--product_name PRODUCT_NAME: 提供人类可读的产品名称。--date DATE: 提供制造日期，使用 ISO 8601 格式，例如 YYYY-MM-DD。--hw_ver HW_VER: 提供硬件版本（整数或十六进制格式）。--hw_ver_str HW_VER_STR: 提供硬件版本的字符串表示形式。--spake2_it SPAKE2_IT: 提供 Spake2+ 迭代次数（整数或十六进制）。--spake2_salt SPAKE2_SALT: 提供 Spake2+ 盐值（Base64 字符串）。--discriminator DISCRIMINATOR: 提供 BLE 配对鉴别码，一个与设置代码中同名字段相匹配的 12 位值。可选参数
--product_url PRODUCT_URL: 提供指向产品特定网页的链接。--product_label PRODUCT_LABEL: 提供人类可读的产品标签。--part_number PART_NUMBER: 提供人类可读的产品编号。--chip_cert_path CHIP_CERT_PATH: 生成 DAC 和 PAI 证书的路径。--dac_cert DAC_CERT: 提供包含 DAC 证书的 .der 文件路径。--dac_key DAC_KEY: 提供包含 DAC 密钥的 .der 文件路径。--generate_rd_uid: 生成新的旋转设备唯一 ID。--pai_cert PAI_CERT: 提供包含 PAI 证书的 .der 文件路径。--passcode PASSCODE: 默认的 PASE 会话密码。--spake2_verifier SPAKE2_VERIFIER: 提供 Spake2+ 验证器，而不是生成它。--enable_key ENABLE_KEY: 启用键，用于触发制造商特定动作。--gen_cd: 生成证书声明。--cd_type CD_TYPE: 生成的认证声明类型：0 - 开发，1 - 临时，2 - 正式。--paa_cert PAA_CERT: 提供用于生成 PAI 证书的产品认证机构证书路径。--paa_key PAA_KEY: 提供用于生成 PAI 证书的产品认证机构密钥路径。--generate_onboarding: 生成手册代码和 QR 码。--product_finish: 提供产品的表面处理。--product_color: 提供产品的颜色。
工厂数据配置
1、命令行：
例如，Python 脚本的最终调用可能类似于以下内容：
python3 scripts/tools/nrfconnect/generate_nrfconnect_chip_factory_data.py \
--sn "11223344556677889900" \
--vendor_id 65521 \
--product_id 32774 \
--vendor_name "Nordic Semiconductor ASA" \
--product_name "not-specified" \
--date "2022-02-02" \
--hw_ver 1 \
--hw_ver_str "prerelase" \
--dac_cert "credentials/development/attestation/Matter-Development-DAC-FFF1-8006-Cert.der" \
--dac_key "credentials/development/attestation/Matter-Development-DAC-FFF1-8006-Key.der" \
--pai_cert "credentials/development/attestation/Matter-Development-PAI-FFF1-noPID-Cert.der" \
--spake2_it 1000 \
--spake2_salt "U1BBS0UyUCBLZXkgU2FsdA==" \
--discriminator 0xF00 \
--generate_rd_uid \
--passcode 20202021 \
--product_finish "matte" \
--product_color "black" \
--out "build.json" \
--schema "scripts/tools/nrfconnect/nrfconnect_factory_data.schema"
--sn "11223344556677889900"：设备的序列号。
--vendor_id 65521：供应商标识号。
--product_id 32774：产品标识号。
--vendor_name "Nordic Semiconductor ASA"：供应商名称。
--product_name "not-specified"：产品名称。
--date "2022-02-02"：制造日期。
--hw_ver 1：硬件版本。
--hw_ver_str "prerelase"：硬件版本的字符串表示。
--dac_cert和--dac_key：DAC（Device Attestation Certificate）的证书和密钥文件的路径。
--pai_cert：PAI（Product Attestation Identity）的证书文件路径。
--spake2_it 1000：SPAKE2+ 迭代次数。
--spake2_salt "U1BBS0UyUCBLZXkgU2FsdA=="：SPAKE2+ salt 的 base64 编码值。
--discriminator 0xF00：BLE 配对鉴别码。
--generate_rd_uid：生成旋转设备唯一标识符（RD UID）。
--passcode 20202021：配对密码。
--product_finish "matte"：产品的表面处理类型，这里是哑光（matte）。
--product_color "black"：产品的颜色，这里是黑色。
--out "build.json"：生成的工厂数据的输出路径。
--schema "scripts/tools/nrfconnect/nrfconnect_factory_data.schema"：JSON 模式文件的路径，用于验证生成的工厂数据。
生成手动配对代码和 QR 码，首先需要安装 Matter 网络相关的 Python 依赖。通过以下命令来安装：
python -m pip install -r ./scripts/setup/requirements.nrfconnect.txt
在脚本的最终调用中添加 --generate_onboarding 参数，执行后在 --out 指定目录下生成：
- 最新工厂数据集的 JSON 文件。
- 包含生成的手动代码和QR码文本版本的测试文件
。- PNG 格式的 QR 码图像。
使用目标 .json 文件生成 factory.hex、factory.bin 文件，移动至 matter libraries 根目录：
python3 scripts/tools/nrfconnect/nrfconnect_generate_partition.py -i build/zephyr/factory_data.json -o build/zephyr/factory_data --offset 0xfb000 --size 0x1000
python3 scripts/tools/nrfconnect/nrfconnect_generate_partition.py -i
-o --offset --size
：提供 .json 文件路径。 ：提供输出路径。 ：提供烧录到内部 flash 中的分区偏移地址。 ：提供分区大小。
使用 nrfjprog 工具烧录至芯片的工厂数据分区中：
nrfjprog --program factory_data.hex
使用 west 编译应用程序时，使能 CONFIG_CHIP_FACTORY_DATA、DCONFIG_CHIP_FACTORY_DATA_BUILD、DCONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE，生成应用程序固件时同时生成工厂数据的 .hex、.bin 文件和 QR 码相关文件在 build/zephyr 路径（默认）中，同时合并固件，如：
west build -b nrf5340dk_nrf5340_cpuapp -- \
-DCONFIG_CHIP_FACTORY_DATA=y \
-DCONFIG_CHIP_FACTORY_DATA_BUILD=y \
-DCONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE=y
添加禁用 DCONFIG_CHIP_FACTORY_DATA_USE_DEFAULT_CERTS=n，将自动生成新的CD、DAC、PAI 证书添加到工程数据中。
2、VS Code
新建 matter light_bulb 工程，使用默认工程配置文件 prj.conf ，默认打开 OTA、工厂数据配置生成等，nRF Kconfig GUI 下，Modules -> connectedhomeip -> ...更改相关配置。
参考：Configuring factory data for the nRF Connect examples