SORACOM Developers

Documents

バイナリパーサー詳細

はじめに

バイナリパーサーとは SORACOM Air でご利用いただけるバイナリデータをJSONデータに変換する機能です。(*)

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

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

(*) SORACOM Air for LoRaWAN / Sigfox および SORACOM Air for セルラーでご利用いただけます。

処理の流れ

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

定義済みフォーマット

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

デバイス名 フォーマット 備考
Sens'it @sensit Sens'it v2 に対応しています。Sens'it v3 には対応していません。
Sigfox Shield for Arduino @unashield unabiz-arduino ライブラリで送信されるデータ形式に対応しています。これ以外のデータ形式には対応していませんのでご注意ください。
SORACOM LTE-M Button for EnterpriseおよびSORACOM LTE-M Button Plus @button clickType および batteryLevel を出力します。
詳しくはSORACOM Harvestを使用して SORACOM LTE-M Button for Enterprise のクリック種別、バッテリ残量を確認するをご覧ください。
SORACOM LTE-M Button for EnterpriseおよびSORACOM LTE-M Button Plus @button.ifttt IFTTTの Webhook に合わせて以下の値が割当たります。
  • value1 : clickType
  • value2 : clickType に合わせた日本語名 (シングル | ダブル | ロング)
  • value3 : batteryLevel を 100 倍した値
clickType および batteryLevel についてはSORACOM Harvestを使用して SORACOM LTE-M Button for Enterprise のクリック種別、バッテリ残量を確認するをご覧ください。

利用例はブログ記事をご参照ください。

カスタムフォーマット

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

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 ~ 64 です。

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 は必ず指定する必要があります。

設定方法

LoRaWAN の場合

ユーザーコンソールのメニューから「LoRa グループ設定」を開き対象のグループを選択します。「SORACOM Air for LoRaWAN 設定」にバイナリパーサーの項目があります。フォーマット欄に定義済みフォーマットもしくはカスタムフォーマットを設定して保存ボタンを押します。

Sigfox の場合

ユーザーコンソールのメニューから「Sigfox グループ設定」を開き対象のグループを選択します。「SORACOM Air for Sigfox 設定」にバイナリパーサーの項目があります。フォーマット欄に定義済みフォーマットもしくはカスタムフォーマットを設定して保存ボタンを押します。

セルラーの場合

ユーザーコンソールのメニューから「SIM グループ設定」を開き対象のグループを選択します。「SORACOM Air for Cellular 設定」にバイナリパーサーの項目があります。フォーマット欄に定義済みフォーマットもしくはカスタムフォーマットを設定して保存ボタンを押します。

制約事項

FAQ

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

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

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

SORACOM Binary Parser Playgroundをご利用ください。使い方に関してはブログ記事もご参照ください。

Getting Started

SORACOM Air for セルラー

SORACOM Air for LoRaWAN

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Funk

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

SORACOM Napter

Gadgets

Device

サービス機能詳細

Developer Tools

pagetop