複数データーの一括送信機能 bulk_send()を実現しました

複数データーの一括送信機能

Ambientでは Ambient::send() という関数で1回に8種類までのデーターを送ることができます。今回追加した機能は複数回分のデーターをまとめてAmbientに送信する機能です。

    int Ambient::bulk_send(char * buf);

パラメーターとして、送信するデーターのポインターをchar *bufの形で渡します。戻り値は実際に送信できたバイト数です。データーは次のようなJSONフォーマットで渡します。

    {
        “writeKey” :  “ライトキー”,
        “data” : [
            {“created” : “YYYY-MM-DD HH:mm:ss.sss”, “d1” :  “値”, “d2” :  “値”, ...},
            {“created” : “YYYY-MM-DD HH:mm:ss.sss”, “d1” :  “値”, “d2” :  “値”, ...},
            ...
            {“created” : “YYYY-MM-DD HH:mm:ss.sss”, “d1” :  “値”, “d2” :  “値”, ...}
        ]
    }

“created”はデーターの生成時刻で、値は“YYYY-MM-DD HH:mm:ss.sss”という形式か、数値を渡します。数値を渡した場合は1970年1月1日00:00:00からのミリ秒と解釈されます。マイコンなどではミリ秒で扱うのが楽だと思います。 “created”の後にはデーターを”キー”:”値”という形式で並べます。キーは”d1″、”d2″、”d3″、”d4″、”d5″、”d6″、”d7″、”d8″のいずれかを指定します。

Arduinoとmbedのサンプルプログラムをそれぞれ公開しました。

C/C++でJSONフォーマットのデーターを作るライブラリーはいくつかあるようなので、 Ambientとしては提供しませんでした。サンプルプログラムでは次のようにJSONデーターを作りました。

    sprintf(buffer, "{\"writeKey\":\"%s\",\"data\":[", writeKey);
    for (int i = 0; i < NSAMPLES; i++) {
        sprintf(&buffer[strlen(buffer)], "{\"created\":%d,\"d%d\":%d},", SAMPLING * i, 2, signal[i]);
    }
    buffer[strlen(buffer)-1] = '\0';
    sprintf(&buffer[strlen(buffer)], "]}\r\n");

bulk_send()により、例えば数ミリ秒間隔でデーターをサンプリングしてメモリーに記録し、一括してAmbientに送信して波形をグラフ化して確認するような使い方ができるようになりました。

データー送信時の消費電力を減らすために複数回のデーターをまとめて送信することも bulk_send()で実現できます。ただし、send()はデーターを受信した時にAmbientが時刻を記録するので、マイコン側では時刻を管理する必要がありませんが、bulk_send()ではマイコン側で時刻を管理し、データーに時刻を含めて送信する必要があります。

データー削除

データーの一括送信と合わせて、チャネルに送信したデーターを削除するライブラリーも追加しました。

    bool Ambient::delete_data(const char * userKey);

Ambient::begin() (mbedではinit()) で指定したチャネルIDのチャネルに保存されたデーターを削除します。パラメーターとして const char * userKey を渡します。

delete_data()はチャネルに保存されたデーターを全て削除します。部分的に削除する機能はありません。 Ambientサイトのチャネルページの「データー削除」ボタンと同じ動作をします。チャネルそのものやチャネルの設定情報は削除されずに残ります。削除したデーターは復元できないので、注意してください。

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

Arduinoとmbedのライブラリーをbulk_send()、delete_data()が含まれたものに更新しました。

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

ArduinoライブラリーはGithubに公開しました。

Ambient_ESP8266_lib

インストール方法は「Arduino ESP8266で温度・湿度を測定し、Ambientに送ってグラフ化する」の説明をご覧ください。

既にAmbientライブラリーをお使いの方は、新しいライブラリーをインストールする前に、今お使いのライブラリーをご自分のArduinoライブラリーからディレクトリーごと削除する必要があるようです。 Arduinoライブラリーの場所は、Arduino IDEの環境設定メニューの「スケッチブックの保存場所」で示されるディレクトリーのlibrariesというディレクトリーの下です。

mbedライブラリー

mbedライブラリーはmbedサイトに公開しました。

AmbientLib

mbedサイトに公開しているサンプルプログラムのライブラリーも最新のものに更新したので、 mbedサイトからライブラリーなりプログラムなりをインポートすれば最新のライブラリーが使えるようになります。

既にAmbientライブラリーをお使いの方は、オンラインコンパイラーの「プログラムワークスペース」の「AmbientLib」を右クリックして、表示されたメニューの中から「アップデート…」を選択すると最新のライブラリーに更新されます。

制限の見直し

bulk_send()の機能追加に合わせて、制限も以下のように見直しました。

データーの送信間隔は最小5秒です。 send()、bulk_send()それぞれ5秒ではなく、send()→bulk_send()、あるいはbulk_send()→send()というように組み合わせて使った場合も、最小間隔は5秒です。
データーはチャネルごとに1日累積、最大3,000件まで登録できます (平均すれば28.8秒に1件登録できます)。 bulk_send()の場合、JSONデーターに含まれる時刻とデーターの組み{“created” : “時刻”, データー…}を1件と数えます。 JSONデーターに時刻とデーターの組みが3個含まれていれば、1回のbulk_send()コールで3件登録したとカウントされます。一つのチャネルにsend()とbulk_send()で登録した場合は、両方の登録件数が合計されます。
最大累積件数を超えて登録すると、最大累積件数まではデーターが登録され、それ以上のデーターは無視されて、エラー(413)が返されます。
データーの累積件数は0時にリセットされます。
累積件数を計算するときのデーターの日付は、apiをコールした日付が使われます。データーに付与された日付ではありません。
データー累積件数はデーターを削除しても減算されません。

また、データー送信以外の制限も明確にしました。今のところ次のような制限があります。

一つのアカウントで持てるチャネル数は最大8です。