MENU

Soracom

Users

カスタムフォーマット

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

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, station, lat, lng, rssi, data, seqNumber, data

バイト列のインデックス

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

変数の型

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

  • bool 真偽値
  • int 符号付き整数
  • uint 符号なし整数
  • float 浮動小数点数
  • char ASCII 文字

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

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

bool

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

flag:0:bool:7

offset (必須)

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

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

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