IoT Hub 用のデバイス更新と IoT プラグ アンド プレイ
IoT Hub 用のデバイス更新では、無線更新対応のデバイスを検出して管理するために、IoT プラグ アンド プレイが使用されます。 デバイス更新サービスにより、IoT プラグ アンド プレイ インターフェイスを使用して、デバイスとの間でプロパティとメッセージが送受信されます。
詳細情報:
- IoT プラグ アンド プレイ デバイス クライアントについて理解します。
- デバイス更新エージェントの実装方法を確認します。
Device Update モデル
モデル ID は、IoT プラグ アンド プレイによってスマート デバイスから Azure IoT アプリケーションに機能が公開される方法です。Azure IoT アプリケーションに機能を公開するようにスマート デバイスを構築する方法の詳細については、「IoT プラグ アンド プレイ デバイス開発者ガイド」をご覧ください。
Device Update for IoT Hub で、デバイス接続の一部としてモデル ID を通知するには、IoT Plug and Play スマート デバイスが必要です。 モデル ID を通知する方法を確認する.
Device Update には、DU 機能をサポートするいくつかの PnP モデルが定義されています。 Device Update モデル 'dtmi:azure:iot:deviceUpdateContractModel;3' はコア機能をサポートし、デバイス更新のコア インターフェイスを使用して更新アクションとメタデータをデバイスに送信し、デバイスから更新状態を受信します。
サポートされているもう 1 つのモデルは dtmi:azure:iot:deviceUpdateModel;3 です。これは、deviceUpdateContractModel;3 を拡張し、デバイスのプロパティと情報の送信と、診断機能の有効化を実行する他の PnP インターフェイスも使用します。 [Device Update モデルとインターフェイスのバージョン](https://github.com/Azure/iot-plugandplay-models/tree/main/dtmi/azure/iot) の詳細を確認してください。
Device Update エージェントは、1.1.0 リリースのすべての最新機能をサポートする dtmi:azure:iot:deviceUpdateModel;3 を使用します。 このモデルでは、V5 マニフェスト バージョンがサポートされています。古いマニフェストは最新のエージェントで動作しますが、新機能では最新のマニフェスト バージョンを使用する必要があります。
エージェント メタデータ
デバイス更新エージェントではエージェント メタデータ フィールドを使用して、デバイス更新サービスに情報が送信されます。
| 名前 | スキーマ | Direction | 説明 | 例 |
|---|---|---|---|---|
| deviceProperties | マップ | デバイスからクラウド | 製造元、モデル、その他のデバイス情報が含まれるプロパティのセット。 | 詳細については、「デバイスのプロパティ」セクションを参照してください。 |
| compatPropertyNames | 文字列 (コンマ区切り) | デバイスからクラウド | 更新プログラムの展開を対象とするデバイスの互換性を確認するために使用される、デバイスから報告されたプロパティ。 5 つのデバイス プロパティに制限されています。 | "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | マップ | デバイスからクラウド | エージェントによって報告された結果。 これには結果コード、拡張結果コード、およびメインの更新と他のステップ更新の結果の詳細が含まれています。 | |
| resultCode | 整数 (integer) | デバイスからクラウド | 前回の更新操作の結果に関する情報が含まれているコード。 成功または失敗のいずれでも設定できます。 | 700 |
| extendedResultCode | 整数 (integer) | デバイスからクラウド | 結果に関する追加情報が含まれているコード。 成功または失敗のいずれでも設定できます。 | 0x80004005 |
| resultDetails | string | デバイスからクラウド | 追加の結果の詳細を提供するための顧客が定義した自由形式の文字列。 解析せずにツインに返されます | |
| stepResults | map | デバイスからクラウド | 結果コード、拡張結果コード、およびステップ更新のための結果の詳細を含む、エージェントによって報告された結果。 | "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| state | 整数 (integer) | デバイスからクラウド | デバイス更新エージェントの現在の状態を示す整数。 | 詳細については、「state」セクションをご覧ください。 |
| workflow | 複雑 | デバイスからクラウド | エージェントが現在動作しているデプロイ、現在のデプロイの ID、およびサービスからエージェントに送信された再試行要求の受信確認を示す値のセットです。 デプロイが取り消されると、ワークフロー ID によって "nodeployment" の値が報告されることに注意してください。 | "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| installedUpdateId | string | デバイスからクラウド | 現在 (デバイス更新を通じて) インストールされている更新プログラムの ID。 デバイス更新によって更新が行われたことのないデバイスの場合、この値は更新 ID の JSON をキャプチャした文字列または null になります。 | installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}" |
デバイスのプロパティ
deviceProperties フィールドには、デバイスの製造元とモデルの情報が含まれています。
| 名前 | スキーマ | Direction | 説明 |
|---|---|---|---|
| manufacturer | string | デバイスからクラウド | deviceProperties によって報告されたデバイスの製造元。 このプロパティは、2 つの場所のいずれかから読み取られます。最初に DeviceUpdateCore インターフェイスによって、構成ファイルから "aduc_manufacturer" 値の読み取りが試みられます。 値が構成ファイルに設定されていない場合、ADUC_DEVICEPROPERTIES_MANUFACTURER のコンパイル時の定義が既定で報告されます。 このプロパティは、起動時にのみ報告されます。 既定値: 'Contoso'。 |
| model | string | デバイスからクラウド | deviceProperties によって報告されたデバイスのデバイス モデル。 このプロパティは、2 つの場所のいずれかから読み取られます。最初に DeviceUpdateCore インターフェイスによって、構成ファイルから "aduc_model" 値の読み取りが試みられます。 値が構成ファイルに設定されていない場合、ADUC_DEVICEPROPERTIES_MODEL のコンパイル時の定義が既定で報告されます。 このプロパティは、起動時にのみ報告されます。 既定値: 'Video' |
| contractModelId | string | デバイスからクラウド | このプロパティは、エージェントの管理と通信のために Device Update エージェントによって使用されている基本モデルのバージョンを識別するために、サービスによって使用されます。 値: DU エージェント バージョン 1.1.0 を使用するデバイスの場合、"dtmi:azure:iot:deviceUpdateContractModel;3"。 注: 'dtmi:azure:iot:deviceUpdateModel;2' を使用するエージェントは、contractModelId を 'dtmi:azure:iot:deviceUpdateContractModel;3' と報告する必要があります。deviceUpdateModel;3 は deviceUpdateModel;3 から拡張されるためです |
| aduVer | string | デバイスからクラウド | デバイスで実行されているデバイス更新エージェントのバージョン。 この値は、コンパイル時に ENABLE_ADU_TELEMETRY_REPORTING が 1 (true) に設定されている場合にのみ、ビルドから読み取られます。 お客様は、値を 0 (false) に設定することにより、バージョンの報告をオプトアウトすることができます。 デバイス更新エージェントのプロパティをカスタマイズする方法。 |
| doVer | string | デバイスからクラウド | デバイスで実行されている配信最適化エージェントのバージョン。 この値は、コンパイル時に ENABLE_ADU_TELEMETRY_REPORTING が 1 (true) に設定されている場合にのみ、ビルドから読み取られます。 お客様は、値を 0 (false) に設定することにより、バージョンの報告をオプトアウトすることができます。 配信の最適化エージェントのプロパティをカスタマイズする方法。 |
| カスタム互換性プロパティ | User Defined | デバイスからクラウド | 実装者は、更新プログラムの展開をターゲットとしながら、互換性チェックに使用される、他のデバイス プロパティを定義できます。 |
IoT Hub デバイス ツインのサンプル:
"deviceUpdate": {
"__t": "c",
"agent": {
"deviceProperties": {
"manufacturer": "contoso",
"model": "virtual-vacuum-v1",
"contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;3",
"aduVer": "DU;agent/1.1.0",
},
"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\"}"
},
Note
この要素からコンポーネントを参照していることを示すために、デバイスまたはモジュールは {"__t": "c"} マーカーを追加する必要があります。 詳細については、「IoT プラグ アンド プレイ規則」を参照してください。
State
state (状態) フィールドは、デバイス更新サービスからアクションを受け取った後に、デバイス更新 (DU) エージェントによって報告された状態です。 state は、 デバイス更新サービスからデバイス更新エージェントに送信された action (action セクションを参照) への応答で報告されます。 デバイス更新サービスとデバイス更新エージェントの間でやり取りされる要求については、ワークフローの概要に関する記事をご覧ください。
| 名前 | 値 | 説明 |
|---|---|---|
| アイドル | 0 | デバイスは、デバイス更新サービスからアクションを受け取る準備ができています。 更新が成功すると、状態は Idle に戻ります。 |
| DeploymentInprogress | 6 | デプロイが進行中です。 |
| 失敗 | 255 | 更新の間にエラーが発生しました。 |
| DownloadSucceeded | 2 | ダウンロード成功。 この状態は、エージェント バージョン 0.7.0 以前のデバイスによってのみ報告されます。 |
| InstallSucceeded | 4 | インストール成功。 この状態は、エージェント バージョン 0.7.0 以前のデバイスによってのみ報告されます。 |
サービス メタデータ
サービス メタデータには、デバイス更新サービスによってアクションとデータをデバイス更新エージェントに伝えるために使用されるフィールドが含まれています。
| 名前 | スキーマ | Direction | 説明 |
|---|---|---|---|
| action | 整数 (integer) | クラウドからデバイス | エージェントが実行する必要のあるアクションに対応する整数。 詳細については、「action」セクションを参照してください。 |
| updateManifest | string | クラウドからデバイス | 更新の内容を記述するために使用されます。 インポート マニフェストから生成されます。 |
| updateManifestSignature | JSON オブジェクト | クラウドからデバイス | ソースの検証に使用される JSON Web Signature (JWS) と JSON Web キー。 |
| fileUrls | マップ | クラウドからデバイス | DownloadUrl への FileID のマップ。 ダウンロードするファイルと、ファイルが正しくダウンロードされたことを検証するために使用するハッシュを、エージェントに指示します。 |
アクション
action (アクション) フィールドは、デバイス更新サービスによって指示されてデバイス更新エージェントによって実行されるアクションを表します。 デバイス更新エージェントは、受信したアクションを処理するための状態を報告します。 デバイス更新サービスとデバイス更新エージェントの間でやり取りされる要求については、ワークフローの概要に関する記事をご覧ください。
| 名前 | 値 | 説明 |
|---|---|---|
| applyDeployment | 3 | 更新プログラムを適用します。 デプロイされた更新プログラムを適用するシグナルをデバイスに送信します |
| cancel | 255 | 現在のアクションの処理を停止して Idle に戻るか、Failed 状態のエージェントに Idle に戻るように指示します。 |
| download | 0 | 発行されたコンテンツまたは更新プログラム、および必要なその他のコンテンツをダウンロードします。 このアクションは、エージェント バージョン 0.7.0 以前のデバイスにのみ送信されます。 |
| インストール | 1 | コンテンツまたは更新プログラムをインストールします。 通常、このアクションは、コンテンツまたは更新プログラムのインストーラーの呼び出しを意味します。 このアクションは、エージェント バージョン 0.7.0 以前のデバイスにのみ送信されます。 |
| apply | 2 | 更新を完了します。 必要な場合は、システムに再起動が通知されます。 このアクションは、エージェント バージョン 0.7.0 以前のデバイスにのみ送信されます。 |
デバイス情報インターフェイス
デバイス情報インターフェイスは、IoT プラグ アンド プレイ アーキテクチャで使用される概念です。 デバイスのハードウェアとオペレーティング システムに関する情報を提供する、デバイスからクラウドへのプロパティが含まれています。 IoT Hub 用のデバイス更新では、テレメトリと診断のための DeviceInformation.manufacturer および DeviceInformation.model プロパティが使用されます。 詳細については、デバイス情報インターフェイスのこちらの例をご覧ください。
このインターフェイスが実装される場合、モデルで予想されるコンポーネント名は deviceInformation です。 Azure IoT プラグ アンド プレイ コンポーネントについての詳細情報
| Name | 種類 | スキーマ | Direction | 説明 | 例 |
|---|---|---|---|---|---|
| manufacturer | プロパティ | string | デバイスからクラウド | デバイスの製造元の会社名。 このプロパティは、OEM (相手先ブランド供給) の名前と同じにすることができます。 | Contoso |
| model | プロパティ | string | デバイスからクラウド | デバイス モデルの名前または ID。 | IoT Edge デバイス |
| swVersion | プロパティ | string | デバイスからクラウド | デバイス上のソフトウェアのバージョン。 swVersion は、ファームウェアのバージョンである場合があります。 | 4.15.0-122 |
| osName | プロパティ | string | デバイスからクラウド | デバイス上のオペレーティング システムの名前。 | Ubuntu Server 18.04 |
| processorArchitecture | プロパティ | string | デバイスからクラウド | デバイスのプロセッサのアーキテクチャ。 | ARM64 |
| processorManufacturer | プロパティ | string | デバイスからクラウド | デバイスのプロセッサの製造元の名前。 | Microsoft |
| totalStorage | プロパティ | string | デバイスからクラウド | デバイスで使用可能な記憶域の合計 (キロバイト単位)。 | 2048 |
| totalMemory | プロパティ | string | デバイスからクラウド | デバイスで使用可能なメモリの合計 (キロバイト単位)。 | 256 |