View a markdown version of this page

為 WiFi Simple Setup 設定佈建者 - 的受管整合 AWS IoT Device Management
佈建者需求製造需求啟用佈建者功能條碼掃描工作流程啟用時段和逾時重試 WSS 設定停用佈建者功能

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

為 WiFi Simple Setup 設定佈建者

在此頁面上：

佈建者需求

佈建裝置必須符合這些需求，才能支援 WiFi Simple Setup。

硬體和安全性

  • 受管整合 在IOTMI_USE_WSS_PROVISIONEE啟用建置旗標的情況下完成終端裝置 SDK 整合

  • 用於安全儲存的硬體安全模組 (HSM) 或信任平台模組 (TPM)

  • WiFi 連線功能

  • 適用於密碼編譯操作的足夠處理能力 (SHA-384、HKF)

身分驗證資料

  • 將憑證和私有金鑰安全地存放在 HSM/TPM 中

  • 唯一序號 (SN)：12-50 個字元英數字元

  • 通用產品代碼 (UPC)：12 位數或歐洲商品編號 (EAN)：13 位數

  • 顯示 SN 和 UPC/EAN 的條碼標籤 （在裝置或包裝上）

注意

EAN 支援：佈建器目前僅支援 UPC。計劃在未來版本提供 EAN 支援。佈建者同時支援 UPC 和 EAN。

重要：與客戶 AWS 帳戶中每個受管物件配對的 SN 必須是唯一的。

軟體元件

  • 將 PKCS#11 API 連線至 HSM/TPM 的 corePKCS11 平台抽象層 (PAL) 實作

  • 具有預先共用金鑰 (PSK) 功能的 TLS 1.2/1.3 用戶端 （連接埠 4433，密碼套件：TLS_AES_256_GCM_SHA384 或同等項目）

  • SOCKS5 代理用戶端支援 （連接埠 1080)

  • SHA-384 和 HKDF 的密碼編譯函數

注意：corePKCS11 PAL 必須連接實際的 HSM/TPM 硬體，而非僅軟體實作。

製造需求

裝置製造商必須在製造期間佈建安全的資料和識別符。

安全資料佈建

申請憑證和私有金鑰：

  • 在製造過程中產生

  • 存放在 HSM 或 TPM 中 （生產裝置需要）

  • 切勿在安全儲存體外部公開私有金鑰

  • 透過 corePKCS11 PAL 界面存取

裝置識別符：

  • 序號 (SN)：12-50 個字元的唯一識別符

  • 通用產品代碼 (UPC)：12 位數產品代碼或歐洲商品編號 (EAN)：13 位數產品代碼

  • 在 HSM/TPM 中安全地與宣告憑證一起存放

條碼需求

實體標籤必須包含：

  • 裝置或封裝上的 SN 條碼 （建議使用 Code 128 格式）

  • 裝置或封裝上的 UPC/EAN 條碼 (UPC-A 或 EAN-13 格式）

  • 輕鬆掃描的標籤 （光線充足、聚焦、無阻礙）

  • 可存活運送和處理的標籤

機群佈建設定

AWS 帳戶組態：

  1. 使用 GetCustomEndpoint API 建立自訂端點

  2. 使用 CreateProvisioningProfile API 建立佈建設定檔

  3. 取得裝置系列的宣告憑證和私有金鑰

  4. 使用必要欄位設定機群佈建範本：

    • deviceSerialNumber (SN)

    • universalProductCode (UPC) 或 europeanArticleNumber(EAN)

    • 裝置憑證產生支援

    • AWS IoT Core 中的物件註冊

啟用佈建者功能

在帳戶連結期間，使用 CreateManagedThing API 為裝置啟用 WSS。

裝置註冊


{
  "role": "DEVICE",
  "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e",
  "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE",
  "authenticationMaterial": "SN:123456789331;UPC:123456789331",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}

參數：

  • role：佈建者裝置必須為「DEVICE」

  • credentialLockerId：將裝置與家庭建立關聯 （與佈建器相同）

  • authenticationMaterialType：針對 WSS 使用 "WIFI_SETUP_QR_BAR_CODE"

  • authenticationMaterial：來自裝置條碼的 SN 和 UPC/EAN

  • enableAsProvisionee：設定為 true 以啟用 WSS

  • timeoutInMinutes：啟用時段持續時間 (5-15 分鐘，預設值 15)

重試或重新啟用

使用 UpdateManagedThing 在初始失敗後重試：


{
  "managedThingId": "existing-device-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}

條碼掃描工作流程

完成從條碼掃描到裝置啟用end-to-end工作流程。

步驟 1：準備

  • 確保行動應用程式已安裝並經過驗證

  • 確認佈建器裝置 （中樞） 已開啟電源並連線

  • 讓裝置和封裝可供掃描

步驟 2：掃描並註冊

  1. 開啟行動應用程式並導覽至裝置設定

  2. 掃描裝置序號 (SN) 條碼

  3. 掃描通用產品代碼 (UPC) 或歐洲文章編號 (EAN) 條碼

  4. 行動應用程式會驗證掃描的資料

  5. 行動應用程式使用掃描資料和 WSS 組態呼叫 CreateManagedThing API

重要

單一佈建者加入限制：一次只能加入一個佈建者。如果您同時掃描多個裝置，則只會加入最新的掃描裝置。若要加入先前已掃描但未啟用的裝置，您必須執行 UpdateManagedThing 以重新啟用其設定時段。

步驟 3：雲端啟用

自動處理雲端：

  1. 使用 WSS 組態建立受管物件記錄

  2. 啟用 15 分鐘設定時段

  3. 識別合格的佈建器 （相同的登入資料儲存庫、enableAsProvisioner=true、supportAsProvisioner=true)

  4. 傳送佈建通知給所有合格的佈建器

  5. 佈建器會建立臨時 SoftAPs並為裝置連線做好準備

GetManagedThing 回應範例：


{
  "managedThingId": "device-id", 
  "role": "DEVICE",
  "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e",
  "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE",
  "authenticationMaterial": "SN:123456789331;UPC:123456789331",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisioner": false,
    "supportAsProvisioner": false,
    "enableAsProvisionee": true,
    "wssExpirationTimeStamp": "2025-06-04T20:22:04.069610Z"
  }
}

