アクションとコマンドの実行

モバイルアプリから Thing を操作するコマンドを発行し、Thing を制御することができます。Thing からはコマンドを実行した結果のエラー情報を、プッシュ通知を経由してモバイルアプリに返すことができます。

実装方法の詳細は、こちら(AndroidiOSJavaScriptREST APIThing)をご覧ください。

ゲートウェイ を使用した構成の場合、エンドノードにコマンドを送信することもできます。ゲートウェイそのものには送信できません。

1. モバイルアプリよりコマンド送信

モバイルアプリは、アプリのユーザーインターフェイスの操作などを受け、Thing に実行させたいコマンドを Thing Interaction Framework に送信します。ここでのコマンドには、たとえば「電源:オン」などのパラメータを含めることができます。

2. Thing によるコマンド受信と実行

Thing Interaction Framework は、MQTT によるプッシュ通知を使ってコマンドを Thing に送信します。

Thing ではプッシュ通知を受けると、SDK が自動的にアクションハンドラーを呼び出します。アクションハンドラーにハードウェアを制御するプログラムを書いておけば、パラメータに従って目的の制御を行うことができます。

3. Thing からのコマンドリザルト送信

Thing は、コマンドの実行が成功したかどうかの結果情報をコマンドリザルトとして Thing Interaction Framework に通知します。

4. プッシュ通知によるモバイルアプリへの通知

Thing Interaction Framework はプッシュ通知によってモバイルアプリにコマンドの実行が行われたことを通知します。ここではコマンド ID だけが通知されます。

モバイルアプリのプラットフォームに応じて、利用できるプッシュ通知ネットワークからプッシュ通知を送信できます。

仮ユーザー(Pseudo User)をオーナーとして設定した場合、コマンド ID は、実行中のデバイスから送信したコマンドについてのみ受け取ることができます。Thing を共有している他のデバイスで発行されたコマンドの ID は通知されません。通常のユーザーがオーナーである場合は、デバイスのインストール によってオーナーと紐付けられているすべてのデバイスに、コマンド ID のプッシュ通知が送信されます。

5. コマンドリザルトの取得

プッシュ通知にはコマンド ID しか含まれていません。必要に応じて、モバイルアプリから該当コマンドの取得要求を行い、コマンドリザルトを取得できます。

コマンドリザルトを取得することで、コマンドの実行によるエラーの有無を知ることができます。

コマンドとアクション

コマンドの構成

実際のコマンドは、下記の図のように 1 つ以上のアクションの配列により構成されます。配列の順序には意味があり、コマンドを受け取った Thing は、配列の順序でアクションを実行します。

各アクションには JSON 形式のパラメーターをつけることができます。この JSON の形式は自由です。JSONObject や JSONArray を使って複数フィールドを定義することもできます(例:LED ライトの RGB 値)。

たとえば「エアコンの電源をオン、設定温度を 25 度に設定、ファン速度を 5 に設定」というコマンドを送信したい場合、Thing Interaction Framework に送られるデータは次のようなものになります。

コマンドが複数のアクションから構成されるのは、状況に応じて必要なアクションのセットが異なるためです。たとえば、電源オンのときには「電源のオンオフ」、「設定温度」、「ファン速度」の 3 つのアクションが必要でも、電源オフの時には「電源のオンオフ」を制御するアクションだけで十分です。アクションの設計時には、概念的なまとまりとしてだけではなく、コマンドを送信する状況ごとに適切なアクションのセットを検討します。

また、アクションの設計時には、Thing 側の実装を含めて検討してください。Thing の実装では、コマンドの到着時にアクションごとにコールバック関数が呼び出されます。制御対処のハードウェアの入出力仕様上、パラメータを同時に出力しなければならないものは、同一のアクションとしてパラメータを送信した方が実装が容易になります。

アクションの設計は スキーマ として定義します。

アクションリザルト

さらに、各アクションはアクションリザルトを持ちます。アクションリザルトは、成功可否のステータスとエラーメッセージから構成されます。

なお、初めのフローに示したコマンドリザルトは説明用の概念で、SDK のクラスなどには存在しません。実装上のデータ構造では、以下のようにコマンドが、それに対応するアクションとアクションリザルトの配列を持つ構造で表現されます。

なお、コマンドの応答にパラメータを含めることはできません。Thing からの値の取得が必要な場合は ステート を利用できます。

コマンドの取得

モバイルアプリからの要求や トリガー によってコマンドが実行されるとき、それらのコマンドは一旦 Thing Interaction Framework 上に登録されます。

登録されたコマンドには コマンド ID が割り当てられ、コマンド ID を使って最新の情報を参照することができます。特に、Thing が実行結果を返す場合は、モバイルアプリからコマンドリザルトを取得できます。

コマンドの取得方法には以下の 2 通りがあります。

  • コマンド ID を指定して、指定されたコマンド 1 件を取得する。
  • 登録されているコマンドをすべて取得する。

それぞれの詳細は、Thing-IF SDK ガイドをご覧ください。

コマンドの詳細情報

コマンドを Thing Interaction Framework に送信する際、コマンドの詳細情報を登録することができます。登録した詳細情報は、コマンドの取得機能によって取得できます。

詳細情報は Thing Interaction Framework では特に解釈されません。モバイルアプリのユーザーインターフェイスで表示するための文字列やアイコンなど、任意の情報を登録できます。

登録できる詳細情報には以下のものがあります。いずれのフィールドも、指定の有無は任意です。これらは、下記の図のようにコマンドに関連付けて保存されます。

  • title

    コマンドのタイトルです。最大 50 文字までの任意の文字列を登録できます。

  • description

    コマンドの詳細説明です。最大 200 文字までの任意の文字列を登録できます。

  • metadata

    コマンドのメタデータです。アプリケーションから使用するデータを任意の JSON 形式で指定します。