PD Agent

PD Agentは、PD Repeaterから制御メッセージ(JSON文字列)を受け取り、 予め設定されたキーと値の一致を持ってユーザーが用意する実行オブジェクトもしくはシェルスクリプト、 ダイナミックリンクモジュール又は Lua言語スクリプトを実行します。 (PD Agentでの比較条件は文字列型での完全一致となります。)
PD Agentはユーザー定義のコンフィグ設定を用いることで下流方向の制御機能を持たないPD Handler BLE等と 連携することを前提に用意されているアプリケーションですが、本章ではPD Handlerとは連携させず、 PD Agentをユーザー定義デバイスとして登録し単独で動作させる方法を例にその使用方法を説明します。

ユーザー定義デバイスの登録と送受信先の設定

  1. WEB UIの「サービス」→「基本」→「ユーザーデバイス登録」タブより、PD Agentをユーザー定義デバイスとして登録します。 送受信先が複数ある場合等、複数のデバイスとして運用する場合は、複数登録します。 サービス機能の基本設定については、WEB UIセットアップガイドサービス機能 を参照して下さい。 ユーザー定義のデバイスの登録とは、デバイス番号を割り振りメモ情報を付与する作業です。

  2. WEB UIの「IoTデータ」→「アプリ設定」タブのアプリケーション制御メニューより、PD Agent が起動されるよう設定します。 アプリケーションの起動設定については、IoTデータ制御のアプリ設定 を参照して下さい。

  3. WEB UIの「IoTデータ」→「送受信設定」タブの「送受信設定」メニューより、 送受信先の選択と送受信設定の内個々のデバイスに依存しない設定を行います。 送受信設定については 送受信先毎の設定 を参照して下さい。

  4. WEB UIの「IoTデータ」→「送受信設定」タブの「デバイス設定(ユーザー定義)」 メニューよりユーザー定義デバイスの送受信設定を行います。 ユーザー定義デバイスの送受信設定については デバイス設定(ユーザー定義) を参照して下さい。

PD Agentの設定

WEB UIの「IoTデータ」→「PD Agent」タブより、PD Agentの設定を行います。

../../../../_images/pd_agent_init.png

初期状態では上図のようになっています。

「使用設定」を「有効」にすると設定項目が表示されます。
複数のデバイスに対する設定行う場合は「追加」をクリックし設定フォームを追加します。
../../../../_images/pd_agent.png

「使用設定」を「有効」にすると上図のように設定項目が表示されます。

PD Agent の設定項目

設定項目

説明

使用設定

この設定を有効にするか無効にするか選択します。

ローカル名

通常はデバイスに付与されたデバイス番号とします。

バッファーサイズ

データの最大サイズを設定します。デバイス側の設定と一致させて下さい。単位はバイトです。

待ち受けソケット

制御メッセージを受け取るUNIXドメインソケットのパス名です。

本例では、@/pd_handler/userdev_0000001.sock に設定します。

詳細は欄外に記載します。

書込先ソケット

応答メッセージを送るUNIXドメインソケットのパス名です。

本例では、@/pd_repeater/userdev_0000001.sock に設定します。

詳細は欄外に記載します。

実行処理(追加)

以下に記載する判定キー・処理判断値・実行コマンド・実行コマンド引数を複数設定したい場合に設定フォームを追加します。

処理名

処理の名称を記載します。

送信設定

「有効」とすることで応答メッセージを送ります。実行されるコマンドに応答メッセージを返す機能が無い場合等に用います。

判定キー

「実行コマンド」に指定されるオブェクトの実行条件として評価される制御メッセージに含まれるJSON文字列のキーを設定します。

処理判定値

「実行コマンド」に指定されるオブェクトの実行条件として評価される制御メッセージに含まれるJSON文字列の値を設定します。

実行コマンド

「判定キー」に指定されるキーと「処理判断値」に指定される値が制御メッセージに含まれる場合に実行される実行オブジェクトもしくはシェルスクリプト、 ダイナミックリンクモジュール又は Lua 言語スクリプトのパス名を設定します。 ダイナミックリンクモジュールの場合はパス名のディスクリプタを ".so"、Lua 言語スクリプトの場合は ".lua" として下さい。

Lua 関数名

実行される Lua 言語スクリプト内の関数名を指定します。

実行コマンド引数

実行コマンドの引数を設定します。

