IoT Hub 用のデバイス更新と IoT プラグアンドプレイ

[アーティクル]
03/04/2024

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

次の方法で共有

IoT Hub 用のデバイス更新と IoT プラグアンドプレイ

Device Update モデル

エージェントメタデータ

デバイスのプロパティ

State

サービスメタデータ

アクション

デバイス情報インターフェイス

次の手順

フィードバック

その他のリソース

次の方法で共有

IoT Hub 用のデバイス更新と IoT プラグ アンド プレイ

Device Update モデル

エージェント メタデータ

デバイスのプロパティ

State

サービス メタデータ

アクション

デバイス情報インターフェイス

次の手順

フィードバック

その他のリソース

IoT Hub 用のデバイス更新と IoT プラグアンドプレイ

エージェントメタデータ

サービスメタデータ