OpenWeave 工厂配置工具

OpenWeave 出厂配置工具提供了一种便捷的方式，可将永久性的每台设备配置信息配置到支持 Weave 的设备。工厂配置工具旨在用于制造流程，在设备发货给客户之前，为每台设备打上唯一的身份和凭据信息。开发者还可以使用它来对开发过程中使用的预生产硬件进行个性化设置。

运作原理

OpenWeave 出厂配置工具的目标是将精选的配置信息注入设备的永久配置存储区，以便设备固件在运行时提取并使用这些信息。永久性设备配置通常存储在设备的内部闪存中，但有关数据存储方式和格式的详细信息会因平台而异。工厂配置工具本身独立于最终存储格式，并依赖于设备固件中的代码以正确的方式写入数据。该工具的界面在很大程度上独立于所配置的硬件类型，这意味着，基于不同硬件平台的产品系列可以采用类似的制造流程。

工厂配置工具专为在通过某种调试或控制接口（例如 JTAG 或 SWD 端口）连接到目标设备的主机上运行而设计。该工具的运作方式是将配置信息以特殊编码形式注入设备的 RAM。然后，设备被指示重启，此时设备固件中内置的代码会定位已编码的数据，验证其完整性，并以适合平台的格式将包含的值写入永久性存储空间。

用于检测和处理注入的配置数据的设备端代码内置于 OpenWeave 设备层，可在任何受支持的平台上启用。启用此代码后，每次设备启动时，该代码都会在设备初始化过程的早期阶段自动运行。该代码的运作方式是扫描平台专用 RAM 区域。在内存较少（例如小于 1M）的平台上，扫描范围涵盖所有可用 RAM。

放置在 RAM 中时，配置数据会使用易于识别的前缀进行编码，以便在扫描过程中快速找到。基于加密哈希的完整性检查值用于在处理之前确认数据的有效性。

默认情况下，配置工具会根据目标设备平台选择将配置数据注入的 RAM 位置。您可以通过向该工具传递参数来替换此选项。通常，设备固件无需专门为接收配置数据预留 RAM 位置。更常见的是，配置数据会写入分配用于其他用途的 RAM 位置，但通常在设备启动流程的早期未使用。常用选项包括初始系统堆栈的顶部或堆竞技场的远端。

工厂配置工具依赖于一组外部开发工具来与目标设备交互。所使用的具体工具取决于目标设备的类型。目前支持两种设备接口：

连接到设备的 JTAG 或 SWD 端口的 SEGGER J-Link 调试探针
连接到 Espressif ESP32 的 USB 串行端口

J-Link 接口依赖于 SEGGER J-Link Commander 工具 (JLinkExe)，该工具必须在主机上单独安装。

ESP32 接口依赖于 Espressif esptool.py 命令，该命令作为 Espressif 的 ESP-IDF SDK 的一部分提供。

可预配的信息类型

OpenWeave 工厂配置工具能够配置以下类型的信息：

设备序列号
制造商分配的 Weave 设备 ID
制造商分配的 Weave 证书和私钥
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`	字符串	Weave 配对码。
`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 <string>	目标设备类型。选项包括：nrf52840、esp32
--load-addr <hex-digits>	设备内存中用于写入配置数据的地址。
--verbose、-v	调整输出详细程度级别。使用多个参数可提高详细程度。
--serial-num <string>	设置设备序列号。
--device-id <十六进制数字>	设置制造商分配的设备 ID。
--device-cert <base-64> \| <file-name>	设置制造商分配的 Weave 设备证书。
--device-key <base-64> \| <文件名>	设置制造商分配的 Weave 设备私钥。
--pairing-code <string>	设置设备配对码。
--product-rev <integer>	为设备设置产品修订版。
--mfg-date <YYYY/MM/DD> \| 今天 \| 现在	设置设备的制造日期。
--jlink-cmd <path-name>	JLink 命令的路径。默认值为“JLinkExe”。
--jlink-if SWD \| JTAG	J-Link 接口类型。默认值为 SWD。
--jlink-speed <integer> \| adaptive \| auto	J-Link 接口速度。
--jlink-sn <string>	J-Link 探针序列号。
--esptool-cmd<路径名称>	esptool 命令的路径。默认为“esptool.py”。
--port <path-name>	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