IoT プラグアンドプレイのデジタルツインを理解する

[アーティクル]
02/06/2024

IoT プラグアンドプレイデバイスは、Digital Twins Definition Language (DTDL) スキーマによって記述されたモデルを実装します。モデルは、特定のデバイスが持つことができるコンポーネント、プロパティ、コマンド、およびテレメトリメッセージのセットを表します。

Note

DTDL は、IoT プラグアンドプレイ専用ではありません。 Azure Digital Twins などの他の IoT サービスでは、これは建物やエネルギーネットワークなどの環境全体を表すために使用されています。

Azure IoT service SDK には、サービスがデバイスのデジタルツインを操作できるようにする API が含まれています。たとえば、サービスは、デジタルツインからデバイスのプロパティを読み取ったり、デジタルツインを使用してデバイスでコマンドを呼び出したりできます。詳細については、「IoT Hub デジタルツインの例」を参照してください。

この記事の例の IoT プラグアンドプレイデバイスには、Thermostat コンポーネントを含む Temperature Controller モデルが実装されています。

デバイスツインとデジタルツイン

デジタルツインに加えて、Azure IoT Hub では、接続されているすべてのデバイスに対して デバイスツイン が保持されます。デバイスツインは、デバイスのプロパティの表現であるという点で、デジタルツインに似ています。 IoT ハブは、IoT プラグアンドプレイデバイスが初めてプロビジョニングされるときに、デバイスツインとデジタルツインを初期化します。 Azure IoT service SDK には、デバイスツインを操作するための API が含まれています。

デバイスツインは、デバイスに関する情報 (メタデータ、構成、状態など) を格納する JSON ドキュメントです。詳細については、「IoT Hub サービスクライアントの例」を参照してください。デバイスビルダーとソリューションビルダーは、どちらも同じ Device Twin API と SDK のセットを使用して、IoT プラグアンドプレイ規則を用いてデバイスとソリューションを実装できます。デバイスツインでは、書き込み可能なプロパティの状態は、"desired プロパティ" と "reported プロパティ" のセクションに分割されます。すべての読み取り専用プロパティは、reported プロパティセクション内で使用できます。

デジタルツイン API は、コンポーネント、プロパティ、コマンドなどのハイレベルな DTDL コンストラクトで動作し、ソリューションビルダーが IoT プラグアンドプレイソリューションを容易に作成できるようにします。デジタルツインには、プロパティの現在の状態と目的の状態を示す統合ビューがあります。特定のプロパティの同期状態は、対応する既定のコンポーネント $metadata セクションに格納されます。

デバイスツインの JSON の例

次のスニペットは、JSON オブジェクトとして書式設定された IoT プラグアンドプレイデバイスツインを示しています。

{
  "deviceId": "sample-device",
  "modelId": "dtmi:com:example:TemperatureController;1",
  "version": 15,
  "properties": {
    "desired": {
      "thermostat1": {
        "__t": "c",
        "targetTemperature": 21.8
      },
      "$metadata": {...},
      "$version": 4
    },
    "reported": {
      "serialNumber": "alwinexlepaho8329",
      "thermostat1": {
        "maxTempSinceLastReboot": 25.3,
        "__t": "c",
        "targetTemperature": {
          "value": 21.8,
          "ac": 200,
          "ad": "Successfully executed patch",
        }
      },
      "$metadata": {...},
      "$version": 11
    }
  }
}

デジタルツインの例

次のスニペットは、JSON オブジェクトとして書式設定されたデジタルツインを示しています。

