基本APIリファレンス（１）概要・admin・db・macro

Quickstartでも述べたように、PicoGWのAPI構成は、8080番ポートにブラウザでアクセスすると見られるWebフロントエンドの階層構造を開いていくとわかりますが一覧性に欠けるので一応こちらにもまとめておきます。PicoGWはかなり徹底したプラグインアーキテクチャとなっており、動作に最低限必要な機能も多くはプラグインとして実装されています。ホストされるAPIのペイロードもすべてプラグインが決めていますので、APIの内容について知りたければ、まずはプラグインごとのREADMEを参照してください。
ドキュメントはソースから自動生成するようなモダンな作り方をしているわけではなく、手書きとなっていますので食い違いが生じる可能性があります。最新状況はWebフロントエンドのほうを参照してください。

PicoGWをインストールすると自動的に導入されるプラグインは以下の通りです。

• admin : APIのホスティング、プラグインのマネージメント、ネットワークのマネージメントなど、PicoGWの動作に必要な低レベルの処理を行います。PicoGWのプラグインの初期化処理はランダムな順序で行われますが、adminだけは他のプラグインに先んじてロードされ、それが終わった時点でほかのプラグインのロードに取り掛かるようになっています。

• web : Webフロントエンドを作るためのプラグインですが、APIをホストする機能はなく設定項目もないhttp属性のプラグイン（後述）のでWebフロントエンドにはリストされません。

• db : 汎用のストレージプラグインです。ゲートウェイ内に保存していてほしい情報がある場合には使ってください。もともとはフロントエンドの永続的ストレージとして使うことを想定して開発したものです。デフォルトのフロントエンドでは使われていませんが、かっこいいフロントエンドを作りたい場合は利用すると便利かもしれません（ただし、フロントエンドの開発には正直言って癖があるのであとで述べる開発方法を参照してください）。

• macro : 定時実行する処理を記述したり、一回のAPI呼び出しで条件分岐などの複雑な処理をさせたい場合に用います。WebフロントエンドのSettingsからJavaScriptのコードを記述することでロジックを設定します。コードはサンドボックス内で実行され、JavaScriptの基本機能と、他のAPIを呼び出す機能、プラグイン内に保存されるログデータストレージへのエントリー追加以外の処理はできないようになっています。呼び出しごとにvmが立ち上がるため変数の持越しはできませんが、globalというオブジェクトを使うと永続情報を扱うことができます。ただし、ゲートウェイが再起動するとクリアされてしまうため、再起動しても消えない永続情報を扱いたい場合は、dbプラグインの呼び出しと組み合わせてください。(addLog()したログデータはファイルに保存されるため、再起動しても消えません）

• echonet : 家電と通信するのに非常に便利なECHONET Liteプロトコルを実現するプラグインです。PicoGWを動かすために必須というわけではありませんが、ECHONET Liteには機器発見機能もあり、PicoGWが動作しているサーバーを発見するのに有益なのと、チュートリアルやワークショップで利用するのにも役に立つため、デフォルトで入れています。
  不要な場合はpicogwがグローバルインストールされているディレクトリの下に行って
  npm un –save picogw-plugin-echonet
  としてください。

adminプラグイン

adminプラグインはPicoGWの基本管理機能を実装しているプラグインで、他のプラグインに先んじて初期化されます。非常に重要なプラグインですが、外部に公開されるAPIはほんのちょっとです。

GET /v1/admin/id

ゲートウェイを特定するIDを取得します。IDはMQTT Pluginなどで用います。PicoGWが動作しているマシンのMACアドレスになっています。
この値はゲートウェイのIDとしてユニークになることが望ましいので変更することは推奨しませんが、どうしても変えたい場合はPicoGWを一度走らせたのちに ~/.picogw/storage/admin/local-storage/MY_UNIQUE_ID というファイルの中身を変更し、PicoGWを再起動してください。

GET /v1/admin/net

PicoGWが実行されているマシンに保存されているMACアドレス一覧を返します。うち一つは自分です。
MACアドレスはARPテーブルから取得します。ARPテーブルは毎分一回ポーリングされるので、IPアドレスの変更はある程度トレースされています。現在はIPv4ネットワークしか使っていません。

ARPテーブルの取得方法はOSやディストリビューションによって異なります。PicoGWが未知のOSやディストリビューション上で動かない場合、ARPテーブルのスキャンに失敗している可能性があります。このスキャンはarpedというライブラリで行われていて、プラットフォームごとに処理を切り替えているコード本体はarped/lib/parsers/ 以下にあります（picogwのインストールディレクトリからたどるとpicogw/node_modules/picogw-plugin-admin/node_modules/arped/lib/parsers/)
単にarpテーブルの文字列処理で情報を取り出しているだけなので、この部分を書き換えれば動作する可能性が高いです。もし新しいパーザーを書かれた場合は、ぜひarpedにプルリクエストをお願いします。

