Arduino/C++でAmbientにデーターを送信するライブラリーです。プログラムサンプルは「Arduino ESP8266で温度・湿度を測定し、Ambientに送ってグラフ化する」の「プログラム」を、ライブラリーのインストール方法は同じページの「Ambientライブラリーのインポート」をご覧ください。

Ambient::begin()

説明

Ambientの初期化(使う準備)をします。

構文

#include “Ambient.h”
bool Ambient::begin(unsigned int channelId, const char * writeKey, WiFiClient * c[, const char * readKey]);

引数

unsigned int channelId;         // データーを送信するチャネルのチャネルId
const char * writeKey;          // ライトキー
WiFiClient * c;                 // WiFiClientのポインター
const char * readKey;           // リードキー（オプション）

戻り値

true: 成功
false: 不成功

Ambient::set()

説明

Ambientに送信するデーターをパケットに設定します。Ambientでは8種類までのデーターを送信できます。set()は何種類目のデーターかを示す数値とそのデーターを指定します。

構文

#include “Ambient.h”
bool Ambient::set(int field, char * data);
bool Ambient::set(int field, int data);
bool Ambient::set(int field, double data);

引数

int field;       // 何種類目のデーターか示す数値。1から8が指定できます。
char * data;          // 送信する数値を文字列にしたもの。
int data;             // 数値はintまたはdouble型で渡すこともできます。
double data;

戻り値

true: 成功
false: 不成功

Ambient::setcmnt()

説明

Ambientにデータを送信する際にコメントを付けて送ることができます。詳しくは「リストチャート、表示/非表示の制御、コメント」をご覧ください。

構文

#include “Ambient.h”
bool Ambient::setcmnt(const char * cmnt);

引数

const char * cmnt;    // コメントの文字列

戻り値

true: 成功
false: 不成功

Ambient::clear()

説明

パケットに設定したデーターを消去します。Ambient::send()またはAmbient::bulk_send()で
データーを送信した後は、設定したすべてのデーターは消去されます。

構文

#include “Ambient.h”
bool Ambient::clear(int field);

引数

int field;        // 何種類目のデーターかを指定します。1から8が指定できます。

戻り値

true: 成功
false: 不成功

Ambient::send()

説明

begin()で指定したチャネルにset()で設定したデーターを送信します。Ambientはデーターを受信した時刻をデーターの生成時刻として記録します。送信後、パケットに設定したデーターは消去されます。また、送信後、AmbientサーバーからのHTTPステータスコードがAmbient::statusにセットされます。

構文

#include “Ambient.h”
bool Ambient::send([uint32_t tmout]);

引数

uint32_t tmout;  // サーバー接続のタイムアウト値（ミリ秒）。省略時は30秒

戻り値

true: 成功
false: 不成功

Ambient::bulk_send()

説明

begin()で指定したチャネルに複数件のデーターをまとめて送信します。データーは下記に示すJSON形式で渡し、データーの中に生成時刻を含める必要があります。送信後、AmbientサーバーからのHTTPステータスコードがAmbient::statusにセットされます。

構文

#include “Ambient.h”
int Ambient::bulk_send(char * buf[, uint32_t tmout]);

引数

char * buf;      // データーへのポインター
uint32_t tmout;  // サーバー接続のタイムアウト値（ミリ秒）。省略時は30秒

データーは次のような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″のいずれかを指定します。

さらに、次のように“time”: 1 を指定すると、数値は「秒(協定世界時(UTC)の1970年1月1日00:00:00からの)」として扱われます。“YYYY-MM-DD HH:mm:ss.sss”という形式の場合は“time”: 1を指定しても無視します。

    {
        “writeKey” :  “ライトキー”,
        “data” : [
            {“created” : 数値, “time” : 1,  “d1” : “値”, “d2” : “値”, ...},
            {“created” : 数値, “time” : 1,  “d1” : “値”, “d2” : “値”, ...},
            ...
            {“created” : 数値, “time” : 1,  “d1” : “値”, “d2” : “値”, ...}
        ]
    }

戻り値

実際に送信できたバイト数が返されます。

Ambient::read()

説明

begin()で指定したチャネルからデーターを受信します。受信データは、次のようなJSON形式の文字列です。受信後、AmbientサーバーからのHTTPステータスコードがAmbient::statusにセットされます。

[{"d1": 値1, "d2": 値2, "d3": 値3, ..., "created": :"2021-04-02T00:32:42.334Z}]

構文

#include “Ambient.h”
bool Ambient::read(char * buf, int len[, int n[, uint32_t tmout]]);

引数

char * buf;      // データが返されるバッファ
int len;         // バッファのバイトサイズ
int n;           // 受信する件数。省略時は１
uint32_t tmout;  // サーバー接続のタイムアウト値（ミリ秒）。省略時は30秒

戻り値

true: 成功
false: 不成功

データの取り出し

read()で取得したデータはJSON形式の文字列なので、Arduino_JSONなどのライブラリを使って解析することもできますが、Ambientからのデータは単純な形式なので、1件のデータなら次のようにsscanf関数で値を取り出すこともできます。

char buf[128];
int d1, d2, d3;

ambient.read(buf, sizeof(buf));
sscanf(buf, "[{\"d1\":%d,\"d2\":%d,\"d3\":%d}]", &d1, &d2, &d3);

Ambient::delete_data()

説明

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

構文

#include “Ambient.h”
bool Ambient::delete_data(const char * userKey[, uint32_t tmout]);

引数

const char * userKey;       // ユーザーキー
uint32_t tmout; // サーバー接続のタイムアウト値（ミリ秒）。省略時は30秒

戻り値

true: 成功
false: 不成功

Ambient::getchannel()

説明

端末ごとの固有のキー（デバイスキー）を送り、対応するチャネルIDとライトキーを取得します。詳しくは「複数台のIoT端末を同一プログラムで動かす」を御覧ください。

構文

#include “Ambient.h”
bool Ambient::getchannel(const char * userKey, const char * devKey, unsigned int & channelId, char * writeKey, int len, WiFiClient * c[, uint32_t tmout]);

引数

const char * userKey;       // ユーザーキー
const char * devKey;        // デバイスキー
unsigned int & channelId;  // チャネルIDのアドレス
char * writeKey;                // ライトキー
int len;                                // ライトキーエリアのバイト数
uint32_t tmout; // サーバー接続のタイムアウト値（ミリ秒）。省略時は30秒

戻り値

true: 成功
false: 不成功