Sigfox Callback - Custom Payload Config機能

本稿では、Sigfox Callbackの一部機能Custom Payload Configについて記述します。
事前に[Sigfox Callback機能](https://qiita.com/ghibi/items/53259381a30363538a6d)をご一読ください。
#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設定について知っておかないといけないので、[こちら](https://qiita.com/ghibi/items/53259381a30363538a6d)を見てください。
![image.png](https://qiita-image-store.s3.amazonaws.com/0/172313/c0b7d59c-e5b0-c685-7733-e17532e3bed9.png)

このCallback設定画面内に**Custom payload config**という入力項目があります。ここに独自の記述ルールに基づき、16進表記のペイロードを数値化（変数代入）することができます。
##Custom payload configの記述例
上記の例（0x1C03F4というペイロードを温度=28℃、気圧=1012hPa）の場合、この入力項目に
`temp::int:8 pressure::int:16`
と記述します。すると、*Custom variables:*というところに
`customData#temp, customData#pressure`
という変数が追加されます。
![image.png](https://qiita-image-store.s3.amazonaws.com/0/172313/938438bd-7b3e-c4c0-1a46-02f2a7b897d0.png)
この2つの変数をURL転送する場合はBody内で、メール転送する場合は、メールタイトルと本文内で使えるようになります。
![image.png](https://qiita-image-store.s3.amazonaws.com/0/172313/bd440fd6-ef4c-08fa-8584-c1652ae3900b.png)
あとは、[OK]ボタンを押し、Callback設定は終わりです。
その後、デバイスがデータを送信する毎に、下記のようなJSONがPOSTされるようになります。

```
{
  "device":"1234AB",
  "data":"1C03F4",
  "temperature":28,
  "pressure":1012
}
```
つまり、`temp::int:8`は、先頭バイトから8ビット分をint型としてtemp変数に代入する。ということになり、`pressure::int:16`は、続くバイト位置から16ビット分をint型としてpressure変数に代入するという意味になります。
![cpc.png](https://qiita-image-store.s3.amazonaws.com/0/172313/3791596a-9866-5450-6eda-a2b9285e1bf6.png)
もし、先頭からではなく、あるバイト位置から何ビットかを取り込みたい場合は、Custom payload configの記述フィールドの2つ目（上記では何も記載しなかったところ）に「バイトインデックス」を定義します。
先頭2バイト目からの16ビット分をint型としてvalue変数に代入したい場合は、
`value:1:int:16`
と定義します。上記の例では`temp::int:8 pressure::int:16`と`pressure:1:int:16`とではpressureは同じ値になります。（バイトとビットで混乱しますが）

##Custom payload configの記述仕様
Custom payload configの記述仕様は、SigfoxクラウドのCallback設定画面のCustom payload config入力の右にある :grey_question:アイコンをクリックすると見れますが、ちょっとわかりにくいので書いておきます。
`[変数定義]:[バイトインデックス]:[データ型定義]`
となります。変数定義とバイトインデックスは上述の通りです。
データ型定義部分は、指定するデータ型により記述方法が異なります。

|データ型|記述仕様|捕捉|
|:------|:------|:---|
|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型の場合は、次のバイトに移らないのでご注意を。

[Custom Payload Config応用](https://qiita.com/ghibi/items/240e8591a7da1e2cbff0)に続く

[Sigfox Japan KCCS](https://qiita.com/organizations/sigfox)