SORACOM Orbit を使用したフォーマットの変換
ここではビーコン対応 GPS トラッカー GW (以下、ビーコン GW) から送信されたデータのフォーマット変換について、仕様と使用方法を説明します。
バイナリパーサーを用いた変換
ビーコン GW では、位置情報、BLE センサー情報などをバイナリ形式で送信します。SORACOM ではバイナリ形式を指定されたフォーマットの JSON 形式に変換する バイナリパーサー を提供しています。キッティングツールでバイナリパーサーに用いるフォーマットを取得し、SORACOM プラットフォーム上で変換することでデバイスからのデータを JSON 形式に変換できます。
変換前のバイナリデータは以下のような例です。
04033031303132313335313730383031323334353637383930313233340300000030313233343536373839414200889E410008674200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
キッティングツールで取得したフォーマットを用いることで以下のような JSON 形式に変換できます。
{
"type": 4,
"bat": 3,
"timestamp": "010121351708",
"imei": "012345678901234",
"sns_valid_no": 3,
"adv_add": "0123456789AB",
"sns1": 19.81640625,
"sns2": 57.7578125,
"sns3": 0,
"sns4": 0,
"sns5": 0,
"sns6": 0,
"sns7": 0,
"sns8": 0,
"sns9": 0,
"sns10": 0,
"sns11": 0,
"sns12": 0,
"sns13": 0,
"sns14": 0,
"sns15": 0,
"sns16": 0,
"sns17": 0,
"sns18": 0,
"sns19": 0,
"sns20": 0,
"sns21": 0,
"sns22": 0,
"sns23": 0,
"sns24": 0,
"binaryParserEnabled": true
}
SORACOM Orbit を使用する理由
死活監視にて各種パラメータが 0 のデータを受信するため
ビーコン GW では日次で死活監視を目的に "type": 2 のパラメータのデータを送信します。そのデータにはセンサーデータは入っていないのですが、バイナリパーサーの仕様上、他のパラメータが 0 になった以下のようなデータを受信します。
{
"type": 2,
"bat": 3,
"timestamp": "010202000005",
"imei": "012345678901234",
"sns_valid_no": 0,
"adv_add": "000000000000",
"sns1": 0,
"sns2": 0,
"sns3": 0,
"sns4": 0,
"sns5": 0,
"sns6": 0,
"sns7": 0,
"sns8": 0,
"sns9": 0,
"sns10": 0,
"sns11": 0,
"sns12": 0,
"sns13": 0,
"sns14": 0,
"sns15": 0,
"sns16": 0,
"sns17": 0,
"sns18": 0,
"sns19": 0,
"sns20": 0,
"sns21": 0,
"sns22": 0,
"sns23": 0,
"sns24": 0,
"binaryParserEnabled": true
}
クラウド側で type パラメータを見て判別できれば良いのですが、不要なパラメータを含まないデータ形式の方が処理が容易になります。
複数センサー利用時に他のセンサーのパラメータが 0 のデータを受信するため
ビーコン GW では複数の BLE センサーのデータを送信できます。たとえば、以下のように sns1, sns2 にデータが入っている場合と sns3, sns4 にデータが入っている場合、といったデータを送信します。
{
"type": 4,
"bat": 3,
"timestamp": "010112000000",
"imei": "012345678901234",
"sns_valid_no": 3,
"adv_add": "0123456789AB",
"sns1": 19.81640625,
"sns2": 57.7578125,
"sns3": 0,
"sns4": 0,
"sns5": 0,
"sns6": 0,
"sns7": 0,
"sns8": 0,
"sns9": 0,
"sns10": 0,
"sns11": 0,
"sns12": 0,
"sns13": 0,
"sns14": 0,
"sns15": 0,
"sns16": 0,
"sns17": 0,
"sns18": 0,
"sns19": 0,
"sns20": 0,
"sns21": 0,
"sns22": 0,
"sns23": 0,
"sns24": 0,
"binaryParserEnabled": true
}
{
"type": 4,
"bat": 3,
"timestamp": "010113000000",
"imei": "012345678901234",
"sns_valid_no": 12,
"adv_add": "ABCDEF012345",
"sns1": 0,
"sns2": 0,
"sns3": 15.01234567,
"sns4": 48.89012345,
"sns5": 0,
"sns6": 0,
"sns7": 0,
"sns8": 0,
"sns9": 0,
"sns10": 0,
"sns11": 0,
"sns12": 0,
"sns13": 0,
"sns14": 0,
"sns15": 0,
"sns16": 0,
"sns17": 0,
"sns18": 0,
"sns19": 0,
"sns20": 0,
"sns21": 0,
"sns22": 0,
"sns23": 0,
"sns24": 0,
"binaryParserEnabled": true
}
どの snsX にデータが入っているかは sns_valid_no より判別できますが、同様に不要なパラメータを含まないデータ形式の方が処理が容易になります。
SORACOM Orbit での変換後のフォーマット
SORACOM Orbit はユーザーの定義するプログラムで柔軟なデータ変換ができるサービスです。ビーコン GW で必要となる、type や sns_valid_no の値に応じて送信するデータの変換も可能です。ビーコン GW に用いるサンプルプログラムはソラコムより 公開 されており、コンパイル済みの WebAssembly (WASM) モジュールをダウンロードし SORACOM ユーザーコントロールへ設定するだけで利用できます。手順詳細は SORACOM Orbit WASM モジュールの使用方法 を参照してください。
SORACOM Orbit により ビーコン GW が送信するフォーマット から変換している点は以下です。
typeに応じて必要なデータのみ送信する- 充電中の
batを-1にする sns_valid_noに応じて値のある snsX のみ送信するns、ewに応じてlat,lonの符号を変換するrssi_bに加えて十進数で記載したrssiを送信するadv_addをデバイスに記載されている通りの並びにする- ユーザーデータに応じて
snsXのキー名を変更する (詳細は ユーザーデータを用いたキー名の変更 を参照) "binaryParserEnabled": trueを送信しない
変換後のフォーマットは以下のようになります。
常に送信されるデータ
| Key | データの意味 | データ形式 |
|---|---|---|
type | データの種別 | 1: 位置情報通知、2: 死活監視通知、3: iBeacon 通知、4: BLE センサー情報通知 |
bat | 電池残量 | 1: なし、2: 少ない、3: あり、-1: 充電中 |
timestamp | デバイスのタイムスタンプ | MMDDhhmmssss (日本時間) |
デバイスのタイムスタンプは「トラッカーモードでデータを送信している間」「ゲートウェイモードでデータを送信していない間」に同期されます。ゲートウェイモードで 24 時間送信し続ける設定にした場合は時刻がずれていく場合があります。 なお、SORACOM Funnel, SORACOM Funk, SORACOM Harvest Data で付与するタイムスタンプは SORACOM プラットフォームで受け取ったタイミングのため、当値は参考値として活用ください。
位置情報通知時に送信されるデータ
| Key | データの意味 | データ形式 |
|---|---|---|
loc_data | 測位時刻 | hhmmssss (世界標準時 UTC) |
lat | 緯度 | DEG 形式で DD.mmmmmm、符号付き |
lon | 経度 | DEG 形式で DDD.mmmmmm、符号付き |
major_axis | 長軸誤差 | 0 ～ 65535 (m) |
minor_axis | 短軸誤差 | 0 ～ 65535 (m) |
- 長軸誤差・短軸誤差は誤差楕円の標準偏差です。値が大きいほど測位データに大きな誤差がある可能性が高いことを示します。
- ばらつきが正規分布するとした場合、長軸誤差が 50m であれば誤差楕円の長軸方向には、±50m の範囲に約 68%、±100m の範囲に約 95% が収まります。
BLE センサー情報通知に送信されるデータ
| Key | データの意味 | データ形式 |
|---|---|---|
sns_valid_no | 有効なセンサーデータ番号 | 1 ~ 4294967295 |
adv_add | センサーの Advertiser's Address | 12 桁の英数字 |
snsX (X は 1~24 の数字) | センターからのデータ | センサーからのデータ (値があるもののみ) |
- Advertiser's Address の異なる複数センサーからデータを送信する場合、センサーごとデータが送信されます。その際、snsX の X の数字がキッティングツールで指定したスロットの数字よりも小さくなる場合があります。
sns_valid_noではセンサーデータが格納されている sns (1 ～ 24) をビット単位で示し、10 進数に変換しています。たとえば 5 の場合は sns1 と sns3 にデータが格納されています。
iBeacon 情報通知に送信されるデータ
| Key | データの意味 | データ形式 |
|---|---|---|
uuid | iBeacon の識別子 | 32 文字の 英数字 |
major | iBeacon の major | 0000 ～ FFFF (2 バイトの 16 進数表現) |
minor | iBeacon の minor | 0000 ～ FFFF (2 バイトの 16 進数表現) |
rssi_b | RSSI | 00 ～ FF (1 バイトの 16 進数表現) |
rssi | RSSI | 0 ～ 255 |
attr | 特別な監視 | 1: 特別監視ビーコンの特定を開始、2: 特別監視ビーコンの特定が不可、3: 特別監視ビーコンの特定を継続、0: 特別な監視ビーコンではない |
「IMEI 情報を送信する」が有効の場合
| Key | データの意味 | データ形式 |
|---|---|---|
imei | IMEI | 15 桁の数字 |
ユーザーデータを用いたキー名の変更
公開している SORACOM Orbit のプログラムでは、BLE センサーのキー名を snsX から任意のキー ("deviceA_temperture"、"冷蔵庫の温度 など) に変更できます。変更後のキー名は メタデータサービスのユーザーデータ に "snsX": "キー名" 形式で記載します。以下は例です。
{
"sns1": "冷凍庫の温度",
"sns3": "deviceA_humidity"
}
変更後のキー名が指定されている snsX についてキー名が変換されて送信されます。以下は送信されるデータの例です。
{
"type": 4,
"bat": 3,
"timestamp": "010112100000",
"imei": "012345678901234",
"sns_valid_no": 7,
"adv_add": "0123456789AB",
"冷凍庫の温度": -19.81640625,
"sns2": 57.7578125,
"deviceA_humidity": 4.1526893
}
なお snsX 以外のキー名について変更したい場合は、公開されているサンプルプログラムを参考に実装してください。
ユーザーデータを用いる場合は、SORACOM Orbit の「メタデータ」を有効にしてください。詳しくは、SIM グループでの使用 を参照してください。
SORACOM Orbit WASM モジュールの使用方法
WASM モジュールのダウンロード方法
GitHub リポジトリのリリースページ より最新のモジュール (.wasm 形式) をダウンロードします。
プログラムのカスタマイズ
README にしたがって、プログラムのカスタマイズが可能です。