PD Agent
PD Agentは、PD Repeaterから制御メッセージ（JSON文字列）を受け取り、予め設定されたキーと値の一致を持ってユーザーが用意する実行オブジェクトもしくはシェルスクリプト、ダイナミックリンクモジュール又は Lua言語スクリプトを実行します。 (PD Agentでの比較条件は文字列型での完全一致となります。)
PD Agentはユーザー定義のコンフィグ設定を用いることで下流方向の制御機能を持たない PD Handler BLE等と連携することを前提に用意されているアプリケーションですが、本章ではPD Handlerとは連携させず、PD Agentをユーザー定義デバイスとして登録し単独で動作させる方法を例にその使用方法を説明します。
ユーザー定義デバイスの登録と送受信先の設定
- WEB-UIの「サービス」→「基本」→「ユーザーデバイス登録」タブより、PD Agentをユーザー定義デバイスとして登録します。
送受信先が複数ある場合等、複数のデバイスとして運用する場合は、複数登録します。サービス機能の基本設定については、スタートアップガイド のサービス機能を参照して下さい。
ユーザー定義のデバイスの登録とは、デバイス番号を割り振りメモ情報を付与する作業です。 - WEB-UIの「IoTデータ」→「アプリ設定」タブのアプリケーション制御メニューより、PD Agent が起動されるよう設定します。 アプリケーションの起動設定については、アプリ設定を参照して下さい。
- WEB-UIの「IoTデータ」→「送受信設定」タブの「送受信設定」メニューより、送受信先の選択と送受信設定の内個々のデバイスに依存しない設定を行います。
送受信設定については送受信設定（PD Repeater）を参照して下さい。 - WEB-UIの「IoTデータ」→「送受信設定」タブの「デバイス設定（ユーザー定義）」メニューよりユーザー定義デバイスの送受信設定を行います。
ユーザー定義デバイスの送受信設定についてはデバイス設定(ユーザー定義)を参照して下さい。
PD Agentの設定
WEB-UIの「IoTデータ」→「PD Agent」タブより、PD Agentの設定を行います。
初期状態では上図のようになっています。
「使用設定」を「有効」にすると設定項目が表示されます。
複数のデバイスに対する設定行う場合は「追加」をクリックし設定フォームを追加します。
「使用設定」を「有効」にすると上図のように設定項目が表示されます。
PD Agent の設定項目
| 設定項目 | 説明 |
|---|---|
| 使用設定 | この設定を有効にするか無効にするか選択します。 |
| ローカル名 | 通常はデバイスに付与されたデバイス番号とします。 |
| バッファーサイズ | データの最大サイズを設定します。 デバイス側の設定と一致させて下さい。 単位はバイトです。 |
| 待ち受けソケット | 制御メッセージを受け取るUNIXドメインソケットのパス名です。 ここでは、@/pd_handler/userdev_0000001.sock に設定します。 詳細は欄外に記載します。 |
| 書込先ソケット | 応答メッセージを送るUNIXドメインソケットのパス名です。 本例では、@/pd_repeater/userdev_0000001.sockに設定します。 詳細は欄外に記載します。 |
| 実行処理（追加） | 以下に記載する判定キー・処理判断値・実行コマンド・実行コマンド引数を 複数設定したい場合に設定フォームを追加します。 |
| 処理名 | 処理の名称を記載します。 |
| 送信設定 | 「有効」とすることで応答メッセージを送ります。 実行されるコマンドに応答メッセージを返す機能が無い場合等に用います。 |
| 判定キー | 「実行コマンド」に指定されるオブェクトの実行条件として評価される 制御メッセージに含まれるJSON文字列のキーを設定します。 |
| 処理判定値 | 「実行コマンド」に指定されるオブェクトの実行条件として評価される 制御メッセージに含まれるJSON文字列の値を設定します。 |
| 実行コマンド | 「判 定キー」に指定されるキーと「処理判断値」に指定される値が 制御メッセージに含まれる場合に実行される実行オブジェクト もしくはシェルスクリプト、ダイナミックリンクモジュール または Lua 言語スクリプトのパス名を設定します。 ダイナミックリンクモジュールの場合はパス名のディスクリプタを ".so"、 Lua 言語スクリプトの場合は ".lua" として下さい。 これら以外のディスクリプタもしくはディスクリプタが無い場合は 実行オブジェクトとして扱われます。 |
| Lua 関数名 | 実行される Lua 言語スクリプト内の関数名を指定します。 |
| 実行コマンド引数 | 実行コマンドの引数を設定します。 |
- 待ち受けソケット :
- 制御メッセージを受け取るUNIXドメインソケットのパス名です。
デバイスとしてユーザー定義デバイスを用い、PDRepeaterから直接制御メッセージを受け取る本例では、@/pd_handler/userdev_0000001.sock に設定します。(`@`はwrite時に`\0`に置き換えられます。)
先頭の @ は、パス名が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" } となります。
一致する制御メッセージを受け取ると '/usr/local/bin/device_switch on' が実行されます。
次の設定に対する制御メッセージは { "switch": "off" } となります。
一致する制御メッセージを受け取ると '/usr/local/bin/device_switch off' が実行されます。
次の設定に対する制御メッセージは { "report": "do" } です。
一致する制御メッセージを受け取ると '/usr/local/bin/device_report' が実行されます。
上記の例において制御メッセージとして { "switch": "on", "report": "do" } 場合は、 '/usr/local/bin/device_switch on' と '/usr/local/bin/device_report' が実行されます。
info
- 複数の実行条件が適用されるメッセージを受信した場合、連続で処理が実行されますが、実行処理順については担保されませんので、ご注意ください。
- ダイナミックリンクモジュールと Lua 言語スクリプトについてについては PDHMSリファレンスのPD Agentを参照してください。
環境変数への継承
制御メッセージ（JSON文字列）の内、実行オブジェクトもしくはシェルスクリプトの実行条件として用いられるキーと値を含め、その値が文字列か数値であれば、それらは環境変数に設定され実行オブジェクトもしくはシェルスクリプトへ継承されます。
例えば、以上の例において { "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 | 文字列 | PD Repeaterの下流方向メッセージ制御メッセージ(クラウドから送られてきたペイロード) |
| agent_localname | 文字列 | PD Agent の設定項目の「ローカル名」に設定されるローカル名 |
| agent_bind | 文字列 | PD Agent の設定項目の「待ち受けソケット」に設定される待ち受けソケット名 |
| agent_push_to | 文字列 | PD Agent の設定項目の「書込ソケット」に設定される書込ソケット名 |
| agent_buffer_size | 整数 | PD Agent の設定項目の「バッファサイズ」に設定されるバッファサイズ |
応答メッセージ
PD Agent の設定項目の「送信設定」が「有効」に設定されている場合は、実行ステータスとして次の応答メッセージを返します。
実行コマンドを起動した :
実行コマンドの実行に失敗した :
実行コマンドの実行を終了した :
一致するキーと値が存在しない :
制御メッセージがJSON文字列でない :
ここで、"md5" はPD Repeaterの下流方向メッセージに記載される制御メッセージのハッシュ値、 {"key":"value"} は、一致した「判断キー」と「処理判断値」です。
実行ステータスは、実行オブジェクトもしくはシェルスクリプトを呼び出すexecv()の戻り値であり、実行オブジェクトもしくはシェルスクリプトの処理結果を示すものではありません。
処理の完全性を求めるのであれば応答メッセージは実行オブジェクトもしくはシェルスクリプトかagent_push_to 環境変数で継承されるUNIXドメインソケットに返すようにして下さい。