Oracle Cloud Infrastructureドキュメント

シナリオ: MQTTSを使用したコマンドの受信およびレスポンスの送信

このシナリオを使用して、クラウドから非構造化RAW JSONコマンドを受信し、MQTTSを介してデバイス・レスポンスを送信します。

このシナリオでは、非構造化RAW JSONコマンドのみがサポートされます。接続デバイスとしてMQTTSクライアントを使用し、Internet of Thingsプラットフォームからコマンドを起動し、デバイス・リクエスト・トピックでコマンドを受信し、レスポンス・トピックへのレスポンスを公開します。

ステップ1: デジタル・ツイン・インスタンスの作成または選択

デジタル・ツイン・モデルまたはデジタル・ツイン・アダプタを使用せずに、デジタル・ツイン・インスタンスを使用します。インスタンスは直接接続され、認証IDを持つ必要があります。インスタンスOCIDおよび外部キーを保存します。

  • デジタル・ツイン・モデルまたはデジタル・ツイン・アダプタを使用しない既存のデジタル・ツイン・インスタンスを選択します。インスタンスは直接接続されている必要があります。または、デジタル・ツイン・インスタンスの作成のコンソールの手順に従います。シークレットまたは証明書認証OCIDを選択または貼り付けます。

  • デジタル・ツイン・モデルまたはデジタル・ツイン・アダプタを使用せずにデジタル・ツイン・インスタンスを作成するには、oci iot digital-twin-instance createコマンドを使用します:

    oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --display-name <display-name> \
  --auth-id <secret-or-certificate-OCID>

  • CreateDigitalTwinInstance操作を実行して、デジタル・ツイン・モデルまたはデジタル・ツイン・アダプタを使用せずにデジタル・ツイン・インスタンスを作成するか、同じ構成の既存のインスタンスを取得します。インスタンスは直接接続され、認証IDを持つ必要があります。

ステップ2: ブローカ資格証明を使用したMQTTセッションの確立

この例では、MQTTXをMQTT 5とともに使用します。

  1. MQTTXをダウンロードして設定します。「MQTTXの開始」を参照してください。
  2. 接続を作成し、機密情報を含まない名前を入力します。
  3. デジタル・ツイン・インスタンスの外部キーを「ユーザー名」として入力します。
  4. デバイス資格証明を「パスワード」として入力します。ボールト・シークレットを使用したテストには、プレーン・テキスト・シークレット・コンテンツを使用します。
  5. 「ホスト」で、mqtts://を選択し、<domain-short-id>.device.iot.<region>.oci.oraclecloud.comと入力します。
  6. ポート8883を入力し、SSL/TLSを有効にして、CA署名サーバー証明書を選択します。
  7. 短い切断後にブローカがコマンド・サブスクリプションを再開できるように、永続MQTT 5セッションを構成します。
    • クライアントID: 安定したクライアントIDを入力し、クライアントが再接続するたびに再利用します。
    • 開始のクリーン: このオプションをオフにします。
    • セッション有効期限間隔: 予想される切断に十分な長さのゼロ以外の間隔(7200秒など)を設定します。
    • Last-Will-Retain: この設定は、Last Willメッセージが保持されるかどうかのみを制御し、サブスクリプションの永続性は制御しません。
  8. 切断通知を少なくとも1回配信するには、Last Will QoSを 1に設定します。
  9. 「接続」を選択します。

ステップ3: コマンド要求トピックへのサブスクライブ

コマンドのrequestEndpointは、デバイスがコマンドを受信するMQTTトピックになります。この例では、QoS 1で/endpoints/1234をサブスクライブします。

  1. MQTTXで、「+新規サブスクリプション」を選択します。
  2. 「トピック」に/endpoints/1234と入力します。
  3. 「QoS」メニューから「1回以上」を選択します。
  4. 「確認」を選択します。

コマンド・リクエスト・エンドポイントおよびQoS 1が表示されたMQTTX新規サブスクリプション・ダイアログ。

ステップ4: JSONファイルでのコマンドの定義

RAW JSONコマンドを起動するときに使用するコマンド詳細をJSONファイルに定義します。

このリクエストをcommand.jsonとして保存します:

