メッセージ仕様

ここでは、連携サービスからやり取りされるメッセージ形式について記載します。

channels形式

さくらの通信モジュールからメッセージデータとしてやり取りされるデータはchannels形式のJSONデータが使用されます。 Typeがchannelsのデータは以下のようなメッセージ形式で構成されています。

メッセージ構造 (sakura.io→外部サービス)

データ送信時(さくらの通信モジュール → プラットフォーム)の channelsメッセージの構造は以下となります。個々のパラメータについては以下に記載します。

{
    "module": "uXXXXXXXXXXX",
    "type": "channels",
    "datetime": "2017-04-06T07:46:36.005341001Z",
    "payload": {
        "channels": [{
            "channel": 0,
            "type": "I",
            "value": 0,
            "datetime": "2017-04-06T07:39:29.703232943Z"
        }, {
            "channel": 0,
            ...
            ..
            .
        }]
    }
}
フィールド名 意味
module String データを送信した通信モジュールが一意に持つモジュールIDを示します。
type String データがどの形式のメッセージであるかを示します。
datetime String 通信モジュールからこのメッセージが送られた日時を示します。
payload Object 通信モジュールから受信したメッセージデータが格納されています。
payload.channels Array データが配列内に最大16個格納されています。
payload.channels[].channel Int チャンネル番号が格納されています。
payload.channels[].type String データの 型指定子 が格納されています。
payload.channels[].value Int or String 値が格納されています。
payload.channels[].datetime String 時間が格納されています。
Note

特定のデータを特定のチャンネルに格納するよう設計することで、外部サービスと連携が行いやすくなります。

例: 温度は常に1Chで送信・湿度は常に2Chで送信。

メッセージ構造 (外部サービス→sakura.io)

プラットフォームのAPIから、さくらの通信モジュールを介してデバイスへコマンドを送信する際には、下記のような形で送信してください。

{
    "type": "channels",
    "module": "uXXXXXXXXXXX",
    "payload": {
        "channels": [{
            "channel": 0,
            "type": "i",
            "value": 0
        }, {
            "channel": 0,
            ...
            ..
            .
        }]
    }
}

コマンド送信時には、datetimeの指定は不要で、module、typeのみを指定します。

フィールド名 意味
module String データの宛先である通信モジュールが一意に持つモジュールIDを示します。
type String データがどの形式のメッセージであるかを示します。
payload Object 通信モジュールから受信したメッセージデータが格納されています。
payload.channels Array データが配列内に最大16個格納されています。
payload.channels[].channel Int チャンネル番号を格納します。
payload.channels[].type String データの 型指定子 を格納します。
payload.channels[].value Int or String 値を格納します。
payload.channels[].datetime String 時間を格納します。

型指定子

C言語における型 型指定子
符号あり32bit整数 int32_t i
符号なし32bit整数 uint32_t I
符号あり64bit整数 int64_t l
符号なし64bit整数 uint64_t L
32bit浮動小数点数 float f
64bit浮動小数点数 double d
8バイトの配列 byte[8] b

大文字と小文字で型指定子の意味は異なりますのでご注意ください。また、小数点数については符号なしが存在しません。

connection形式

通信モジュールが起動した際、および通信が途絶した場合、connection形式のJSONメッセージが送信されます。

Typeがconnectionのメッセージデータは以下のような構造となります。

メッセージ構造

例として通信モジュールが起動した場合に送信されるconnectionメッセージの構造を以下に示します。

{
    "module": "uXXXXXXXXXXX",
    "type": "connection",
    "datetime": "2017-04-06T07:39:29.703232943Z",
    "payload": {
        "is_online": true
    }
}
フィールド名 意味
payload Object 通信モジュールから受信した接続に関するメッセージが格納されています。
payload.is_online Bool Trueの場合通信の開始・Falseの場合を途絶を示します。

location形式

簡易位置情報提供機能を利用している場合、location形式のJSONデータが通常のメッセージに併せて送信されます。簡易位置情報とは、メッセージが送られた基地局情報を元に弊社が算出したものとなります。

Typeがlocationのメッセージデータは以下のような構造となります。 基地局が特定できる場合、特定できない場合によりメッセージの中身が変わります。

メッセージ構造

基地局が特定できた場合に送信されるlocationメッセージの例を以下に示します。個々のパラメータについては以下に記載します。

{
    "datetime": "2017-04-04T01:31:19.6431197Z",
    "module": "uXXXXXXXXXXX", 
    "type": "location",
    "payload": {
        "coordinate": {
            "latitude": 0.000000, 
            "longitude": 0.000000, 
            "range_m": 0
        }
    }
}

基地局がデータに存在しない等の理由により基地局が特定できない場合の例を示します。

{
    "datetime": "2017-04-04T01:31:19.6431197Z",
    "module": "uXXXXXXXXXXX", 
    "type": "location",
    "payload": {
        "coordinate": null
    }
}
フィールド名 意味
payload Object 通信モジュールから受信した接続に関するメッセージが格納されています。
payload.coordinate Object 基地局情報を元に算出された位置情報が含まれます。
payload.coordinate.latitude Float 緯度情報を示します。
payload.coordinate.longitude Float 経度情報を示します。
payload.coordinate.range_m Int 大まかな誤差を示します。単位はメートルです。

keepalive形式

WebSocketなどコネクションを維持する必要のある連携サービスでは、プラットフォームと連携先システム間でのコネクション維持のためにkeepaliveメッセージを送信するものがあります。

type がkeepaliveであるデータは、直接お客様のサービスに関係するものではないため、無視していただいても問題ありません。

keepaliveメッセージ構造を以下に示します。

{
    "type": "keepalive",
    "datetime": "2017-05-02T10:36:51.231263947Z"
}