SORACOM Developers

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 でも使えますか?

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

Getting Started

SORACOM Air for セルラー

SORACOM Air for LoRaWAN

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

サービス機能詳細

Developer Tools

pagetop