カスタムフォーマットは以下のような構文を持っています。
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:
data、date、deveui、gatewayData - Sigfox:
countryCode、data、device、lat、lng、lqi、operatorName、rssi、seqNumber、snr、station、time
バイト列のインデックス
先頭から何バイト目を読むかを指定します。複数バイトを読むデータ型の場合は、読み始める最初のバイトを指定してください。先頭バイトを 0 として数えます。
バイト列のインデックスの省略について
バイト列のインデックスは空欄にできます。(例) lat::float:32
空欄にした場合、最後に読んだバイトの次のバイトから読み始めます。先頭の項目の場合は先頭のバイトを読みます。たとえば、value1::int:6 value2::int:8 という指定をした場合、value1 は先頭バイト (6 ビットを指定しているので、末尾 2 ビットは読まれません)、value2 はその次のバイトを読みます。
bool が連続する場合は例外で、同じインデックスのバイトを読み続けます (*1) (*2)。
これによって、1 バイトの中に複数の bool を詰め込むときの設定が簡潔になります。
(例) flagA:0:bool:7 flagB::bool:6 flagC::bool:5 value:0:int:4 は先頭 3 ビットを bool に、その後の 5 ビットを int として読み込みます。
- (*1) bool を 8 個以上連続させてもインデックスは進みません。
- (*2) ビットの offset は必ず指定する必要があります。
変数の型
バイナリパーサーがサポートする型は以下のとおりです。
変数の型に依存した設定内容
各変数の型にはそれぞれ固有の設定があります。型ごとに説明します。
省略する場合はコロンも含めて省略します
(省略可) と書いてある設定は、省略できます。省略する場合は、直前の : も含めて省略してください。
たとえば、value:1:uint:8:little-endian:7:+10*2 のエンディアンネスの指定を省略する場合は、以下のように設定します。
✓ value:1:uint:8:7:+10*2
× value:1:uint:8::7:+10*2
bool 型 (真偽値)
bool は真偽値です。対象バイトの 1 ビットを読み、1 であれば true、0 であれば false を返します。
設定項目は、以下のとおりです。
<変数名>:[バイト列のインデックス]:bool:[offset]
設定例： flag:0:bool:7
offset (必須)
offset は指定されたバイトのどのビットから読むかを指定します。 最上位ビットを読むには offset に 7 を指定します。0-7 までの値のいずれかを指定してください (下図参照)。
例: 0x9A (10011010b) に対する offset の例
int 型 (符号付き整数)、uint 型 (符号なし整数)
int は符号付き整数、uint は符号なし整数です。
設定項目は以下のとおりです。
符号付き整数の場合:
<変数名>:[バイト列のインデックス]:int:<length>:[endianness]:[offset]:[operations]符号なし整数の場合:
<変数名>:[バイト列のインデックス]:uint:<length>:[endianness]:[offset]:[operations]
設定例: value:1:uint:8:little-endian:7:+10*2
length (必須)
読み込むビットの長さ (1 ～ 32) を指定します。上の設定例では 8 が指定されています。
なお、データが読み取られる範囲は、ビッグエンディアンとリトルエンディアンで異なります。エンディアンネス (バイトオーダー) は、次の設定項目 endianness で設定します。
| エンディアンネス (バイトオーダー) | データが読み取られる範囲 |
|---|---|
| ビッグエンディアン (デフォルト) | 指定した値の分だけデータが読み取られます。たとえば、1 バイトを読み込む場合は 8 を指定します。4 を指定すると 4 ビットだけ読み取られます。length に指定した値によって、変数が取りうる値の範囲が決まります。 |
| リトルエンディアン | リトルエンディアンの場合は、1 バイト (8 ビット) ごとにデータが読み取られます。つまり、length に指定した値に応じて常に 8/16/24/32 のいずれかのビット数が読み込まれます。たとえば 3 や 5 を指定した場合は、3 ビットまたは 5 ビットの表現に必要な 1 バイト (8 ビット) が読み込まれます。 |
endianness (省略可)
エンディアン (バイトオーダー) をリトルエンディアンにする場合は、length の直後に :little-endian を指定します。デフォルトはビッグエンディアンで読み込みます。
offset (省略可)
バイト列のインデックス で指定されたバイトのどのビットから読むか (オフセット。0 ～ 7) を指定します。上の設定例では 7 が指定されています。デフォルトは、7 です。
0x9A (10011010) に対する offset は以下のとおりです。
設定例:
0x9A (10011010) というバイトがあった場合、先頭の
1から 8 ビットを整数として読む場合は、offset に7を指定します。変数全体ではtemp:0:uint:8:7を指定します。0x9A (10011010) というバイトの後半の 4 ビット (
1010) を符号なし整数として読みたい場合は、offset に3を指定します。変数全体ではtemp:0:uint:4:3を指定します。2 バイトのデータの後半 10 ビットを符号付き整数として読みたい場合は、
temp:0:int:10:1を指定します。この指定で、先頭バイトの offset1から 10 ビット (先頭バイトの末尾 2 ビットと、次のバイトの 8 ビット) が読み込まれます。
リトルエンディアンの場合は offset は常に 7 として取り扱われます
offset は、ビッグエンディアンの場合に有効な設定項目です。リトルエンディアンの場合は、offset が常に 7 として取り扱われます。
operations (省略可)
operations は読み込んだ値に対して演算するときに使います。
利用できる演算子は四則演算 (
+、-、*、/) です。演算子の優先順位はすべて同じで、シンプルな電卓を使ったときのように、左から順に計算していきます。
例:
value:0:int:8:+10*2という設定があって、value が 1 だった場合、値は 22 となります。1+10*2 = (1 + 10) * 2 = 22演算子の上限は 5 です。
割り算の場合、計算結果は浮動小数点数に変換されます。
例:
11/10 = 1.1operations が省略された場合は、演算を行いません。
演算子と前の設定の間には他の設定と同様に : が必要です。忘れやすいので、気をつけてください。
float 型 (浮動小数点数)
float は IEEE 754 形式の浮動小数点数です。
設定項目は以下のとおりです。
<変数名>:[バイト列のインデックス]:float:<length>:[endianness]:[offset]:[operations]
設定例: value:0:float:64:little-endian:7:+10*2
length (必須)
読み込むビットの長さ (32 または 64) を指定します。length に指定した値によって、変数が取りうる値の範囲が決まります。
endianness (省略可)
エンディアン (バイトオーダー) をリトルエンディアンにする場合は、length の直後に :little-endian を指定します。デフォルトはビッグエンディアンで読み込みます。
offset (省略可)
バイト列のインデックス で指定されたバイトのどのビットから読むか (オフセット。0 ～ 7) を指定します。上の設定例では 7 が指定されています。デフォルトは、7 です。
operations (省略可)
int 型 (符号付き整数)、uint 型 (符号なし整数) の operations と同様です。
char 型 (ASCII 文字)
char は ASCII 文字です。1 バイトで 1 文字を表現します。設定できる項目は length です。
設定項目は以下のとおりです。
<変数名>:[バイト列のインデックス]:char:<length>
設定例: value:0:char:4
length (必須)
読み込む文字の長さ (＝バイト数。1 ～ 64) を指定します。