カスタムフォーマット
カスタムフォーマットは以下のような構文を持っています。
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 オブジェクトのキーです。
変数名に使えるのは 数字、アルファベット、記号 (#、-、_、$) です。
LoRaWAN、Sigfox における既存の項目との衝突を防ぐため、それぞれのペイロードで使用されている以下の変数名は利用できません。
- LoRaWAN:
date、gatewayData、data、deveui - Sigfox:
device、time、data、seqNumber、lqi、operatorName、countryCode
バイト列のインデックス
先頭から何バイト目を読むかを指定します。複数バイトを読むデータ型の場合は、読み始める最初のバイトを指定してください。先頭バイトを 0 として数えます。
変数の型
バイナリパーサーがサポートする型は以下のとおりです。
- bool 真偽値
- int 符号付き整数
- uint 符号なし整数
- float 浮動小数点数
- char ASCII 文字
変数の型に依存した設定内容
各変数の型にはそれぞれ固有の設定があります。 それぞれの型ごとに、それを解説していきます。
bool
bool は真偽値です。対象バイトの 1bit を読み、1 であれば true、0 であれば 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) bool を 8 個以上連続させてもインデックスは進みません。
- (*2) bit の offset は必ず指定する必要があります。