OpenWeave 工廠佈建工具

在 GitHub 上查看來源

OpenWeave 工廠帳戶管理工具提供方便的管道，可將持續性裝置設定資訊佈建至支援 Weave 的裝置。工廠佈建工具的用途是用於製造線程式，在出貨給客戶前，為個別裝置加上專屬身分和憑證資訊。開發人員也可以使用這項功能，在開發過程中為預先製作硬體進行客製化。

運作原理

OpenWeave 工廠佈建工具的目標是將特定設定資訊插入裝置的持續設定儲存空間，讓裝置韌體在執行階段擷取並使用這些資訊。永久性裝置設定通常儲存在裝置的內部 Flash 中，但可掌握確切的資料儲存方式和格式，會因平台而異。工廠佈建工具本身與最終儲存格式無關，而且需要用裝置韌體中的程式碼，以正確方式寫入資料。這項工具的使用者介面也幾乎不受所設定硬體類型的影響，也就是說，不同硬體平台的產品線可以採用類似的製造程序。

工廠佈建工具的設計目的是在主機上執行，該主機會透過某種偵錯或控制介面 (例如 JTAG 或 SWD 通訊埠) 連線至目標裝置。這項工具會以特殊編碼格式，將佈建資訊注入裝置的 RAM。接著，系統會指示裝置重新啟動，此時裝置韌體內建的程式碼會找出已編碼的資料並驗證其完整性，並根據平台適用的格式，將所含值寫入永久儲存空間。

用於偵測及處理插入的佈建資料的裝置端程式碼已內建於 OpenWeave Device Layer，可在任何支援的平台上啟用。啟用後，系統會在裝置每次啟動時，在裝置初始化程序早期的時間點自動執行程式碼。程式碼會掃描特定平台的 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 憑證和私密金鑰
• 編織配對碼
• 產品修訂版本編號
• 製造日期

雖然裝置通常需要上述所有資訊才能正常運作，但不一定要同時提供所有資訊。因此，在製造過程的不同階段，可能會提供不同類型的資訊。此外，您可以在後續佈建步驟中，將先前佈建的值替換為新值。

佈建資訊來源

您可以透過下列方式，將裝置佈建資訊提供給工廠佈建工具：

• 指令列引數
• 使用佈建 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	整數	產品修訂版本編號。
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 Factory Provisioning Tool 支援下列指令列選項：

選項	說明
--target <string>	目標裝置類型。選擇：nrf52840、esp32
--load-addr <十六進位數字>	裝置記憶體中的位址，用於寫入佈建資料。
--verbose、-v	調整輸出詳細程度。使用多個引數可增加詳細程度。
--serial-num <string>	設定裝置序號。
--device-id <hex-digits>	設定製造商指派的裝置 ID。
--device-cert <base-64> | <檔案名稱>	設定製造商指派的 Weave 裝置憑證。
--device-key <base-64> | <file-name>	設定製造商指派的 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> | 自動調整 | 自動	J-Link 介面速度。
--jlink-sn <string>	J-Link 探針序號。
--esptool-cmd <path-name>	esptool 指令的路徑。預設為「esptool.py」。
--port <path-name>	ESP32 的 COM 連接埠裝置名稱。預設為 /tty/USB0。
--speed <integer>	COM 通訊埠的波特率。預設值為 115200。
--prov-csv-檔案 <檔案名稱>	讀取佈建 CSV 檔案中的裝置佈建資料。
--prov-server <url>	從佈建伺服器讀取裝置佈建資料。
--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