 在 GitHub 上查看源代码
|
OpenWeave 出厂配置工具提供了一种便捷的途径，用于将每台设备的永久性配置信息配置到启用了 Weave 的设备上。出厂配置工具旨在为生产线流程的一部分，在将设备寄给客户之前，为每台设备印上唯一的身份和凭据信息。开发者还可以使用它对开发过程中使用的预生产硬件进行个性化。
运算理论
OpenWeave 出厂配置工具的目标是将选定的配置信息注入设备的持久性配置存储区，以便设备固件在运行时获取和使用它。持久性设备配置通常存储在设备的内部闪存中，但具体的数据存储方式以及格式各不相同则因平台而异。出厂配置工具本身独立于最终存储格式，并依赖设备固件中的代码以正确的方式写入数据。此工具的界面在很大程度上也与配置的硬件类型无关，这意味着，可以在基于不同硬件平台的产品线中使用类似的制造工艺。
出厂配置工具设计为在通过某种形式的调试或控制界面（例如 JTAG 或 SWD 端口）连接到目标设备的主机上运行。该工具的工作原理是采用特殊编码的形式将配置信息注入设备的 RAM。然后，系统指示设备重启，这时设备固件内置的代码会定位编码数据、验证其完整性，并以适合平台的格式将所包含的值写入持久性存储空间。
设备上代码用于检测和处理注入的配置数据内置于 OpenWeave 设备层，并且可在任何支持的平台上启用。启用后，代码会在每次设备启动时自动运行，在设备初始化过程的早期运行。 此代码通过扫描平台特定的 RAM 区域来运行。在内存适度装载的平台（例如 <1M）上，扫描包含所有可用 RAM。
存储在 RAM 中时，系统会使用易识别的前缀对配置数据进行编码，以便在扫描过程中快速找到这些数据。基于加密哈希值的完整性检查值用于在处理之前确认数据的有效性。
默认情况下，配置工具会根据目标设备平台选择要将配置数据注入到 RAM 的位置。可以通过工具的参数替换此选项。一般来说，设备固件无需专门预留 RAM 位置来接收配置数据。更常见的情况是，将数据写入用于其他用途的 RAM 位置，但在设备启动过程的早期阶段一般不会使用。常见选项包括初始系统堆栈的顶部或堆竞技场的最远端。
出厂配置工具依赖于一组外部开发工具与目标设备连接。具体采用的工具取决于目标设备的类型。目前支持两种设备接口：
- SEGGER J-Link 调试探测器已连接到设备的 JTAG 或 SWD 端口
- 一个与 Espressif ESP32 连接的 USB 串行端口
J-Link 接口依赖于 SEGGER J-Link Commander 工具 (JLinkExe)，必须单独安装在主机上。
ESP32 接口依赖于 Espressif esptool.py 命令，该命令作为 Espressif's ESP-IDF SDK 的一部分提供。
可配置的信息类型
OpenWeave 出厂配置工具能够配置以下类型的信息：
- 设备序列号
- 制造商指定的 Weave 设备 ID
- 制造商分配的 Weave 证书和私钥
- 编织配对码
- 产品修订版本号
- 制造日期
虽然设备通常需要以上所有信息才能正常运行，但不需要同时配置所有信息。因此，不同类型的信息可以在制造过程中的不同阶段进行配置。此外，可以在后续配置步骤中将之前配置的值替换为新值。
配置信息来源
可通过以下方式将设备配置信息提供给出厂配置工具：
- 命令行参数
- 使用配置 CSV 文件
- 从 Nest 配置服务器提取值
命令行
最简单的形式是直接在命令行中指定 OpenWeave 出厂配置工具。 例如：
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--pairing-code NESTUS --mfg-date 2019/04/01
二进制数据值（如 Weave 证书和私钥）可以指定为 Base-64 字符串，也可以指定为包含原始（二进制）形式所需数据的文件的名称。
如需查看可用命令行参数的完整列表，请参阅下文。
配置 CSV 文件
为了适应设备的批量配置，出厂配置工具还可以从 CSV 格式的配置数据文件中读取配置数据。此文件中的各列应为特定配置数据类型（即 Serial_Num、Certificate、Private_Key 等）。该文件中的各行用于为特定设备提供单独的值，并按 Weave 设备 ID (Device_Id) 编入索引。要配置的具体设备 ID 必须在命令行中指定。例如：
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-csv-file ./dev-provisioning-data.csv
支持以下 CSV 列：
| 名称 | 格式 | 说明 |
|---|---|---|
Device_Id |
16 位十六进制数字 | Weave 设备 ID。必须存在。 |
Serial_Num |
字符串 | 设备序列号。 |
Certificate |
base-64 字符串 | 制造商指定的 Weave 设备证书。 |
Private_Key |
base-64 字符串 | 制造商分配的 Weave 私钥。 |
Pairing_Code |
字符串 | 编织配对码。 |
Product_Rev |
integer | 产品修订号。 |
Mfg_Date |
YYYY/MM/DD | 设备制造日期。 |
列可以按任意顺序显示在 CSV 文件中。除 Device_Id 外，所有列均为可选列。CSV 文件中不存在的任何值都不会在设备上配置。
用户除了使用 CSV 文件之外，还可以在命令行中指定单独的配置值；在这种情况下，命令行值将优先于文件中的值。
出厂配置工具对 CSV 文件格式的支持与 weave 工具的 gen-provisioning-data 命令的输出兼容。
Nest 配置服务器
出厂配置工具支持使用基于 HTTPS 的协议从 Nest 配置服务器中提取选定的配置信息。配置服务器协议可用于从配置服务器中提取制造商分配的 Weave 设备证书、相应的私钥和 Weave 配对代码。
通过在配置工具命令行中提供基准网址，指定配置服务器的网络位置。您可以通过在命令行中指定 Weave 设备 ID 来选择所需配置信息。例如：
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-server https://192.168.172.2:8000/
用户可以在配置服务器网址之外使用命令行指定具体配置值。在这种情况下，在命令行中给出的值将优先于服务器返回的值。
启用 / 停用出厂配置支持
对设备固件中的 OpenWeave 出厂配置的支持由 WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 编译时配置选项控制。此选项默认处于启用状态。可以通过替换应用的 WeaveProjectConfig.h 文件中的选项来停用此功能。例如：
#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0
一般来说，在生产设备固件中启用出厂配置是安全的，前提是在正式版设备上正确停用了设备调试接口。这可以通过硬件方式（例如，在 SoC 中吹断）或通过软件来实现（例如，通过在启动过程中阻止调试访问的安全引导加载程序）。
运行出厂配置工具
OpenWeave 出厂配置工具支持以下命令行选项：
| 选项 | 说明 |
|---|---|
| --target <字符串> | 目标设备类型。选项包括：nrf52840、esp32 |
| --load-addr <十六进制数字> | 将写入配置数据的设备内存地址。 |
| --verbose，-v | 调整输出详细程度。使用多个参数可以提高详细程度。 |
| --serial-num <string> | 设置设备序列号。 |
| --device-id <十六进制数字> | 设置制造商指定的设备 ID。 |
| --device-cert <base-64> | <file-name> | 设置制造商指定的 Weave 设备证书。 |
| --device-key <base-64> | <file-name> | 设置制造商指定的 Weave 设备私钥。 |
| --pairing-code <string> | 设置设备配对码。 |
| --product-rev <integer> | 为设备设置产品修订版本。 |
| --mfg-date <YYYY/MM/DD> | 今天 | 现在 | 设置设备的制造日期。 |
| --jlink-cmd <路径名称> | JLink 命令路径。默认值为 'JLinkExe'。 |
| --jlink-if SWD | JTAG | J-Link 接口类型。默认值为 SWD。 |
| --jlink-speed <integer> | 自适应 | auto | J-Link 接口速度。 |
| --jlink-sn <string> | J-Link 探测序列号。 |
| --esptool-cmd <path-name> | esptool 命令的路径。默认值为 'esptool.py'。 |
| --port <路径名称> | ESP32 的 COM 端口设备名称。默认为 /tty/USB0。 |
| --speed <integer> | COM 端口的波特率。默认值为 115200。 |
| --prov-csv-file <file-name> | 从配置 CSV 文件中读取设备配置数据。 |
| --prov-server 网址 | 从配置服务器读取设备配置数据。 |
| --disable-server-validation | 使用 HTTPS 时，停用配置服务器提供的证书的验证。 |
示例
以下命令会将设备 ID、序列号、产品修订版本和配对代码设置为特定值。制造日期设为当前日期。设备证书和私钥设置为测试由 openweave-core 源代码库提供的 CSV 文件中给出的值。
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000042 \
--serial-num JAYS_DEVICE_42 --product-rev 1 --pairing-code NESTUS --mfg-date today \
--prov-csv-file ~/projects/openweave-core/certs/development/device/test-dev-provisioning-data.csv