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

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

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

全体的なフロー

アクションとコマンドの実行の全体的なフローを以下にまとめます。

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

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

ステップ2　コマンド（アクション）の検証

Thing Interaction Framework は、モバイルアプリより送信されたコマンド（を構成するアクション）を検証します。検証は、対応するトレイトの内容に基づいて実施されます。検証の詳細はコマンドの検証をご覧ください。

検証の結果コマンドが無効であると判定された場合は、Thing へのコマンドの送信は拒否されエラーが返されます。

ステップ3　Thing によるコマンド受信と実行

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

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

ステップ4　Thing からのコマンドリザルト送信

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

ステップ5　プッシュ通知によるモバイルアプリへの通知

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

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

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

ステップ6　コマンドリザルトの取得

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

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

コマンドとアクション

コマンドの構成

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

各アクションには JSON 形式のパラメーターをつけることができます。この JSON の形式は自由です。JSONObject や JSONArray を使って複数フィールドを定義することもできます（例：LED ライトの RGB 値）。ただし、データ形式を定義したトレイトの登録があらかじめ必要です。また、コマンドを受信する Thing とこのトレートが関連付けされていなければなりません。

コマンド送信の際には、この関連付けをしているトレイトエイリアスをあわせて Thing Interaction Framework に送信します。たとえば「センサーの電源をオンにした後、センサーをリセット」というコマンドを送信したい場合、Thing Interaction Framework に送られるデータは次のようなものになります。

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

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

アクションリザルト

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

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

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

コマンドの検証

モバイルアプリよりコマンドを受信すると、Thing Interaction Framework は対応するトレイトに基づいてコマンドを構成するアクションを検証します。アクションの検証は、トレイトの payloadSchema で設定された内容に基づいて実施されます。

今回のコマンドの例はトレイトエイリアスの登録で例示したケースを想定したものです。Thing Interaction Framework は、トレイトエイリアス LiquidLevelMeterAlias を参照することにより、トレイト LiquidLevelMeter のバージョン 1 に基づいてアクション turnPower と resetSensor を検証すればよいことを認識します。トレイトではいずれのアクションもパラメーターとしてブール値を期待しているとされているため、ブール値以外が送信された場合はエラーが返されます。

コマンドの取得

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

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

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

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

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

コマンドの詳細情報

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

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

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

title

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

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

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