GET /v1/admin/server_status

OSの状態を取得するvmstatというコマンドを実行し、その結果を返すだけのメソッドです。vmstatが入っていない場合はエラーが返ります。

dbプラグイン

dbプラグインは汎用の永続的ストレージ機能を実装します。key-value形式（keyは文字列、valueは文字列化されたJSONオブジェクト）で情報を保存します。ゲートウェイ内に保存していてほしい情報がある場合には使ってください。

GET /v1/db

保存されている全てのキーを返します。

GET /v1/db/[PATH_AS_A_KEY]

キーを指定し、保存されている値を取得します。

PUT|POST /v1/db/[PATH_AS_A_KEY]

特定のキーに値を格納します。値はJSON形式である必要があります。実際に保存される前にstringify()されます。
このAPIが成功すると、格納された値が当該パスからPublishされます。

DELETE /v1/db/[PATH_AS_A_KEY]

キー及び格納されている値が削除されます。当該パスから{}がpublishされます。

DELETE /v1/db

全ての情報を削除します。

PUB /v1/db/[PATH_AS_A_KEY]

前述のように、指定パスに新たな値が格納されたとき、値が削除されたときにPublishされます。

macroプラグイン

macroプラグインは、スクリプティングでなければ記述できないような複雑な処理を、JavaScriptで記述するための仕組みを持ったプラグインです。マクロを記述するにはWebフロントエンドから/v1/macroを探し右クリック=>Settingsを開きます。

On Demandエリア（設定画面一番上のテキストエリア）には、GET /v1/macro/run が呼び出されたときに実行されるロジックを記述します。文法は普通のJavaScriptですが、以下の関数が追加されています。

getArgs() : GET引数をオブジェクトとして取得する
callProc() : PicoGWのAPIを呼び出す。Promiseが返るのでawaitで待つとよい。
addLog(key,value) : 引数に指定したオブジェクトがmacroプラグインのログエリアに記録される。
resolve(), reject() : macroスクリプトが正常にするためには、どちらかを必ず呼び出す必要がある。
print() : console.logと同意。

また、普通に変数を宣言すると、実行が終わった時点で消えてしまうので、次回呼び出し時にも値が保持されるオブジェクトとしてglobalという変数が用意されています。ただしglobalもPicoGWがリブートすると消えてしまうので、リブートしても消えない変数が必要な場合はcallProc()でDBプラグインを呼び出してストレージに保存するようにしてください。
デフォルトでサンプルプログラムがいろいろと入っています。DBプラグインの呼び出し例もあるので参考にしてください。

Pollingエリア（二番目のテキストエリア）は、定期的に実行されるスクリプトを記述します。ログを取得するコードを記述することを想定しています。この中ではcallProc()とaddLog()とprint()とglobalオブジェクトしか拡張関数がありません(引数はもちろんありませんし、resolve/rejectも存在しません）

定時実行スクリプトの実行インターバルとログが保存される最大数もSettingsで指定できます。実行インターバルとして-1を指定すると、ポーリングは行われません（これがデフォルトです）。
実行インターバルは数だけを書いた場合は分単位と解釈されます。1であれば毎分一回、10であれば10分に一回ポーリングします。ポーリング時間は毎時0分から数えられますので、例えば10を指定すると毎時0分、10分、20分…のように実行されます。したがって、10:05分に10分おきを指定すると、次の（最初の）ポーリング時間は5分後になります。1分より細かい頻度でアクセスしたい場合は、1sとか100msとか、末尾に’s’か’ms’を足してください。ただし、あまり細かくした場合、マクロの実行時間によっては予期せぬ動作をすることがありますのでご注意ください。

GET /v1/macro/run

macroプラグインの設定画面で設定される最初のマクロスクリプトを実行し、結果を返す。

このマクロの設定方法がわかれば、API自体はシンプルです。

GET /v1/macro/log

スクリプト内addLog()で記録されるプラグイン内のログエリアの中身すべてを出力する。

PUB /v1/macro/log

プラグイン内のログエリアの内容が更新されるとPublishされる。

DELETE /v1/macro/log

ログエリアの中身を全削除