メッセージ仕様

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

channels形式

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

channelsメッセージ構造(さくらの通信モジュール → プラットフォーム)

データ送信時(さくらの通信モジュール → プラットフォーム)の 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

moduleはデータを送信した通信モジュールが一意に持つモジュールIDを示します。 以降で登場する他の形式のメッセージにおいても同様です。

type

typeはデータがどの形式のデータであるかを示します。 以降で登場する他の形式のメッセージにおいても同様です。

datetime

datetimeは通信モジュールからこのメッセージが送られた日時を示します。 以降で登場する他の形式のメッセージにおいても同様です。

payload

channels形式のpayloadにはデバイス側の通信モジュールから受信したメッセージデータが格納されています。 payloadのvalueはまず配列を持つchannelsオブジェクトが格納されています。

payload.channels

payload.channelsには配列として実際のデータが最大16個格納されています。 配列の中は連想配列になっており、以下のkeyとvalueで構成されています。

payload.channels.channel

payload.channels.channelはマイコンが通信モジュールにデータを格納する際に指定したチャンネルが格納されています。 特定のデータを特定のチャンネルに格納するよう設計することで、任意のデータを連続して取り出すことができるようになります。 外部のサービス側でデータを受け取ったり、返したりする際にこちらの値を指定します。

payload.channels.type

payload.channels.typeはマイコンが通信モジュールにデータを格納する際に指定したデータの型指定子が格納されています。

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

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

payload.channels.value

payload.channels.valueはマイコンが通信モジュールにデータを格納する際に指定したデータの値が格納されています。

payload.channels.datetime

payload.channels.datetimeはマイコンが通信モジュールにデータを格納した時間が格納されています。

注意事項

以下の項目は他のメッセージでも同様となるため、記載を割愛します。

  • module
  • type
  • datetime

channelsメッセージ構造(プラットフォーム → さくらの通信モジュール)

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

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

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

payload.channels

payload.channelsには配列として実際のデータが最大16個格納可能です。 配列の中は連想配列になっており、以下のkeyとvalueで構成する必要があります。

payload.channels.channel

payload.channels.channelはマイコンがデータを受信する際に指定されるチャンネルの情報を格納します。 デバイスのマイコン等で受信したチャンネルや値に応じたプログラムを設計することで、任意の動作を実行させる事ができます。

payload.channels.type

payload.channels.typeはマイコンが通信モジュールから受け取るデータの型指定子が格納されています。

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

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

payload.channels.value

payload.channels.valueはマイコンが通信モジュールから受け取るデータの値が格納されています。

connection形式

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

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

connectionメッセージ構造(通信が開始された場合)

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

{
	"module": "uXXXXXXXXXXX",
	"type": "connection",
	"datetime": "2017-04-06T07:39:29.703232943Z",
	"payload": {
		"is_online": true
	}
}

payload

connection形式のpayloadにはプラットフォーム側からの接続に関するメッセージが格納されています。 payloadのvalueには通信開始もしくは通信途絶を表すis_onlineオブジェクトが格納されています。

payload.is_online

is_onlineは通信モジュールの通信の開始もしくは途絶を示します。

通信が開始された場合、is_onlineパラメータはtrueで返されます。

connectionメッセージ構造(通信が途絶された場合)

電源断等の理由により通信モジュールからの通信が途絶した場合、is_onlineパラメータはfalseで返されます。

{
	"module": "uXXXXXXXXXXX",
	"type": "connection",
	"datetime": "2017-04-06T07:46:36.005341001Z",
	"payload": {
		"is_online": false
	}
}

location形式

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

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

locationメッセージ構造(基地局が特定できる場合)

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

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

payload

location形式のpayloadにはプラットフォーム側で算出した位置情報に関するメッセージが格納されています。 payloadのvalueには位置情報を示すcoordinateオブジェクトが格納されています。

payload.coordinate

payload.coordinateは通信モジュールが送られた基地局情報を元に算出された位置情報が含まれます。

payload.coordinate.latitude

payload.coordinate.latitudeは通信モジュールが送られた基地局情報を元に算出された緯度情報を示します。

payload.coordinate.longitude

payload.coordinate.longitudeは通信モジュールが送られた基地局情報を元に算出された経度情報を示します。

payload.coordinate.range_m

payload.coordinate.range_mは緯度経度情報の大まかな誤差を示します。メートル単位で記載されており、小さいほど精度が高いことを示します。

locationメッセージ構造(基地局が特定できない場合)

基地局がデータに存在しない等の理由により基地局が特定できない場合、coodinateパラメータはnullで返されます。

{
    "datetime": "2017-04-04T01:31:19.6431197Z",
    "module": "uXXXXXXXXXXX", 
    "type": "location",
    "payload": {
        "coordinate":null
        }
    }
}

keepalive形式

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

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

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

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