Posted at

Sigfox Callback - Custom Payload Config機能

More than 1 year has passed since last update.

本稿では、Sigfox Callbackの一部機能Custom Payload Configについて記述します。

事前にSigfox Callback機能をご一読ください。


Custom payload configとは

LPWA(Sigfox)ネットワークは、ちょっとしたデータを長距離伝送することを目的としていたり、デバイスの消費電力を削減するため、Sigfoxデバイスから送信されるデータは最大12バイトのペイロードとなっています。また、この12バイトは構造化されている訳ではなく、12バイト内でユーザーが独自にフォーマットを取り決めます。

例えば、温度センサーと気圧センサーのデータを送信しようとした場合、(わかりやすくするため整数値で)温度=28℃、気圧=1012hPaというデータを送る場合、16進表記で


  • 温度 = 28℃ = 0x1C

  • 気圧 = 1012hPa = 0x03F4

となるので、1C03F4というデータ(3バイト分)をペイロードに入れ、送ることとなります。

このデータは自動的にSigfoxクラウドに蓄積されるとともに、Sigfox Callback機能により、JSON形式等で、ユーザー側のサーバー(アプリケーションサーバー)に転送されます。

通常は、アプリケーションサーバー側でこの1C03F4というデータをParseすることになるのですが、温度=28℃、気圧=1012hPaとしてアプリケーションサーバーで受け取りたいという場合があります。

それを解決するのがCustom Payload Configです。


Custom payload configの使い方

まずは、Sigfox Callback設定について知っておかないといけないので、こちらを見てください。

このCallback設定画面内にCustom payload configという入力項目があります。ここに独自の記述ルールに基づき、16進表記のペイロードを数値化(変数代入)することができます。


Custom payload configの記述例

上記の例(0x1C03F4というペイロードを温度=28℃、気圧=1012hPa)の場合、この入力項目に

temp::int:8 pressure::int:16

と記述します。すると、Custom variables:というところに

customData#temp, customData#pressure

という変数が追加されます。



この2つの変数をURL転送する場合はBody内で、メール転送する場合は、メールタイトルと本文内で使えるようになります。



あとは、[OK]ボタンを押し、Callback設定は終わりです。

その後、デバイスがデータを送信する毎に、下記のようなJSONがPOSTされるようになります。

{

"device":"1234AB",
"data":"1C03F4",
"temperature":28,
"pressure":1012
}

つまり、temp::int:8は、先頭バイトから8ビット分をint型としてtemp変数に代入する。ということになり、pressure::int:16は、続くバイト位置から16ビット分をint型としてpressure変数に代入するという意味になります。



もし、先頭からではなく、あるバイト位置から何ビットかを取り込みたい場合は、Custom payload configの記述フィールドの2つ目(上記では何も記載しなかったところ)に「バイトインデックス」を定義します。

先頭2バイト目からの16ビット分をint型としてvalue変数に代入したい場合は、

value:1:int:16

と定義します。上記の例ではtemp::int:8 pressure::int:16pressure:1:int:16とではpressureは同じ値になります。(バイトとビットで混乱しますが)


Custom payload configの記述仕様

Custom payload configの記述仕様は、SigfoxクラウドのCallback設定画面のCustom payload config入力の右にある

アイコンをクリックすると見れますが、ちょっとわかりにくいので書いておきます。

[変数定義]:[バイトインデックス]:[データ型定義]

となります。変数定義とバイトインデックスは上述の通りです。

データ型定義部分は、指定するデータ型により記述方法が異なります。

データ型
記述仕様
捕捉

bool型
bool:ビットインデックス(0-7)
ビットインデックスは対象バイト内の対象ビット。例えば、0x80に対しb1::bool:7 b2::bool:6と記述した場合はb1=true,b2=falseになります。つまり0x80(2進数表記で10000000)の7ビット目は1、6ビット目は0になります。

char型
char:文字数(0-7)
ASCII文字としてParseします。例えば0x414243444546という6バイトを文字に変換する場合、char:6と記述することによりABCEDFという文字に変換されます

float型
float:ビット数:[エンディアン]:[ビットオフセット]
ビット数は、32(bits)か64(bits)かどちらか。エンディアンはオプションで:little-endianか:big-endianを指定できます。 IEEE 754に準拠ています。

uint型
uint:ビット数:[エンディアン]
ビット数でサイズを指定します。

int型
int:ビット数:[エンディアン]
ビット数でサイズを指定します。

※バイトインデックスはbool型の場合は、次のバイトに移らないのでご注意を。

Sigfox Japan KCCS