IoT 中樞的裝置更新使用 IoT 隨插即用探索及管理支援無線更新的裝置。 裝置更新服務會使用IoT隨插即用介面來回傳送和接收裝置的屬性和訊息。 IoT 中樞的裝置更新需要IoT裝置實作下列介面和模型標識碼。
如需詳細資訊,請參閱:
- 瞭解 IoT即插即用裝置用戶端。
- 查看 裝置更新代理程序的實作方式。
裝置更新核心介面
DeviceUpdateCore 介面可用來將更新動作和元數據傳送至裝置,並從裝置接收更新狀態。 DeviceUpdateCore 介面會分割成兩個物件屬性。
實作此介面時,模型中的預期元件名稱為 “deviceUpdate”。 深入瞭解 Azure IoT 隨插即用元件。
代理程式中繼資料
裝置更新代理程式會使用代理程式元數據欄位,將資訊傳送至裝置更新服務。
| 名稱 | 圖式 | 方向 | 說明 | 範例 |
|---|---|---|---|---|
| 設備屬性 | 地圖 | 裝置到雲端 | 包含製造商、型號和其他裝置資訊的屬性集和。 | 如需詳細資訊,請參閱 裝置屬性 一節。 |
| 相容屬性名稱 (compatPropertyNames) | 字串 (逗號分隔) | 裝置到雲端 | 裝置回報的屬性用於檢查裝置與更新部署目標的相容性。 最多限制五個裝置屬性。 | “compatPropertyNames”: “製造商,型號” |
| 最後安裝結果 | 地圖 | 裝置到雲端 | 代理所報告的結果。 其中包含主要更新和其他步驟更新的結果程式代碼、擴充結果碼和結果詳細數據。 | |
| 結果代碼 | 整數 | 裝置到雲端 | 包含上次更新動作結果相關資訊的程式碼。 可以填入成功或失敗。 | 700 |
| 擴展結果代碼 | 整數 | 裝置到雲端 | 包含結果的其他信息的程序代碼。 成功或失敗皆可填入。 | 0x80004005 |
| 結果詳情 | 字串 | 裝置到雲端 | 客戶定義的自由格式字串,以提供其他結果詳細數據。 返回至雙胞胎而不進行解析 | |
| stepResults | 地圖 | 裝置到雲端 | 代理程式回報的結果,其中包含結果碼、擴充的結果碼,以及步驟更新的結果詳細數據。 | “step_1”: { “resultCode”: 0,“extendedResultCode”: 0, “resultDetails”: “”} |
| 狀態 | 整數 | 裝置到雲端 | 表示裝置更新代理程式目前狀態的整數。 | 如需詳細資訊,請參閱 狀態 一節。 |
| 工作流程 | 複雜 | 裝置到雲端 | 一組值,指出代理程式目前正在處理的部署、目前部署的識別碼,以及對從服務傳送至代理程式的任何重試要求的認可。 | “workflow”: {“action”: 3,“ID”: “11b6a7c3-6956-4b33-b5a9-87fdd79d2f01”,“retryTimestamp”: “2022-01-26T11:33:29.9680598Z”} |
| 已安裝更新ID | 字串 | 裝置到雲端 | 目前安裝的更新標識碼(透過裝置更新)。 此值是一個字串,用於捕捉更新標識碼 JSON;如果裝置從未透過裝置更新接收過更新,則為 Null。 | installedUpdateID{“provider”:“contoso”,“name”:“image-update”,“version”:“1.0.0”}” |
裝置屬性
deviceProperties 欄位包含裝置的製造商和型號資訊。
| 名稱 | 圖式 | 方向 | 說明 |
|---|---|---|---|
| 製造商 | 字串 | 裝置到雲端 | 裝置製造商透過 deviceProperties 回報。 此屬性會從兩個位置的其中一個讀取 - 首先,DeviceUpdateCore 介面會嘗試從 組態檔讀取 'aduc_manufacturer' 值。 如果未在組態檔中填入此值,預設會報告ADUC_DEVICEPROPERTIES_MANUFACTURER的編譯時間定義。 此屬性僅於開機時報告。 默認值:『Contoso』。 |
| 模型 | 字串 | 裝置到雲端 | 裝置的型號,通過 deviceProperties 回報。 此屬性會從兩個位置的其中一個讀取 - 首先,DeviceUpdateCore 介面會嘗試從 組態檔讀取 'aduc_model' 值。 如果未在組態檔中填入此值,預設會報告ADUC_DEVICEPROPERTIES_MODEL的編譯時間定義。 此屬性僅於開機時報告。 預設值為:'Video' |
| 介面ID | 字串 | 裝置到雲端 | 服務會使用這個屬性來識別裝置更新代理程式所使用的介面版本。 裝置更新服務需要介面標識碼,才能管理及與代理程序通訊。 默認值:'dtmi:azure:iot:deviceUpdate;1' 適用於使用 DU 代理程式 0.8.0 版的裝置。 |
| aduVer | 字串 | 裝置到雲端 | 裝置上執行的裝置更新代理程式版本。 只有在編譯期間ENABLE_ADU_TELEMETRY_REPORTING設定為 1 (true) 時,才會從組建讀取此值。 客戶可以選擇不參加版本報告,方法是將值設定為 0(代表 false)。 如何自定義裝置更新代理程序屬性。 |
| doVer | 字串 | 裝置到雲端 | 在裝置上執行的傳遞最佳化代理程式版本。 只有在編譯期間ENABLE_ADU_TELEMETRY_REPORTING設定為 1(true)時,才會從組建讀取值。 客戶可以選擇將值設定為 0 以停用版本報告功能。 如何自定義傳遞優化代理程序屬性。 |
| 自定義相容性屬性 | 用戶定義 | 裝置到雲端 | 實作者可以在以更新部署為目標時,定義要用於相容性檢查的其他裝置屬性。 |
IoT 中樞裝置孿生範例:
"deviceUpdate": {
"__t": "c",
"agent": {
"deviceProperties": {
"manufacturer": "contoso",
"model": "virtual-vacuum-v1",
"interfaceId": "dtmi:azure:iot:deviceUpdateModel;1",
"aduVer": "DU;agent/0.8.0-rc1-public-preview",
"doVer": "DU;lib/v0.6.0+20211001.174458.c8c4051,DU;agent/v0.6.0+20211001.174418.c8c4051"
},
"compatPropertyNames": "manufacturer,model",
"lastInstallResult": {
"resultCode": 700,
"extendedResultCode": 0,
"resultDetails": "",
"stepResults": {
"step_0": {
"resultCode": 700,
"extendedResultCode": 0,
"resultDetails": ""
}
}
},
"state": 0,
"workflow": {
"action": 3,
"id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
"retryTimestamp": "2022-01-26T11:33:29.9680598Z"
},
"installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
},
備註
裝置或模組必須新增 {"__t": "c"} 標記,以指出參考元件的元素。 如需詳細資訊,請參閱 IoT 隨插即用慣例。
國家
[ 狀態 ] 字段是裝置更新 (DU) 代理程式從裝置更新服務收到動作之後所報告的狀態。 狀態會因應動作(詳細內容請參閱動作章節)而回報,這些動作是從裝置更新服務傳送至裝置更新代理程式的。 如需裝置更新服務與裝置更新代理程式之間流動之要求的詳細資訊,請參閱 概觀工作流程。
| 名稱 | 價值 | 說明 |
|---|---|---|
| 閒置 | 0 | 裝置已準備好從裝置更新服務接收動作。 成功更新之後,狀態會傳回至 Idle 狀態。 |
| 部署進行中 | 6 | 正在進行部署。 |
| 失敗 | 255 | 更新期間發生失敗。 |
| 下載成功 | 2 | 成功下載。 只有代理程式 0.7.0 版或更新版本的裝置才會報告此狀態。 |
| 安裝成功 | 4 | 成功安裝。 只有代理程式 0.7.0 版或更新版本的裝置才會報告此狀態。 |
服務元數據
服務元數據包含裝置更新服務用來將動作和數據傳達給裝置更新代理程式的欄位。
| 名稱 | 圖式 | 方向 | 說明 |
|---|---|---|---|
| 行為 | 整數 | 雲端到裝置 | 對應至代理程式應執行之動作的整數。 如需詳細資訊,請參閱 動作 一節。 |
| 更新清單 | 字串 | 雲端到裝置 | 用來描述更新的內容。 已從匯入資訊清單產生。 |
| 更新清單簽章 | JSON 物件 | 雲端到裝置 | JSON Web 簽章 (JWS) 與用於來源驗證的 JSON Web 金鑰。 |
| 檔案網址 | 地圖 | 雲端到裝置 |
FileID 到 DownloadUrl 的地圖。 告知代理程式要下載哪些檔案,以及用來驗證檔案是否已正確下載的哈希。 |
行動
[動作] 欄位代表裝置更新代理程式依照裝置更新服務指示所採取的動作。 裝置更新代理程式會報告處理所接收動作 的狀態 。 如需裝置更新服務與裝置更新代理程式之間流動之要求的詳細資訊,請參閱 概觀工作流程。
| 名稱 | 價值 | 說明 |
|---|---|---|
| 套用部署 | 3 | 套用更新。 它會向裝置發出訊號以套用已部署的更新 |
| 取消 | 255 | 停止處理目前的動作並返回 Idle,或告訴處於 Failed 狀態的代理程式返回 Idle。 |
| 下載 | 0 | 下載已發佈的內容或更新,以及所需的任何其他內容。 此動作只會傳送至代理程式0.7.0版或更新版本的裝置。 |
| 安裝 | 1 | 安裝內容或更新。 此動作通常表示呼叫內容或更新的安裝程式。 此動作只會傳送至代理程式0.7.0版或更新版本的裝置。 |
| 套用 | 2 | 完成更新。 它會視需要向系統發出重新啟動的訊號。 此動作只會傳送至代理程式0.7.0版或更新版本的裝置。 |
裝置資訊介面
裝置資訊介面是 IoT 隨插即用架構中使用的概念。 它包含裝置到雲端屬性,可提供裝置硬體和作系統的相關信息。 IoT 中樞的裝置更新會使用 DeviceInformation.manufacturer 和 DeviceInformation.model 屬性進行遙測和診斷。 若要深入瞭解,請參閱此 裝置資訊介面範例。
實作此介面時,模型中的預期元件名稱為 deviceInformation 。 瞭解 Azure IoT 隨插即用元件
| 名稱 | 類型 | 圖式 | 方向 | 說明 | 範例 |
|---|---|---|---|---|---|
| 製造商 | 財產 | 字串 | 裝置到雲端 | 裝置製造商的公司名稱。 此屬性可能與原始設備製造商 (OEM) 的名稱相同。 | Contoso |
| 模型 | 財產 | 字串 | 裝置到雲端 | 裝置型號名稱或識別碼。 | IoT Edge 裝置 |
| 軟體版本 | 財產 | 字串 | 裝置到雲端 | 裝置上的軟體版本。 swVersion 可能指的是您的韌體版本。 | 4.15.0-122 |
| 作業系統名稱 | 財產 | 字串 | 裝置到雲端 | 裝置的作業系統名稱。 | Ubuntu Server 18.04 |
| 處理器架構 | 財產 | 字串 | 裝置到雲端 | 裝置上處理器的架構。 | ARM64 |
| 處理器製造商 | 財產 | 字串 | 裝置到雲端 | 裝置上處理器製造商的名稱。 | Microsoft |
| 總儲存空間 | 財產 | 字串 | 裝置到雲端 | 裝置上可用的儲存體總量,以 KB 為單位。 | 2048 |
| 總記憶體 | 財產 | 字串 | 裝置到雲端 | 裝置上可用的記憶體總量,以 KB 為單位。 | 256 |
型號編號
模型標識符是智慧裝置如何使用 IoT 隨插即用向 Azure IoT 應用程式公告其功能。若要深入瞭解如何建置智慧裝置以向 Azure IoT 應用程式公告其功能,請造訪 IoT 隨插即用裝置開發人員指南。
IoT 中樞的裝置更新需要 IoT 隨插即用智慧裝置,該裝置必須在裝置連線中宣告模型識別碼,並且其值為 「dtmi:azure:iot:deviceUpdateModel;1」。 瞭解如何宣告模型標識碼。