メッセージ仕様 ¶

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

メッセージ仕様

channels形式 ¶

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

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

データ送信時(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から、sakura.ioモジュールを介してデバイスへコマンドを送信する際には、下記のような形で送信してください。

{
    "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の場合を途絶を示します。

Note

is_onlineは、通信モジュールとプラットフォーム間の定期的な疎通確認により判定しています。疎通確認の合間の短時間での切断・接続となった場合は、切断を検知できず、is_online: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"
}