Arduino "Ciao MCU" を翻訳してみた

今度はCiaoライブラリ、Sketch側でどうCiaoライブラリを呼び出すか
が書かれている

Ciao MCU
http://labs.arduino.org/Ciao%20MCU

を翻訳してみました。

以下、at your own risk で参考のこと。

-----

Ciao MCU

イントロダクション

Ciaoライブラリは、シリアル通信経由で、シンプルで直感的な方法により、マイクロコントローラ外部へのデータ送受信を許可します。CiaoライブラリはSketch上で使用することのできる3つの主な関数を提供します：

 

• read(connector)
• write(connector, param1, param2, param3) 
• writeResponse(connector, id, param1, param2, param3)

これらの関数に加えて、便利なCiaoData、管理のためのユーティリティ機能、データの取得および操作を提供します。
 

• get(index)
• isError()
• isEmpty()

Ciaoライブラリを使うためには以下の作業が必要です：
 

1. Ciaoライブラリのインポート
2. 関数begin()による初期化

注意：Ciaoライブラリを使う前に、Sketchで使うコネクタをenableにする必要があります、そしてそれは時々設定を行う必要があります。コネクタの有効にする方法とコネクタリストを読んでコネクタのセットアップ方法を学習してください。

read

関数readはコネクタからのデータ受け取りを可能にします（例：xmpp、websocket、twitter）。コネクタにより提供されたIDやデータで構成されるCiaoDataオブジェクトで返却されます。
関数getによりCiaoDataオブジェクトから様々なフィールド値の取得が可能です(関数getを参照のこと）。


例

xmppコネクタからデータ取得する場合、このようなシンプルなステップが必要になります：

#include

setup{
    Ciao.begin()
}

loop{
    CiaoData data;
    data = Ciao.read("xmpp"); // xmpp connectorへ問い合わせ
}

write

関数writeはボードからコネクタへデータ送信を可能にします。4つのパラメータまで認められており、最初のパラメータは常に相互通信したいコネクタのタイプです。その他のパラメータは異なる利用ケースにより自由に使用されることがあります。

例：

xmppコネクタへ送信データを送る場合、関数writeのパラメータは次のようになります：
 

• 最初のパラメータは、コネクタタイプ
• 2番めのパラメータは、 送信先名
• 3番めのパラメータは、送信メッセージ

#include

setup{
    Ciao.begin();
}

loop{
    Ciao.write("xmpp","user@xmpp","hello from MCU");
}

writeResponse

関数writeResponseはコネクタにより送信したリクエストのリプライを直接受け取ることができます。最大5つのパラメータまで指定でき、最初のパラメータは常に相互通信したいコネクタタイプ、2番めのパラメータはレスポンスを送りたいID値を常に指定します。その他のパラメータは異なる利用ケースにより自由に使用されることがあります。

例：

直前のxmppリクエストのレスポンスを受け取る場合、関数writeResponseのパラメータは次のように指定します：
 

• 最初のパラメータは、コネクタタイプ
• 2番めのパラメータは、xmppリクエストのID
• 3番めのパラメータは、送信メッセージ

#include

setup{
    Ciao.begin();
}

loop{
    CiaoData data;
    data = Ciao.read("xmpp"); // xmpp connectorへの問い合わせ
    String id = data.get(0);
    String sender = data.get(1);
    String message = data.get(2);

    Ciao.writeResponse("xmpp",id,"response from MCU");
}

get

関数getはCiaoData内部から情報を取り出すことを許可します。この情報は使用されるコネクタタイプにより様々です。

関数はたった1つだけのパラメータ、コネクタ内でセットされたデータフォーマットの位置(インデックス)のみ受け取ります

例

XMPPコネクタのCiaoDataは普通、ID（インデックス"0"）、送信者（インデックス"1"）、そしてメッセージ（インデックス"2"）となります。

情報を取り出すには、以下の様なステップでおこないます：

#include

setup{
    Ciao.begin()
}

loop{
    CiaoData data;
    data = Ciao.read("xmpp"); // xmpp connector への問い合わせ
    String id = data.get(0);  // CiaoData から情報取得
    String sender = data.get(1);
    String message = data.get(2);
}

splitString

関数splitStringは、コネクタへ送信するMCUコマンドを管理するために使用します。

関数は最大4つまでパラメータを受け取ります、最初のパラメータはMCUのシリアルコマンド、2番めのパラメータはシリアルコマンドを分割するために使用されるキャラクタ、3番めと4番めのパラメータはそれぞれ受信シリアルコマンドを分割した配列と（配列の）サイズです。


例

もしxmppコネクタにより、"digital/13/1"のように、3つのパラメータが送信された場合、コマンドを分割するためにまず3つの要素文字列を作成する必要があります、その後関数splitStringを呼び出します：

#include

void setup() {
     Ciao.begin();
     Serial.begin(57600);
}

void loop() {
     CiaoData data = Ciao.read("xmpp");
     String id = data.get(0);
     String sender = data.get(1);
     String message = data.get(2);
     String command[3];
     splitString(message,"/",command,3);
     Serial.println("command type: "+command[0]); //アウトプットはdigital
     Serial.println("pin: "+command[1]); //アウトプットは13
     Serial.println("pin value: "+command[2])); //アウトプットは 1
}

isError

関数isErrorはCiaoDataオブジェクトにエラーコードが含まれているかチェックすることができます。
CiaoData無いにエラーコードが存在する場合、関数は真値を返却します。


例

xmppコネクタからの受信データ内にエラーコードが存在するかどうかチェックします。

#include

void setup() {
    Ciao.begin();
    Serial.begin(57600);
}

void loop() {
    CiaoData data = Ciao.read("xmpp");  
    if(data.isError()){
      String message = data.get(2);
      Serial.println(" error:"+ message);
    }
}

isEmpty

関数isEmptyはCiaoDataオブジェクトが空かどうかをチェックすることができます。

関数はCiaoDataが空かどうか真偽値を返却します。

例

オブジェクトが空でなければ、CiaoDataオブジェクト内の情報を取り出す。

#include

void setup() {
    Ciao.begin();
    Serial.begin(57600);
}

void loop() {
  CiaoData data = Ciao.read("xmpp");
  if(!data.isEmpty()){
      String id = data.get(0);
      String sender = data.get(1);
      String message = data.get(2);
      Serial.println("id: "+id);
      Serial.println("sender: "+sender);
      Serial.println("message: "+message);
    }
}

----

小難しい部分は全部Ciao Coreへ分離しただけあってライブラリ側の簡単なこと..