SORACOM, INC.

User Console »
Documents

バイナリパーサー詳細

はじめに

バイナリパーサーとは SORACOM Air for LoRaWAN / Sigfox でご利用いただける、バイナリデータをJSONデータに変換する機能です。

バイナリパーサーを利用することにより、お客様は バイナリデータを SORACOM プラットフォーム上でJSON 形式にデコードして SORACOM Beam / Funnel / Harvest に送信いただくことができます。

バイナリパーサーフォーマット(以下、フォーマット)は特定のデバイスに対応した定義済みフォーマット(Predefined Format) と、ユーザーが指定できるカスタムフォーマット (Custom Format) があります。カスタムフォーマットは複数のデータ型と、四則演算に対応しています。

処理の流れ

バイナリパーサーを利用した場合、出力されたJSONにbinaryParserEnabled: trueという項目が追加されます。

定義済みフォーマット

定義済みフォーマットは、対応デバイスの仕様に応じて自動的にパースします。対応デバイスならびに、指定するフォーマット名は以下の通りです。

デバイス名 フォーマット 参考情報
Sens'it @sensit 利用例はブログ記事をご参照ください。

カスタムフォーマット

フォーマットは以下のような構文を持っています。

flag:0:bool:7 temp:1:int:13:/10 humid:3:uint:8:/100 lat::float:32 long:float:32

flag:0:bool:7 がひとつの値を表現しています。値はスペースで区切られます。
値の定義は複数の設定項目を持ち、それらはコロンで区切られています。
値の定義は下記のフォーマットで表現されています。

[変数名]:[バイト列のインデックス]:[変数の型]:[型に依存した設定内容]

以下に、それぞれの項目について解説していきます。

変数名

パースされた値が格納されるJSONオブジェクトのキーです。
変数名に使えるのは 数字、アルファベット、記号(#, -, _, $)です。

LoRa, Sigfox における既存の項目との衝突を防ぐため、それぞれのペイロードで使用されている以下の変数名は利用できません。

# LoRa
"date", "gatewayData", "data", "deveui"

# Sigfox
"device", "time", "station", "lat", "lng", "rssi", "data", "seqNumber", "data"

バイト列のインデックス

先頭から何バイト目を読むかを指定します。複数バイトを読むデータ型の場合は、読み始める最初のバイトを指定してください。先頭バイトを0として数えます。

変数の型

バイナリパーサーがサポートする型は以下のとおりです。

変数の型に依存した設定内容

各変数の型にはそれぞれ固有の設定があります。
それぞれの型ごとに、それを解説していきます。

bool

bool は真偽値です。対象バイトの 1bit を読み、1 であればtrue0 であればfalse を返します。設定項目は1つで、offset です。設定例:flag:0:bool:7

offset (必須)

offset は指定されたバイトのどの bit から読むかを指定します。
最上位ビットを読むには offset に 7 を指定します。0-7 までの値のいずれかを指定してください(下図参照)。

例) 0x9A (10011010b) に対する offset の例

int, uint

int は符号付き整数、 uint は符号なし整数です。設定項目は共通で、length,offset,operations です。

length (必須)

読み込む bit の長さを指定します。 1バイト読み込む場合は8 を指定します。
この長さによって、変数が取りうる値の範囲が決まります。
1 ~ 32 までの値を指定することができます。

offset (省略可、デフォルト 7 )

offset は指定されたバイトのどの bit から読むかを指定します。
10000000 というバイトがあった場合、先頭の 1 を読むには offset に 7 を指定します。
offset の値は 0-7 までの値のいずれかを指定してください。

例えば、 後半の 4 bit を符号なし整数として読みたい場合は、temp:0:uint:4:3 となります。
2バイトの後半10 bit を符号付き整数として読みたい場合は、temp:0:int:10:1 となります。(先頭バイトの後ろ 2 bit と次のバイトの 8 bit を読み込んでいます)

operations (省略可)

operations は読み込んだ値に対して演算するときに使います。
利用できる演算子は四則演算(+,-,*,/ )です。
演算子の優先順位はすべて同じで、シンプルな電卓を使ったときのように、左から順に計算していきます。(例)value:0:int:8:+10*2 という設定があって、value が 1 だった場合、値は  22 となります。1+10*2 = (1 + 10) * 2 = 22

演算子の上限は 5 です。割り算の場合、計算結果は浮動小数点数に変換されます。
例)11/10 = 1.1

省略された場合は、演算を行いません。

演算子と前の設定の間には他の設定と同様に: が必要です。忘れやすいので、気をつけて下さい。

float

float はIEEE 754 形式の浮動小数点数です。設定できる項目はlength,offset,operations です。

length (必須)

読み込む bit の長さを指定します。取りうる値は 32 または 64 です。
この長さによって、変数が取りうる値の範囲が決まります。

offset (省略可)

int, uint の offset と同様です。

operations (省略可)

int, uint の operations と同様です。

char

char はASCII文字です。1バイトで1文字を表現します。設定できる項目はlength です。

length (必須)

読み込む文字の長さ(=バイト数)を指定します。取りうる値は 1 ~ 8 です。

Advanced Tips

エンディアンネスについて

複数バイトを読む int や float はビッグエンディアンで読み込みます。
リトルエンディアンを利用したい場合はlength 設定の直後に:little-endian を付与します。

(例)value:0:float:64:little-endian

バイト列のインデックスの省略について

バイト列のインデックスは空欄にすることができます。(例)lat::float:32
空欄にした場合、最後に読んだバイトの次のバイトから読み始めます。先頭の項目の場合は先頭のバイトを読みます。例えば、value1::int:6 value2::int:8 という指定をした場合、value1 は先頭バイト(6bit を指定しているので、末尾 2bit は読まれません)、 value2 はその次のバイトを読みます。

bool が連続する場合は例外で、同じインデックスのバイトを読み続けます(※1, ※2)。
これによって、1バイトの中に複数の bool を詰め込むときの設定が簡潔になります。

(例)flagA:0:bool:7 flagB::bool:6 flagC::bool:5 value:0:int:4 は先頭 3 bit を bool に、その後の 5 bit を int として読み込みます。

※1. 8個以上 bool を連続させてもインデックスは進みません。
※2. bit の offset は必ず指定する必要があります。

設定方法

LoRa グループ設定の、「SORACOM Air for LoRaWAN 設定」に項目があります。

FAQ

フォーマットにエラーがあった場合はどうなりますか?

変換時のエラー内容がerrors という項目に入ってエンドポイントに送信されます。

フォーマットの挙動を事前にデバッグするツールはありませんか?

ご要望いただいておりますが、現在はご用意がございません。

SORACOM Air for Cellular でも使えますか?

ご要望いただいておりますが、現在はご用意がございません。

pagetop