メッセージ仕様

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

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言語における型 型指定子 JSONにおける例
符号あり32bit整数 int32_t i -123456789
符号なし32bit整数 uint32_t I 123456789
符号あり64bit整数 int64_t l -123456789
符号なし64bit整数 uint64_t L 123456789
32bit浮動小数点数 float f 3.141592
64bit浮動小数点数 double d 3.141592
8バイトの配列 byte[8] b "0123456789abcdef" (16進数文字列)

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

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 大まかな誤差を示します。単位はメートルです。

gpio形式

モジュールがGPIOモードで動作している場合、gpio形式のメッセージが送信されるようになり、channels形式のJSONデータは送信されなくなります。

GPIOモードで動作しているモジュールのピンは、起動時には入力ピン(High-Z)として動作します。

入出力の切替え操作と、出力モードとなっているピンの出力値変更はプラットフォーム側から行う必要があり、本メッセージ形式による指示が必要となります。

GPIOモードの設定はモジュールごとに行う必要があり、モジュールが再起動されると設定値はリセットされます。 onlineメッセージ等で再接続を検出した場合には適切に再設定を行ってください。

また、入力モードとなっているピンに入力されている信号が変化した場合、信号の立ち上がりと立ち下がりで本メッセージ形式により通信モジュールからピンの状態が報告されます。

注意事項

安易にGPIOモードを用いず、本モジュールとは別にMCUを用いて制御を行うことを推奨します。

信号変化後の到達時間や、信号変化間隔通りの到達間隔の保証はされません。 また、通信回線状態やキューの開き具合によるデータ破棄がありうるため、確実な到達は保証されません。

データが到達しなかった場合にも問題が生じないように全体をユーザ側で設計する必要があります。

メッセージ構造(連携サービス→モジュール方向)

typeは gpio とし、モジュールに対してピンの出力値変更やモード変更を指示する場合には操作対象のモジュールIDを指定してください。

本メッセージは、連携サービスに対して送出する際とモジュールから送出された

例としてGPIOモード設定時に用いるJSON形式のメッセージを示します。 本形式に従ったJSONメッセージをIncoming WebhookやWebsocket等の連携サービスからモジュールに対して送出することで、モジュール側で自動的に設定変更が行われます。

{
    "type": "gpio",
    "module": "uXXXXXXXXXX",
    "payload": {
        "gpio": [
            {"pin": 0, "mode": "output", "value": 0},
            {"pin": 1, "mode": "output", "value": 1},
            {"pin": 2, "mode": "input", "value": 0},
            {"pin": 3, "mode": "input", "value": 1},
        ]
    }
}

payload以下に含まれる {"pin": 0, "mode": "output", "value": 0} 部が実際にモジュールに割り当てられる設定の記述となります。 フィールドの意味と、モジュール起動時の初期値は以下の通りです。

フィールド名 初期値 値の意味
payload Object    
payload.gpio Array    
payload.gpio.pin Int   操作対象のピン番号。
payload.gpio.mode String input ピンの動作モード。 input を指定した場合、pinで操作対象としたピンは入力モードとなり、 output を指定した場合は同じように対象のピンが出力モードとなります。
payload.gpio.value Int 0 ピンの動作モードがoutputの場合にピンから出力される値を指定します。 0 を指定した場合、pinで操作対象としたピンからはLowが出力され、 1 が指定された場合にはHighが出力されます。動作モードがoutput以外の場合、この値は無視されます。

メッセージ構造(モジュール→連携サービス方向)

GPIOモードで動作しているモジュールのピンの状態が変化した場合、gpio形式メッセージがモジュールから連携サービス方向に送出されます。

モジュールからGPIO形式メッセージが送出されるタイミングは以下の通りです。

  • 接続確立直後

  • 入力モードになっているピンに対して、入力されている信号が変化した場合(Low→High、High→Low)

  • モジュールが連携サービス側からのGPIO形式メッセージを受信した場合

    • 出力モードとなっているピンに対して、出力値の変更を指示し、変更が反映された場合
    • ピンの入出力モード変更を指示し、変更が反映された場合

また、入力モードとなっているピンへの入力値が変わった場合や、GPIO形式メッセージを送出した事によるモジュール側での設定変更が反映された場合に、結果の通知として同一形式のメッセージがモジュールから送出されます。

メッセージ構造については連携サービス→モジュール方向と同じJSON形式のメッセージを使用しますが、一部フィールドの意味が異なります。 モジュール→連携サービス方向のGPIO形式メッセージの各フィールドの意味は以下の通りです。

フィールド名 値の意味
payload Object  
payload.gpio Array  
payload.gpio.pin Int 対象のピン番号。
payload.gpio.mode String 対象ピンの動作モード。
payload.gpio.value Int ピンの動作モードがoutputの場合にはピンから出力している値が格納され、動作モードがinputの場合にはピンに入力されている値が格納されます。入力モードがいずれの場合にも、本フィールドの値が 0 の場合には対象ピンの値がLow、 1 の場合には対象ピンの値はHighとなります。

keepalive形式

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

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

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

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