{
  "$dtId": "sample-device",
  "serialNumber": "alwinexlepaho8329",
  "thermostat1": {
    "maxTempSinceLastReboot": 25.3,
    "targetTemperature": 21.8,
    "$metadata": {
      "targetTemperature": {
        "desiredValue": 21.8,
        "desiredVersion": 4,
        "ackVersion": 4,
        "ackCode": 200,
        "ackDescription": "Successfully executed patch",
        "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
      },
      "maxTempSinceLastReboot": {
         "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:example:TemperatureController;1",
    "serialNumber": {
      "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
    }
  }
}

次の表では、デジタルツイン JSON オブジェクト内のフィールドについて説明します。

フィールド名	説明
`$dtId`	デバイスデジタルツインの ID を表すユーザー指定の文字列。
`{propertyName}`	JSON のプロパティの値。
`$metadata.$model`	[省略可能] このデジタルツインを特徴付けるモデルインターフェイスの ID。
`$metadata.{propertyName}.desiredValue`	[書き込み可能なプロパティ専用] 指定されたプロパティの目的の値。
`$metadata.{propertyName}.desiredVersion`	[書き込み可能なプロパティ専用] IoT Hub で管理される目的の値のバージョン。
`$metadata.{propertyName}.ackVersion`	[必須、書き込み可能なプロパティ専用] デジタルツインを実装しているデバイスによって確認されたバージョン。これは、目的のバージョン以上である必要があります。
`$metadata.{propertyName}.ackCode`	[必須、書き込み可能なプロパティ専用] デジタルツインを実装するデバイスアプリによって返される `ack` コード。
`$metadata.{propertyName}.ackDescription`	[省略可能、書き込み可能なプロパティ専用] デジタルツインを実装するデバイスアプリによって返される `ack` の説明。
`$metadata.{propertyName}.lastUpdateTime`	IoT Hub によって、デバイスによるプロパティの最後の更新のタイムスタンプが保持されます。タイムスタンプは UTC で、ISO8601 形式 (YYYY-MM-DDTHH:MM:SS.mmmZ) でエンコードされています。
`{componentName}`	コンポーネントのプロパティ値とメタデータを含む JSON オブジェクト。
`{componentName}.{propertyName}`	JSON でのコンポーネントのプロパティ値。
`{componentName}.$metadata`	コンポーネントのメタデータ情報。

プロパティ

プロパティは、多くのオブジェクト指向プログラミング言語のプロパティと同様に、エンティティの状態を表すデータフィールドです。

読み取り専用プロパティ

DTDL スキーマ:

{
    "@type": "Property",
    "name": "serialNumber",
    "displayName": "Serial Number",
    "description": "Serial number of the device.",
    "schema": "string"
}

この例では、alwinexlepaho8329 は、デバイスによって報告された serialNumber 読み取り専用プロパティの現在の値です。

次のスニペットは、serialNumber プロパティの JSON 表現を横に並べて示しています。

デバイスツイン

"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}

デジタルツイン

"serialNumber": "alwinexlepaho8329"

書き込み可能なプロパティ

次の例は、既定のコンポーネント内の書き込み可能なプロパティを示しています。

DTDL:

{
  "@type": "Property",
  "name": "fanSpeed",
  "displayName": "Fan Speed",
  "writable": true,
  "schema": "double"
}

デバイスツイン

{
"properties": {
"desired": {
"fanSpeed": 2.0,
},
"reported": {
"fanSpeed": {
"value": 3.0,
"ac": 200,
"av": 1,
"ad": "Successfully executed patch version 1"
}
}
},
}

デジタルツイン

{
"fanSpeed": 3.0,
"$metadata": {
"fanSpeed": {
"desiredValue": 2.0,
"desiredVersion": 2,
"ackVersion": 1,
"ackCode": 200,
"ackDescription": "Successfully executed patch version 1",
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

この例では、3.0 は、デバイスによって報告された fanSpeed プロパティの現在の値です。 2.0 は、ソリューションによって設定された目的の値です。ルートレベルプロパティの目的の値と同期状態は、デジタルツインのルートレベルの $metadata 内で設定されます。デバイスがオンラインになると、この更新が適用され、更新された値が報告されます。

コンポーネント

コンポーネントを使用すると、他のインターフェイスのアセンブリとしてモデルインターフェイスを作成できます。たとえば、Thermostat インターフェイスは、thermostat1 および thermostat2 コンポーネントとして Temperature Controller モデルに組み込むことができます。

デバイスツインでは、コンポーネントは { "__t": "c"} マーカーによって識別されます。デジタルツインでは、$metadata の存在によってコンポーネントがマークされます。

この例では、thermostat1 は 2 つのプロパティを持つコンポーネントです。

maxTempSinceLastReboot は読み取り専用プロパティです。
targetTemperature は、デバイスによって正常に同期された書き込み可能なプロパティです。これらのプロパティの目的の値と同期状態は、コンポーネントの $metadata にあります。

次のスニペットは、thermostat1 コンポーネントの JSON 表現を横に並べて示しています。

デバイスツイン

"properties": {
"desired": {
"thermostat1": {
"__t": "c",
"targetTemperature": 21.8
},
"$metadata": {
},
"$version": 4
},
"reported": {
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"__t": "c",
"targetTemperature": {
"value": 21.8,
"ac": 200,
"ad": "Successfully executed patch",
"av": 4
}
},
"$metadata": {
},
"$version": 11
}
}

デジタルツイン

"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 21.8,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.8,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

Digital Twin API

Digital Twin API には、Get Digital Twin、Update Digital Twin、Invoke Component Command、および Invoke Command の各操作が含まれ、デジタルツインをさらに管理できます。 REST API は、直接使用することも、いずれかのサービス SDK を介して使用することもできます。

デジタルツインの変更イベント

デジタルツインの変更イベントを有効にすると、コンポーネントまたはプロパティの現在の値または目的の値が変更されるたびにイベントがトリガーされます。デジタルツインの変更イベントは JSON Patch 形式で生成されます。ツイン変更イベントが有効になっている場合、対応するイベントがデバイスツイン形式で生成されます。

デバイスおよびデジタルツインイベントのルーティングを有効にする方法については、「IoT Hub メッセージルーティングを使用して device-to-cloud メッセージを別のエンドポイントに送信する」を参照してください。メッセージ形式の詳細については、「IoT Hub メッセージを作成し、読み取る」を参照してください。

たとえば、ソリューションによって targetTemperature が設定されると、次のようなデジタルツイン変更イベントがトリガーされます。

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:04 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d463fa034
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature",
    "value": {
      "desiredValue": 21.8,
      "desiredVersion": 4
    }
  }
]

次のデジタルツイン変更イベントは、上記の目的の変更が適用されたことがデバイスによって報告されたときにトリガーされます。

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:05 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d464a2c80
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackCode",
    "value": 200
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackDescription",
    "value": "Successfully executed patch"
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackVersion",
    "value": 4
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/lastUpdateTime",
    "value": "2020-07-17T06:11:04.9309159Z"
  },
  {
    "op": "add",
    "path": "/thermostat1/targetTemperature",
    "value": 21.8
  }
]

Note

ツイン変更通知メッセージは、デバイスとデジタルツインの両方の変更通知で有効になっている場合、二重になります。

次のステップ

ここまでで、デジタルツインについて学習しました。その他のリソースを次に示します。

次の方法で共有

IoT プラグアンドプレイのデジタルツインを理解する

デバイスツインとデジタルツイン

デバイスツインの JSON の例

デジタルツインの例

プロパティ

読み取り専用プロパティ

書き込み可能なプロパティ

コンポーネント

Digital Twin API

デジタルツインの変更イベント

次のステップ

フィードバック

その他のリソース

次の方法で共有

IoT プラグ アンド プレイのデジタル ツインを理解する

デバイス ツインとデジタル ツイン

デバイス ツインの JSON の例

デジタル ツインの例

プロパティ

読み取り専用プロパティ

書き込み可能なプロパティ

コンポーネント

Digital Twin API

デジタル ツインの変更イベント

次のステップ

フィードバック

その他のリソース

IoT プラグアンドプレイのデジタルツインを理解する

デバイスツインとデジタルツイン

デバイスツインの JSON の例

デジタルツインの例

デジタルツインの変更イベント