Arduino "Ciao: development of a new connector"を翻訳してみた

既存のCiaoコネクタをつかうにしても設定ファイルのパラメータについて理解する必要があるため、

Ciao: development of a new connector
http://labs.arduino.org/Ciao+connector+development

を勝手翻訳しましたのでブログ記事に載せておきます。
参考にされる方はat your own riskでお願いします。

------

Ciao:新規コネクタの開発

Getting started

コネクタはスタンドアロンソフトウェアで、すきな言語で開発可能です。Ciaoはイメージ可能な多くのコネクタをサポートします。
各コネクタは、Ciao Coreと相互接続するために必要な2つのシンプルな要件を満たす必要があります：
 

• TCPソケットの使用 - Ciaoと接続するために必要
• JSONの使用 - Ciaoとの通信に必要

以下のサンプル設定ファイルは、一般的なコネクタ"samplecon"のものです：

samplecon.json.conf
{
        "name" : "samplecon",
        "enabled": true,

        //type accepted values: managed/standalone
        "type" : "managed",

        "commands": {
              // 開始コマンドのパラメータ配列
              "start": ["/usr/lib/python2.7/Ciao/connectors/samplecon/samplecon.py"],

              // 停止コマンドの全パラメータ
              "stop": ["/usr/bin/killall","-s", "HUP","samplecon.py"]
        },

        "implements" : {
            "read" : { "direction": "in", "has_params": false },
            "write" : { "direction": "out", "has_params": true },
            "writeresponse" : { "direction": "out", "has_params": true }
        }
}

設定パラメータ

name:
コンテナの名称(小文字)。Ciao Coreへの登録に使用される。name値はMCUサイド(Sketch)上でも使用する。（samplecon.json.confのように）name値をを使った設定ファイル名をつけることはベストプラクティスの一つです。

enabled:
Ciao Coreがコネクタを開始/停止しCiaoとのコミュニケーションを受け入れるかどうか、trueもしくはfalseを指定する。

type:
"managed"もしくは"standalone"のどちらかを指定する。
managedを指定すると、Ciao Coreがコネクタの開始・停止を管理する。"standalone"を指定すると、コネクタは(Ciaoと接続するシステムサービスもしくはデーモンが有効なときだけ）"自己管理"となる。


commands: (type値が"managed"である場合のみ)
    start (コネクタの開始コマンド、絶対パスで指定する)
    stop  (コネクタの終了コマンド、絶対パスで指定する)

implements:
(MCUの観点からの)コネクタによるり実装された機能の配列表現
    read: MCUサイド上で利用可能なインストイラクション"Ciao.read(…)"が指定された場合
    write: MCUサイド上で利用可能なインストイラクション"Ciao.write(…)"が指定された場合
    writeresponse: MCUサイド上で利用可能なインストイラクション"Ciao.writeResponse(…)"が指定された場合


配列には2つのキーのエントリがそれぞれ格納されている：
    direction: MCUの観点からの振る舞いの方向性を"in"、"out"、"result"のいずれかの値で表現する
        "in": チャットメッセージやHTTPリクエストからの受け取りのような、"外界"からのインタラクションのために待機するコマンド
        "out": 外部への送信のみのチャットメッセージのような、メッセージ/データを送信しなくてはならないコマンド
        "result": リクエスト構築し（一旦実行後）レスポンス提供しなくてはならないコマンド
    has_params: この値は"true"もしく"false"のどちらかをセットすることが可能。パラメータがMCU Sketchによりread/write/writeResponseメソッドでコネクタへ渡されるかどうかを指定する

コネクタの開発方法

独自のコネクタを実装する場合、（OpenWRT上でインタプリタが提供される、もしくはコンパイル可能なものであれば）あなたが快適に使えるプログラミング言語を使うことができます。

新規コネクタを設計する場合、2つのインタラクションサイドに気をつけてください：

• TCP経由でCiao Coreをつかってのインタラクト（通常localhost上のポート番号10900番にてlisten）
• インタラクトを希望するアプリケーションもしくはプロトコルのハンドル

コネクタの登録

それぞれの使用可能なコネクタは - 一旦Ciao Coreに接続し - 登録文字列を送信しなくてはなりません。

（コネクタにより送信される）登録文字列
{
"action" : "register",
"name" : "samplecon"
}

Ciao Coreは - もし設定ファイルが適当に指定されているならば - "samplecon"コネクタのためにMCUから、そして"samplecon"コネクタからMCUへの受け取りを開始します。


Ciao Coreは登録メッセージへのどんな確認文字列も提供されません。もし何か間違っていた場合はコネクタへアドバイスするだけです。

コネクタ通信

コネクタと Ciao Core の間の通信はJSON文字列を使って合意しなくてはなりません。

Ciao ライブラリはトンネルのように行動し、順序やフォーマットを維持してコネクタから送信されるものはなんでもMCUへフォワードされます。

MCUへ何かを送信したい場合、TCPで送るための位置配列で構成される"data"キーを含んだシンプルなJSON文字列を記述します：

（MCUを狙った）Ciao Coreへのメッセージ
{
"data": ["param1", "param2"]
}

もし Ciao Core がそのようなメッセージを受け入れるならば、"status"文字列を返信します：

Ciao Coreからのレスポンス
{
  "status": 1,
  "checksum": "alphanumeric-25char-ID"
}

Ciao Coreの各インタラクションは、オペレーションを明確にするための一意なアルファベット25文字のID(alphanumeric-25char-ID)を持っています。そしてコレはCiao Core(やコネクタ)が各メッセージのトラックやリファレンスの保持を許可します。

サードパーティアプリ/プロトコルのハンドリング

（例えばTwitterなどの）サードパーティアプリケーションや（例えばHTTP、XMPP、MQTTなどの）プロトコルとの相互接続はあなた好みのデザインパターンで開発することができます。


以下の項目を推奨します：

• 可能な限り軽量/高パフォーマンスなコードを維持すること
• 知識共有のために簡単なコメントを記載すること
• (維持を簡単にするために)パラメータをハードコードする代わりに外部設定ファイルを使用すること

既に使用可能なライブラリ群

ciaoTools - Python

ciaoToolsライブラリは、Pythonを使って新規コネクタ開発を簡単にするためのものです。このライブラリはCiaoCoreとの通信をハンドルするスレッドを実装します。開発者はこのライブラリをインポートし、幾つかのメソッドをオーバライドした新規クラスをビルドする必要があります。

------

nameだけでなくenabledもきちんとセットしないと自分でPythonコネクタを操作しないといけなかったりするのか..

それにOpenWRT、実際はLininoOS最新版になるけど、上で10900が既に使われている状態ってことも、こころにとめておかないとなあ..


結構重要なこと書かれているなあ..