プラグインの動作の仕組みを簡単に解説します。
プラグインとはKadecot|JS (以下Kadecot) の中心的な機能を提供する部分です。つまり、機器ごとに異なるプロトコルをWAMPに変換し、Kadecot APIの体系で使えるようにします。以下、WAMPに関する基本概念(Procedure文字列を用いたRPC、Topic文字列を用いたPubSub)については既知とします。
プラグインには管理プラグイン、通常プラグイン、外部プラグインの３種類があります。
-
管理プラグイン Crossbar.ioのゲストプロセスとして起動されるメインのプラグインで、他のプラグインを起動・管理し、機器リストをメンテナンスする役割を持つのに加え、WAMPのユーザー管理や、JSONP APIのホストなどを行います。各機器には、見つかった順deviceIdというユニークなIDを割り当てます。機器登録時にはプラグインからUUIDが送られているので、もしUUIDに重複がある場合は、もともと登録されていたdeviceIdを再度割り当てるようになっています。
-
通常プラグイン v1/pluginsの下の、ユニークな名前のディレクトリの下に配置されるmain.jsをエントリーポイントとしたプラグインです。管理プラグインによって起動されます。その時に引数として、WAMPルータとのコネクションも保持している、PluginInterfaceオブジェクトを受けとります。このオブジェクトを用いて、機器発見や消失の通知や、RPC/PubSubの機能実装を行います。
-
外部プラグイン v1/plugins/net.kadecot.external/main.jsに配置されている、外部サービスに接続するためのプラグインです。通常プラグインとほとんど同様ですが、topicやprocedureの命名規則がわずかに異なります。
管理プラグインの持つ３つの機能、WAMPユーザー管理、他のプラグイン管理、JSONP APIサーバ立ち上げについて解説します。
KadecotのWAMPに接続するためには認証が必要で、CrossbarのAuthentication機能を用いています。
管理プラグインは最初にスーパーユーザーとしてstaticなWAMP-Ticket認証でCrossbarに接続します。スーパーユーザー名（Crossbarの用語でいえばrole）はsuperuser、パスワードはシェルスクリプトにより起動時に動的生成されます。 APIクライアント（一般ユーザー）やプラグインはDynamicなWAMP-CRA認証です。他のクライアントが接続してきたときにその認証情報が正しいかどうかの確認を管理プラグインが行います。 スーパーユーザーと一般ユーザーでは権限が違います。権限の詳細についてはplugin-development.mdを参照してください。
管理プラグインは、他のプラグインの起動・接続・死活管理、および機器一覧管理を行います。実装はv1/provider.jsです。プラグインフォルダ(v1/plugins/)内をスキャンし、見つけたディレクトリごとに、デフォルトユーザー(最初の一般ユーザー)としてCrossbarへのWAMP接続を試みます。（ただし、この時点ではindex.jsの呼び出しはまだです）。
プラグインが存在するディレクトリ名はPrefixと呼び、重要な意味があります。プラグインが実現するProcedureやTopicは、必ずこの名前からはじまることになります。名前の衝突を避けるため、お持ちのドメイン名を逆に並べてお使いください。Sony CSLではcom.sonycsl.kadecotとnet.kadecotからはじまるもののみ作っています。（com.sonycsl.kadecotはAndroid版との互換性のために使っているもので、ゆくゆくはAndroid版と同時にnet.kadecotに一本化したいと思っています）
WAMPセッションが確立したら、管理プラグインはPluginInterfaceオブジェクトを作ります。この時の処理は、v1/plugin-interface.jsに書かれています。この中でセッションIDなどを調べて管理プラグインに登録します。こういった初期化が終わったら、PluginInterfaceを引数として、プラグイン本体（各ディレクトリ内にあるmain.js）を呼び出します。
プラグイン側の処理としては、新しい機器を見つけたり、接続が切れたりした場合にPluginInterfaceオブジェクトのメソッドを用いて逐一管理プラグインにそれを通知します。管理プラグインはその情報を用いて、機器リストを作り、死活情報も保存していきます。また、procedureやtopicなどを登録し、処理の本体を実装するときにもPluginInterafceの目祖度呼び出しを行います。
プラグインとWAMPルータとの接続が切れると、Crossbar.ioでは特定のtopicにそれが通知されますので、管理プラグインはその情報を用いて機器管理に役立てます。
JSONP APIサーバは31413ポートに開かれるWebサーバです。JSONPに対応しているので、クロスドメインアクセスが可能です。実装はv1/JSONPRouter.jsにありますが、本ドキュメントでは説明しません。単なる普通のWAMP APIクライアントのRPCコールのラッパーを提供しているだけです。
通常のプラグインとしての最小の機能は、exports.init()を実装することです。 機能を実装するには、exports.init()の引数として渡されてPluginInterfaceオブジェクトのメソッドを用います。以下のメソッドが実装されています。
- registerDevice : 機器の登録
機器が見つかったら、registerDeviceを呼び出します。機器の種類名、ニックネームに加えてUUIDを引数に与えます。UUIDは、なるべくIPアドレスなどに依存しない、ユニークなものを指定したほうが望ましいです。ECHONET Liteの場合はメーカーコードなども含む機器IDを登録しているので、DHCPなどの影響を受けずに重複対応ができます（UUIDが変わらなければ同じdeviceIdになります）。
- registerProcedures : WAMP Procedureの登録
APIクライアントからの呼び出しに応答するために用いるProcedureの登録を行います。
- publish : トピックへのPublish
Publishしたい場合は事前の登録など必要ありません。Publishしたいタイミングで以下のようなコールをしてください。
- unregisterDevice : 機器の削除
pluginInterface.unregisterDeviceは機器の削除を行います。引数に、登録時に指定したUUIDを入れて呼び出してください。
外部プラグインはv1/net.kadecot.external/の下に実装されている、外部サービスと連携するための特殊なプラグインです。 外部プラグインは、それ自体には機器プロトコル制御の機能を実装しておらず、同じディレクトリ内にあるclients.jsonの情報に基づいて、外部のサーバにWebSocketで接続しに行きます。そのサーバが特定のプロトコルに従っていれば、外部サービスが機器オブジェクトの形でKadecotに登録され、RPC/PubSubでその機能を利用することができるようになります。
また外部プラグインの機能として、APIブリッジがあります。外部サービスがAPIブリッジをリクエストすると、KadecotのAPI呼び出しを外部プラグイン経由で行えるようになります。これによって、外部サービスが宅内の機器一覧を得たり、メンテをするなどが可能になります。
特定の外部サービスに、どの機能を開示するかはローカル側で制御します。まだユーザーインターフェースが十分ではありませんが、まずはWAMPルータに元々実装されているRealmによる制御を可能にする予定です。
外部プラグインに関しては、様々なサービスに接続するためTopic/Procedureの命名規則が異なります。通常だとフォルダ名をPrefixとし、その後に.procedure.とか.topic.などが続くことになりますが、外部プラグインの場合、Prefixの前に機器名（外部サービス名）がつけられることになります。
plugin-development.mdを参照してください。