金鑰欄位：

  • enableAsProvisionee：為 WSS 佈建設定的裝置

  • wssExpirationTimeStamp：作用中設定時段結束時間 （過期時為 Null)

步驟 4：裝置開機

  1. 行動應用程式會顯示「立即在您的裝置上開啟電源」訊息

  2. 佈建者裝置上的使用者電源

  3. WSS 工作流程會自動繼續：

    • 裝置探索佈建器 SoftAP

    • 身分驗證和憑證交換完成

    • 裝置連線至 WiFi

    • 行動應用程式會收到成功通知

啟用時段和逾時

WSS 使用限時時段和操作逾時來增強安全性和管理佈建。

啟用時段

預設：從條碼掃描到裝置啟用 15 分鐘

組態：

  • 透過 timeoutInMinutes 參數設定 （範圍：5-15 分鐘）

  • 預設：15 分鐘平衡便利性和安全性

過期行為：

  • 佈建程式在逾時後從允許清單中移除裝置

  • 裝置在過期後無法透過 WSS 連線

  • 使用者必須重新掃描條碼或呼叫 UpdateManagedThing 以重新啟用

操作逾時

WSS 操作逾時
作業 Timeout (逾時) Behavior (行為)
SoftAP 探索 30 秒 重試最多 5 次，然後返回 使用者指南設定
機群佈建 30 秒 如果失敗，則以指數退避重試
WiFi 連線 60 秒 報告錯誤，並在失敗時建議疑難排解

最佳實務

  • 在條碼掃描後 5 分鐘內開啟裝置電源，並將裝置放在佈建器的軟性 WiFi 範圍附近

  • 在掃描之前，請確定佈建器已開啟電源並連線

  • 除非特定要求另有指示，否則請使用預設的 15 分鐘逾時

重試 WSS 設定

如果初始 WSS 設定失敗，請使用 UpdateManagedThing API 重試。

重試工作流程

步驟 1：識別失敗

  • 行動應用程式收到 WSS 失敗通知

  • 逾時會在未成功啟用的情況下過期

  • 使用者看到「設定失敗」或「重試」訊息

步驟 2：透過 UpdateManagedThing 重試


{
  "managedThingId": "device-managed-thing-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}

步驟 3：重新啟用

  • 雲端會重新啟用 15 分鐘的設定時段

  • Provisioners 重新建立 SoftAP 和允許清單項目

  • 使用者開啟裝置的電源 （如果尚未開啟電源）

  • WSS 工作流程繼續

常見的重試案例

WSS 重試案例
案例 解決方案
裝置未及時開啟電源 立即呼叫 UpdateManagedThing 並開啟裝置電源
Provisioner 無法使用 確保中樞在線上，然後重試
網路連線問題 驗證網路穩定，然後重試
使用者錯誤 使用正確的裝置重試

重要：每個 UpdateManagedThing 呼叫都會建立新的 15 分鐘時段。在 3-4 次失敗後，請考慮檢查佈建器狀態、驗證裝置功能，或使用 使用者指南設定。

停用佈建者功能

停用或永久移除佈建者裝置的 WSS。

使用 UpdateManagedThing API


{
  "managedThingId": "device-managed-thing-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": false
  }
}

使用 DeleteManagedThing API


{
  "managedThingId": "device-managed-thing-id"
}

Comparison (比較)

停用與刪除比較
Action UpdateManagedThing DeleteManagedThing
裝置記錄 保留在雲端 永久移除
裝置狀態 已變更為已停用 不再存在
重新啟用 隨時重新啟用 WSS 必須重新註冊裝置
使用案例 暫時停用、測試 裝置已淘汰，安全事件

安全考量

在下列情況下使用停用/刪除：

  • 偵測到可疑活動

  • 裝置回報遭竊

  • 需要安全事件調查

  • 裝置已停用或已傳回

停用/刪除後，請考慮：

  • 如果登入資料可能已洩露，請變更 WiFi 密碼

  • 檢閱異常活動的安全通知

  • 檢查家中的其他裝置是否有類似問題