{
  "requestEndpoint": "/endpoints/1234",
  "requestDuration": "PT3M",
  "requestDataFormat": "JSON",
  "requestData": {
    "temp": 33
  },
  "requestDataContentType": "application/json",
  "responseEndpoint": "/endpoints/4321",
  "responseDuration": "PT3M"
}
  • requestEndpointは、デバイスがコマンドの受信をサブスクライブするMQTTトピックです。コマンド・リクエスト・トピックにサブスクライブする場合も同じ値を使用します。
  • requestDurationは、プラットフォームがコマンドを配信できる期間です。ISO 8601期間形式を使用します。たとえば、PT3Mは3分です。
  • requestDataFormatは、リクエスト・データをJSONとして識別します。
  • requestDataは、デバイスに配信されるJSONペイロードです。
  • requestDataContentTypeはリクエスト・データのメディア・タイプです。
  • responseEndpointは、デバイスがレスポンスを公開するMQTTトピックです。/endpoints/<external-id>/responseなどの専用レスポンス・エンドポイントがある場合は、ここで使用します。このフィールドおよびデバイスがレスポンスを公開する場合は、同じMQTTトピックを使用します。
  • responseDurationは、プラットフォームがレスポンスを待機する最大時間です。

ファイルの場所およびパス・タイプの詳細は、「複雑な入力のためのJSONファイルの使用」を参照してください。

ステップ5: デバイスでのRAW JSONコマンドの起動

コンソール、CLIまたはAPIを使用して、同じコマンドを起動します。

    1. IoTドメインを開き、「デジタル・ツイン・インスタンス」を選択します。
    2. インスタンスを開き、「アクション」、「RAWコマンドの送信」の順に選択します。
    3. リクエスト・エンドポイントとして/endpoints/1234を入力し、リクエスト期間としてPT3Mを入力します。
    4. 「JSON」を選択し、{"temp": 33}と入力します。
    5. レスポンス・パラメータとして/endpoints/4321およびPT3Mを指定します。
    6. 「Send raw command」を選択します。

  • oci iot digital-twin-instance invoke-raw-json-commandコマンドを使用します:

    oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <digital-twin-instance-OCID> \
  --request-endpoint "/endpoints/1234" \
  --from-json file://command.json

  • デジタル・ツイン・インスタンスに対してInvokeRawCommand操作を実行し、command.jsonの値を使用します。

ステップ6: MQTTXでコマンドを受信してレスポンスを公開する

  1. /endpoints/1234サブスクリプションで、MQTTXがリクエスト・データを受信することを確認します。
    {
  "temp": 33
}
  2. レスポンス期間が期限切れになる前に、QoS 1を使用して/endpoints/4321へのレスポンスを公開します。
    {
  "status": "accepted",
  "temp": 33
}

MQTTXがIoTデバイス・ホストに接続されました。

コマンドメッセージを表示するMQTTX

コマンド・レスポンス・シナリオ
シナリオデバイスの状態予想されるコマンド状態コメント
接続されていません接続されておらず、サブスクライブされていません拒否済コマンドの配信はすぐに失敗します。
接続済ですがサブスクライブされていません接続済拒否済デバイスはオンラインですが、コマンドを受信できません。
サブスクライブしましたが、接続されていませんサブスクリプションは永続セッションにあります期限切れへの保留コマンドは待機し、タイムアウト後に期限切れになります。
タイムアウト前に再接続永続セッションで初期オフライン送信待ちデバイスは再接続後にコマンドを受信します。
接続済およびサブスクライブ済接続済およびサブスクライブ済送信デバイスはコマンドを受信します。
一方向コマンド接続済およびサブスクライブ済COMPLETED予期される応答はありません。
レスポンスのない双方向コマンド接続済およびサブスクライブ済NOT_RESPONDEDデバイスは、応答タイムアウトの前に応答しません。
レスポンスのある双方向コマンド接続済およびサブスクライブ済COMPLETEDデバイスは、タイムアウトの前にレスポンスを公開します。

ステップ7: APEXでのコマンドの配信ステータスの監視

IoTデータへのAPEXアクセスを構成した後、APEXを使用してRAWコマンド・データを問い合せます。

  1. IoTドメインの詳細を取得して、<domain-short-id-from-device-host>を検索します。APEXで、ワークスペース名とデータベース・ユーザー名の両方としてこの値を使用してIoTドメインのワークスペースにログインします:
    <domain-short-id-from-device-host>__WKSP
    ノート

    __WKSPの2つのアンダースコアに注意してください。
  2. 「SQLワークショップ」に移動し、「SQLコマンド」を選択して、読取り専用<domain-short-id-from-device-host>__IOTスキーマを選択します。
  3. 次のコマンドを入力します。<domain-short-id-from-device-host>および<digital-twin-instance-OCID>を環境の値に置き換え、「実行」を選択します。
    select *
from <domain-short-id-from-device-host>__IOT.RAW_COMMAND_DATA
where digital_twin_instance_id = '<digital-twin-instance-OCID>';
  4. 「結果」で、RESPONSE_DATA、配信ステータス、リクエスト・エンドポイントとレスポンス・エンドポイント、およびタイムアウト値を確認します。

大きなスクリーンショットを表示するには、右クリックして新しいブラウザ・タブでイメージを開きます。APEX SQLコマンドの結果は、レスポンス・データ列が強調表示されたRAWコマンド・データです。