Getting Started(Arduino, ESP8266, mbed)

こちらはArduino、ESP8266(日本国内ではESP-WROOM-02という商品名で取り扱われています)、mbedでMilkcocoaを使う方法になります。

なお、想定しないアプリケーションからの不正なアクセスを遮断するために、管理画面の「認証」ページの「認証済みクライアント以外を接続不可にする」をONにする必要があるため(デフォルトの設定でON)、API Key認証を必ず行って利用してください。

※こちらを始める前に、チュートリアルのこのページを参考にMilkcocoaに登録、アプリの作成、app_idの確認、API KeyとAPI Secretの生成を行っておいて下さい。

導入方法

Arduino, ESP8266, mbed、いずれもC/C++のライブラリになっており、APIの利用方法も統一されています。

mbedの場合

※追記(2015/12/16):こちらのSDKは、jksoftさんに作って頂きました!

以下が、mbed LPC1114FN28にWi-FiモジュールとGroveコネクタを拡張するためのボードであるSimple IoT Boardですぐに試すことが出来るサンプルになります(動作確認済み)。

main.cppWLAN_SSIDWLAN_PASSMILKCOCOA_APP_IDを書き換えて書き込めば、Milkcocoaへのpush()が確認出来ます。

現在は、mbed+ESP8266(WiFi)、mbed+有線LAN(Ethernet)に対応しています。

ESP8266に直接プログラムを書き込む場合

※追記(2015/12/16):従来のMilkcocoa Arduino SDKを、従来通りのESP8266に直接プログラムを書き込む場合のSDK(ESP8266 SDK)と、新しく追加したArduinoからESP8266のATコマンドを使う場合のSDK(Arduino SDK)にわけました。

ESP8266に直接プログラムを書き込む場合は以下のSDKになります。

ESP8266にArduino IDEでプログラムを書き込めるようにする

こちらの記事(ESP8266やArduinoでMilkcocoaを使う方法(Milkcocoa Arduino SDK))の「Arduino IDEでESP8266を使えるようにする」のセクションを参考に、Arduino IDEでESP8266へプログラムを書き込めるようにして下さい。

GithubレポジトリからZipでダウンロードする

SDKを作業用パソコンにダウンロードします。以下のGithubリポジトリを開き、右のほうにある「Download ZIP」ボタンをクリックして保存します。

ライブラリのインストール

ダウンロードが終わったら、Arduino IDEの「スケッチ」 > 「Include Library」 > 「Add ZIP Library...」をクリックします。

ファイル選択画面が開かれるので、先ほどダウンロードしたZIPファイルを選択して読み込みます。

これでインストール完了です。「スケッチ」 > 「Include Library」の中に「Milkcocoa ESP8266 SDK」が追加されていれば、インストール成功です。

※現在はZIPでダウンロードしてライブラリをインストールするかたちですが、このSDKがArduinoライブラリに登録されれば「スケッチ」 > 「Manage Libraries」から直接インストールできるようになります。登録申請が通り次第、こちらの方法は更新します。

ArduinoからESP8266のATコマンドを使う場合

ArduinoからESP8266のATコマンドを使う、つまり、ESP8266への書き込みは一切行わず、ArduinoにESP8266と通信するプログラムを書き込んで利用する方法です。この場合は以下のSDKになります。

導入方法はESP8266 SDKと同様、GithubレポジトリからZIPをダウンロードしてインストールします。ただ、Arduino SDKとESP8266 SDKの両方をインストールしてしまうとライブラリ名が競合してしまうので、片方のみをインストールした状態でお使い下さい。

SDKの使い方

使い方を説明します。といっても、現在できることは以下の3つです(2015/10/22現在。他のメソッドについては、随時追加していきます)。

  • send():データの送信
  • push():データの送信&保存
  • on()send()push()の監視

まずはMilkcocoaオブジェクトを作成するための情報です。

#define MILKCOCOA_APP_ID      "...YOUR_MILKCOCOA_APP_ID..."
#define MILKCOCOA_DATASTORE   "esp8266"

