シナリオ: ゲートウェイを使用した間接接続デバイスのデジタル・ツインの作成

IoTドメインに各デジタル・ツイン・モデルを作成するには、oci iot digital-twin-model createコマンドを使用します。

ゲートウェイ・モデルの作成

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://gateway-model.json

HVACモデルの作成

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://hvac-model.json

ボイラー・モデルの作成

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://boiler-model.json

この例では、これらのスニペットをgateway-model.json、hvac-model.jsonおよびboiler-model.jsonというモデル・ファイルに保存します。

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:gateway;1",
  "@type": "Interface",
  "displayName": "Gateway",
  "description": "A digital twin model for Gateway",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "cpuUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "memoryUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "storageUtilization",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "firmwareVersion",
      "schema": "string"
    }
  ]
}

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:boiler;1",
  "@type": "Interface",
  "displayName": "Boiler",
  "description": "A digital twin model for Boiler",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "pressure",
      "schema": "integer"
    }
  ]
}

CreateDigitalTwinModel操作を実行して、IoTドメインにデジタル・ツイン・モデルを作成します。

APIをコールするときは、サンプル・デジタル・ツイン・モデル・ファイルに示されているものと同じDTDLペイロードを使用します。

IoTドメインに各アダプタを作成するには、oci iot digital-twin-adapter createコマンドを使用します。

ゲートウェイ・アダプタの作成

このコマンドを使用して、デジタル・ツイン・アダプタを作成します。この例では、DTMIを使用してデジタル・ツイン・モデルを関連付ける方法と、.jsonファイルを使用してエンベロープおよびルートを定義する方法を示します。

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:gateway;1" \
  --inbound-envelope file://gateway-envelope.json \
  --inbound-routes file://gateway-routes.json

{
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "cpuUtil": 0,
      "memUtil": 0,
      "diskUtil": 0,
      "firmware": "Oracle Linux 9.1"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time",
    "target": "${if ([\"boilers\", \"hvacs\", \"dehumidifiers\"] | contains([endpoint(1)])) then endpoint(2) else null end}",
    "contentRoot": "$"
  }
}

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.cpuUtilization": "$.cpuUtil",
      "$.memoryUtilization": "$.memUtil",
      "$.storageUtilization": "$.diskUtil",
      "$.firmwareVersion": "$.firmware"
    }
  }
]

HVACアダプタを作成します

このコマンドを使用して、デジタル・ツイン・アダプタを作成します。この例では、DTMIを使用してデジタル・ツイン・モデルを関連付ける方法と、.jsonファイルを使用してエンベロープおよびルートを定義する方法を示します。

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1" \
  --inbound-envelope file://hvac-envelope.json \
  --inbound-routes file://hvac-routes.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temperature": 0,
      "humidity": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.humidity": "$.humidity"
    }
  }
]

ボイラー・アダプタの作成

このコマンドを使用して、デジタル・ツイン・アダプタを作成します。この例では、DTMIを使用してデジタル・ツイン・モデルを関連付ける方法と、.jsonファイルを使用してエンベロープおよびルートを定義する方法を示します。

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:boiler;1" \
  --inbound-envelope file://boiler-envelope.json \
  --inbound-routes file://boiler-routes.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "timestamp": 1773768299143534,
      "temperature": 0,
      "pressure": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.timestamp"
  }
}

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.pressure": "$.pressure"
    }
  }
]

CLIからのファイルの参照の詳細は、「複雑な入力のためのJSONファイルの使用」を参照してください。

CreateDigitalTwinAdapter操作を実行して、IoTドメインにデジタル・ツイン・アダプタを作成します。

サンプル・ファイルに示されているものと同じインバウンド・エンベロープおよびインバウンド・ルート・ペイロードを使用します。

oci iot digital-twin-instance createコマンドを使用して、ゲートウェイおよび直接接続および間接接続されたデバイス・インスタンスを作成します。

直接接続されたHVACインスタンスの作成

このコマンドを使用して、外部キーhvac1を使用して、特定のIoTドメインに関連付けられ、直接接続されるデジタル・ツイン・インスタンスを作成します。

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type DIRECT \
  --display-name "LG HVAC 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <hvac-adapter-OCID> \
  --external-key hvac1

ゲートウェイ・インスタンスの作成

このコマンドを使用して、特定のIoTドメインに関連付けられたデジタル・ツイン・インスタンスを作成し、必要な--connectivity-typeパラメータをGATEWAY値とともに使用して、ゲートウェイであるデジタル・ツイン・インスタンスを作成します。外部キーはgateway1.です。

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type GATEWAY \
  --display-name "Bosch Gateway 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <gateway-adapter-OCID> \
  --external-key gateway1

間接的に接続されたHVACインスタンスの作成

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "LG HVAC 2" \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <hvac-adapter-OCID> \
  --external-key hvac2

