 前往 GitHub 查看原始碼
|
只要使用 OpenWeave Factory Provisioning Tool，即可在支援 Weave 的裝置上佈建永久的裝置設定資訊。工廠佈建工具的用途是製造細部線路的一部分，在裝置出貨前，以不重複的身分和憑證資訊來標示個別裝置。開發人員也可以用來自訂在開發過程中使用的正式生產前硬體。
作業理論
OpenWeave Factory Provisioning Tool 的目標是將特定設定資訊插入裝置的永久設定存放區，讓裝置在執行階段接收及使用裝置的韌體。永久裝置設定通常儲存在裝置的內部 Flash 中，但確切的資料儲存方式和格式則因平台而異。工廠佈建工具本身並非最終的儲存格式，並且需要仰賴裝置中的程式碼以正確的方式寫入資料。這項工具的使用者介面主要與設置的硬體類型無關，也就是說，以不同硬體平台為基礎的產品系列，都可以執行類似的製造流程。
「工廠佈建工具」是專為在透過機器 (如 JTAG 或 SWD 連接埠) 連線或控制介面連線至主機裝置的主機上執行的作業。這個工具的運作方式是將佈建資訊以特殊編碼形式插入裝置的 RAM。然後指示裝置重新啟動，這時內建於裝置韌體的程式碼，會找出編碼資料、驗證其完整性，並將內含的值寫入永久儲存空間中，並採用適用於平台的格式。
偵測及處理插入的佈建資料的裝置程式碼內建於 OpenWeave 裝置層，可在任何支援的平台上啟用。啟用後，系統會在裝置啟動時，在裝置初始化程序初期的時間點自動執行程式碼。 此程式碼會掃描平台專屬的 RAM 區域。在具有少量記憶體 (例如，<1>1) 的平台上，掃描時，會包含所有可用 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's ESP-IDF SDK 的一部分提供的。
可佈建的資訊類型
OpenWeave Factory Provisioning Tool 能夠佈建以下類型的資訊：
- 裝置序號
- 製造商指派的 Weave 裝置 ID
- 製造商指派的 Weave 憑證和私密金鑰
- Weave 配對碼
- 產品修訂版本編號
- 製造日期
雖然裝置通常會需要上述所有資訊才能正常運作，但並不需要同時佈建所有資訊。因此，在製作過程中的不同時間點，可以佈建不同類型的資訊。此外，您可以在後續的佈建步驟中，將之前佈建的值替換為新值。
佈建資訊來源
您可以透過以下方式將裝置佈建資訊傳送到「原廠帳戶管理工具」：
- 指令列引數
- 使用佈建 CSV 檔案
- 從 Nest 佈建伺服器擷取值
指令列
最簡單的方式是直接在 OpenWeave Factory Provisioning Tool 的指令列中指定裝置佈建資訊。 例如：
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--pairing-code NESTUS --mfg-date 2019/04/01
二進位資料值 (例如 Weave 憑證和私密金鑰) 可以指定為 Base-64 字串，也可以指定為包含所需資料且採用原始 (二進位) 格式的檔案名稱。
完整的可用指令列引數清單請見下方。
佈建 CSV 檔案
為因應大量裝置佈建作業，Factory Provisioning Tool 也可以讀取 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 位數的十六進位數字 | 裝置 ID。必須包含。 |
Serial_Num |
字串 | 裝置序號。 |
Certificate |
base-64 字串 | 製造商指派的 Weave 裝置憑證。 |
Private_Key |
base-64 字串 | 製造商指派的 Weave 私密金鑰。 |
Pairing_Code |
字串 | 配對配對碼。 |
Product_Rev |
整數 | 產品修訂版本編號。 |
Mfg_Date |
YYYY/MM/DD | 裝置製造日期。 |
資料欄可能會以任何順序顯示在 CSV 檔案中。所有資料欄均為選填，但 Device_Id 除外。任何「不存在」CSV 檔案的值都不會
直接在裝置上佈建。
除了 CSV 檔案以外，使用者還可以在指令列中指定個別佈建值。在這種情況下，指令列值會優先在檔案值前面。
恢復原廠設定工具支援的 CSV 檔案格式支援 weave 工具的 gen-provisioning-data 指令。
Nest 佈建伺服器
Factory Provisioning Tool 支援使用 HTTPS 式通訊協定，從 Nest 佈建伺服器中擷取特定的帳戶管理資訊。 佈建伺服器通訊協定可用來從 Manufacturer Center 擷取製造商指派的 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 <十六進位數字> | 設定製造商指派的裝置 ID。 |
| --device-cert <base-64> | <file-name> | 設定製造商指派的 Weave 裝置憑證。 |
| --device-key <base-64> | <file-name> | 設定製造商指派的 Weave 裝置私密金鑰。 |
| --配對碼 <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-file <file-name> | 從佈建 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