#define MILKCOCOA_SERVERPORT  1883

const char MQTT_SERVER[] PROGMEM    = MILKCOCOA_APP_ID ".mlkcca.com";
const char MQTT_CLIENTID[] PROGMEM  = __TIME__ MILKCOCOA_APP_ID;

必ず変更する必要があるのはMILKCOCOA_APP_IDの部分だけです。必要に応じてMQTT_CLIENTIDMILKCOCOA_DATASTOREも変更して下さい。

milkcocoaオブジェクトを作成します。

// 'client'は、Ethernet or WiFiのClient (mbedでは'ipstack')
Milkcocoa milkcocoa = Milkcocoa(&client, MQTT_SERVER, MILKCOCOA_SERVERPORT, MILKCOCOA_APP_ID, MQTT_CLIENTID);

続いて、send()push()の方法です。

loop(){
  // 以下をloopの中で必ず実行します
  milkcocoa.loop();

  // データ格納用のオブジェクトです
  DataElement elem = DataElement();

  // 以下のようにkey, valueを設定していきます。
  elem.setValue("name", "Milk");
  elem.setValue("age", 35);

  // データストア名を指定して、データをpushもしくはsendします
  milkcocoa.push(MILKCOCOA_DATASTORE, elem);
  // or
  milkcocoa.send(MILKCOCOA_DATASTORE, elem);
}

on()は以下のように使います。

void setup() {
    // on()はsetup()内で呼び出します。onpush()にpushされたときの処理を書きます。
    milkcocoa.on("datastore name", "push", onpush);
    // or
    milkcocoa.on("datastore name", "send", onsend);
}
void loop() {
 // ...
}
void onpush(DataElement elem) {
  // 受け取ったデータを取り出すときは、getStringやgetIntなど型によって関数を使い分けます。
  Serial.println(elem.getString("name"));
  Serial.println(elem.getInt("age"));
  // 出力結果:
  // Milk
  // 35
}
// or
void onsend(DataElement elem) {
  // ...
}

API Keyによるデバイスの認証

※10/27より「API Key認証」を利用できるようになりました。前のバージョンを既にインストールしている方は、お手数ですが~/Documents/Arduino/libraries/にあるMilkcocoa SDKをフォルダごと削除して、リポジトリから再度ダウンロード&インストール頂ければと思います。

使い方は、milkcocoaオブジェクトを作成する際のコードを、Milkcocoaアプリの管理画面で生成したAPI KeyAPI Secretを使って以下のように書くだけです。

API Key認証無し
Milkcocoa milkcocoa = Milkcocoa(&client, MQTT_SERVER, MILKCOCOA_SERVERPORT, MILKCOCOA_APP_ID, MQTT_CLIENTID);
API Key認証有り
Milkcocoa *milkcocoa = Milkcocoa::createWithApiKey(&client, MQTT_SERVER, MILKCOCOA_SERVERPORT, MILKCOCOA_APP_ID, MQTT_CLIENTID, "API_Key", "API_Secret");

milkcocoaオブジェクトがポインタになるので、メソッドの呼び出しが.から->milkcocoa.push()ではなくmilkcocoa->push())になることに注意しましょう。

API KeyとAPI Secretの生成は、「アプリの管理画面」 > 「認証」 > 「API Key認証」の「新しいAPI KeyとAPI Secretのペアを生成する」からできます。

認証を行ったら、以下のようなことが実現できます。

  • 管理画面の「認証済みクライアント以外を接続不可にする」をONにすることで、認証していないクライアントの接続を受け付けないようにする。(デバイス制御等で、特定のデバイスだけでMilkcocoaを利用したい場合等)
  • セキュリティルール内で、API Keyをaccount.keyで取得できるため、それを使ったアクセス制御(そのデバイスからのみ保存を受け付ける等)

使い方は以上です。実際に使う場合は、具体的な実装例を自分用にカスタマイズするのが間違いもなく利用できて良いかと思います。