待ち受けソケット :
制御メッセージを受け取るUNIXドメインソケットのパス名です。
デバイスとしてユーザー定義デバイスを用い、PD Repeaterから直接制御メッセージを受け取る本例では、 @/pd_handler/userdev_0000001.sock に設定します。
先頭の @ は、パス名がAbstract UNIXドメインソケット名であることを意図し、 Abstract UNIXドメインソケット名をサポートしない実行オブジェクトから待ち受ける場合は、 /tmp/pd_agent_0000001.sock等のファイルシステムに実在するパス名とします。
書込ソケットのパス名 :
応答メッセージを送るUNIXドメインソケットのパス名です。
デバイスとしてユーザー定義デバイスを用い、PD Repeaterへ直接応答メッセージを送る本例では、 @/pd_repeater/userdev_0000001.sock に設定します。
先頭の @ は、パス名がAbstract UNIXドメインソケット名であることを意図し、 Abstract UNIXドメインソケット名をサポートしない実行オブジェクトへ送る場合は、/tmp/ anyobject_0000001.sock等のファイルシステムに実在するパス名とします。

PD Agentの設定と制御メッセージ

PD Agentの設定と制御メッセージの例を幾つか示します。

次の設定に対する制御メッセージは { "switch": "on" } となります。

../../../../_images/pd_agent_1.png

一致する制御メッセージを受け取ると '/usr/local/bin/device_switch on' が実行されます。

次の設定に対する制御メッセージは { "switch": "off" } となります。

../../../../_images/pd_agent_2.png

一致する制御メッセージを受け取ると '/usr/local/bin/device_switch off' が実行されます。

次の設定に対する制御メッセージは { "report": "do" } です。

../../../../_images/pd_agent_3.png

一致する制御メッセージを受け取ると '/usr/local/bin/device_report' が実行されます。

上記の例において制御メッセージとして {"switch": "on", "report": "do" } 場合は、 '/usr/local/bin/device_switch on' と '/usr/local/bin/device_report' が実行されます。

注釈

複数の実行条件が適用されるメッセージを受信した場合、連続で処理が実行されます。
実行処理順については担保されませんので、ご注意ください。

環境変数への継承

制御メッセージ(JSON文字列)の内、実行オブジェクトもしくはシェルスクリプトの実行条件として用いられるキーと値を含め、 その値が文字列か数値であれば、それらは環境変数に設定され実行オブジェクトもしくはシェルスクリプトへ継承されます。

例えば、以上の例において { "switch" : "on", "report": "do", "page": 40 } の制御メッセージを受け取った場合、 コマンドの実行においては次の環境変数が継承されます。

switch="on"
report="do"
page=40

また、制御メッセージの内容に関わらずPD Agentは、 実行オブジェクトもしくはシェルスクリプトの実行において、次の値を環境変数として継承します。

実行オブジェクトもしくはシェルスクリプトに環境変数として継承されるパラメータ

環境変数

データ型

説明

request_cloud_id

整数

PD Repeaterの下流方向メッセージ に記載される Cloud ID

request_sub_id

整数

PD Repeaterの下流方向メッセージ に記載される Sub ID

request_header

文字列

PD Repeaterの下流方向メッセージ に記載されるヘッダー

request_md5

文字列

PD Repeaterの下流方向メッセージ に記載される制御メッセージのハッシュ値

request_payload

文字列

クラウドから送られてきたペイロード

agent_localname

文字列

PD Agentの設定 の「ローカル名」に設定されるローカル名

agent_bind

文字列

PD Agentの設定 の「待ち受けソケット」に設定される待ち受けソケット名

agent_push_to

文字列

PD Agentの設定 の「書込ソケット」に設定される書込ソケット名

agent_buffer_size

整数

PD Agentの設定 の「バッファサイズ」に設定されるバッファサイズ

応答メッセージ

PD Agentの設定 の「送信設定」が「有効」に設定されている場合は、実行ステータスとして次の応答メッセージを返します。

実行コマンドを起動した

{
   "time": "timestamp", "reply_to": "md5", "result": "queuing",
   "reason": "matched", "matched": {"key": "value"}
}

実行コマンドの実行に失敗した

{
   "time": "timestamp", "reply_to": "md5", "result": "faild",
   "reason": "matched", "matched": {"key": "value"}
}

実行コマンドの実行を終了した

{
   "time": "timestamp", "reply_to": "md5", "result": "done",
   "reason": "matched", "matched": {"key": "value"}
}

一致するキーと値が存在しない

{
   "time": "timestamp", "reply_to": "md5", "result": "not queuing",
   "reason": "key and value not matched"
}

制御メッセージがJSON文字列でない

{
   "time": "timestamp", "reply_to": "md5", "result": "not queuing",
   "reason": "not JSON form"
}
ここで、md5は、PD Repeaterの下流方向メッセージ に記載される制御メッセージのハッシュ値、 {"key": "value"} は、一致した「判断キー」と「処理判断値」です。
実行ステータスは、実行オブジェクトもしくはシェルスクリプトを呼び出すexecv()の戻り値であり、 実行オブジェクトもしくはシェルスクリプトの処理結果を示すものではありません。 処理の完全性を求めるのであれば応答メッセージは実行オブジェクトもしくはシェルスクリプトから agent_push_to 環境変数で継承されるUNIXドメインソケットに返すようにして下さい。