IoT プラグ アンド プレイ デジタル ツインについて

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

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

この記事の IoT プラグ アンド プレイ デバイスの例では、サーモスタット コンポーネントを含む Temperature Controller モデルを実装しています。

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

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

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

デジタル ツイン 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 オブジェクトのフィールドについて説明します。

プロパティ

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

読み取り専用プロパティ

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 内で設定されます。 デバイスがオンラインになると、この更新プログラムを適用し、更新された値を報告できます。

Components

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

デバイス ツインでは、 { "__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"
}
}
}

デジタルツインAPI

デジタル ツイン API には、 デジタル ツインの取得、 デジタル ツインの更新、 コンポーネント コマンドの呼び出 し、デジタル ツインを管理するための コマンドの呼び出 し操作が含まれます。 REST API は、直接使用することも、いずれかのサービス SDK を介して使用することもできます。

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

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

デバイスおよびデジタル ツイン イベントのルーティングを有効にする方法については、「 IoT Hub メッセージ ルーティングを使用してデバイスからクラウドへのメッセージをさまざまなエンドポイントに送信する」を参照してください。 メッセージ形式を理解するには、「 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
  }
]