間接的に接続されたボイラー・インスタンスの作成

このコマンドおよび必須パラメータ--connectivity-type INDIRECTを使用して、間接的に接続されたデバイスであるデジタル・ツインを作成します。

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "GE Boiler 1" \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <boiler-adapter-OCID> \
  --external-key boiler1

間接的に接続された除湿器インスタンスの作成

このコマンドおよび必須パラメータ--connectivity-type INDIRECTを使用して、間接的に接続されたデバイスであるデジタル・ツインを作成します。

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name Danby Dehumidifier 1 \
  --gateways '["<gateway-instance-OCID>"]' \
  --external-key dehumidifier1

CreateDigitalTwinInstance操作を実行して、ゲートウェイ・インスタンス、直接接続されたインスタンスおよび間接的に接続されたインスタンスを作成します。

間接的に接続されたインスタンスを作成する場合は、リクエストにゲートウェイ・アソシエーションが含まれていることを確認してください。

curlを使用して、HTTPS経由でテレメトリを送信します。これらの例では、デジタル・ツイン・インスタンスの外部キーおよびプレーン・テキストのシークレット・コンテンツとともにHTTP Basic認証を使用します。

1. ユーザー名としてデジタル・ツイン・インスタンスの外部キーを使用します。たとえば、直接接続されたテレメトリの場合は、インスタンスの外部キー(hvac1など)を使用します。
2. プレーン・テキストのシークレット・コンテンツをパスワードとして使用します。
3. リクエストをhttps://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/<endpoint-path>に送信します。
4. 間接的に接続されたデバイスの場合は、ゲートウェイ・インスタンスとして認証し、エンドポイント・パスを使用してターゲット・デバイス(hvacs/hvac2やboilers/boiler1など)を識別します。

直接接続されたHVACインスタンスからテレメトリを送信:

curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temperature": 70,
    "humidity": 60
  }'

ゲートウェイ・インスタンスからのテレメトリの送信:

curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
  "cpuUtil": 30,
  "memUtil": 25,
  "diskUtil": 20,
  "firmware": "Oracle Linux 9.1"
}'

ゲートウェイを介して間接的に接続されたHVACインスタンスのテレメトリを送信します:

curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/hvacs/hvac2" \
  -d '{
    "temperature": 75,
    "humidity": 65
  }'

ゲートウェイを介して間接的に接続されたボイラー・インスタンスのテレメトリを送信します:

curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/boilers/boiler1" \
  -d '{
    "temperature": 80,
    "pressure": 90
  }'

ゲートウェイを介して間接的に接続された除湿器インスタンスの遠隔測定を送信します:

curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: text/plain" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/dehumidifiers/dehumidifier1" \
  -d 'humidity=50,fanSpeed=medium'

oci iot digital-twin-instance invoke-raw-json-commandコマンドを使用して、このシナリオのアクション例を呼び出します。詳細は、デジタル・ツイン・インスタンスからのRAWコマンドの送信を参照してください。

ゲートウェイ・インスタンスを再起動します。

oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <bosch-gateway-1-OCID> \
  --request-endpoint "actions/reboot" \
  --request-data '{"force": true}'

間接的に接続されたボイラー・インスタンスのリセット

この例では、boilers/boiler1/actions/resetの--request-endpointを指定します。

この例では、boilers/boiler1/actions/responseの--response-endpointを指定します。

レスポンスが必要な場合、--response-durationパラメータを含める必要があります。そうでない場合、コマンドはレスポンスを受信せずにCOMPLETED状態に遷移します。その結果、コマンドのレスポンスはRAW_COMMAND_DATAデータベース表には取得されません。

oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <ge-boiler-1-OCID> \
  --request-endpoint "boilers/boiler1/actions/reset" \
  --request-data '{"hardReset": false}' \
  --response-endpoint "boilers/boiler1/actions/response" \
  --response-duration PT10M

ボイラー・レスポンスの公開

Use the response endpoint to publish the boiler response to this endpoint: boilers/boiler1/actions/response in this example gateway1 is the external key and the device username.

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t "boilers/boiler1/actions/response" \
  -m '{
    "status": "OK"
  }' \
  -u gateway1 \
  -P '<secret-contents>'

間接的に接続された除湿ファンをオフにする

このコマンドを使用して、除湿器のファンをシャットダウンするデバイスでraw JSONコマンドを呼び出します。

oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <danby-dehumidifier-1-OCID> \
  --request-endpoint "dehumidifiers/dehumidifier1/actions/fanOff" \
  --request-data '{"fanOff": true}'

InvokeRawCommand操作を実行して、デバイスでRAWコマンドを起動します。

レスポンス・エンドポイントは、コマンドがアプリケーション・レベルの確認を返す場合に使用します。