Soracom

Users

スタートガイド

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 で必要となる、typesns_valid_no の値に応じて送信するデータの変換も可能です。ビーコン GW に用いるサンプルプログラムはソラコムより 公開 されており、コンパイル済みの WebAssembly (WASM) モジュールをダウンロードし SORACOM ユーザーコントロールへ設定するだけで利用できます。手順詳細は SORACOM Orbit WASM モジュールの使用方法 を参照してください。

SORACOM Orbit により ビーコン GW が送信するフォーマット から変換している点は以下です。

  • type に応じて必要なデータのみ送信する
  • 充電中の bat-1 にする
  • sns_valid_no に応じて値のある snsX のみ送信する
  • nsew に応じて 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 Address12 桁の英数字
snsX (X は 1~24 の数字)センターからのデータセンサーからのデータ (値があるもののみ)
  • Advertiser's Address の異なる複数センサーからデータを送信する場合、センサーごとデータが送信されます。その際、snsX の X の数字がキッティングツールで指定したスロットの数字よりも小さくなる場合があります。
  • sns_valid_no ではセンサーデータが格納されている sns (1 ~ 24) をビット単位で示し、10 進数に変換しています。たとえば 5 の場合は sns1 と sns3 にデータが格納されています。

iBeacon 情報通知に送信されるデータ

Keyデータの意味データ形式
uuidiBeacon の識別子32 文字の 英数字
majoriBeacon の major0000 ~ FFFF (2 バイトの 16 進数表現)
minoriBeacon の minor0000 ~ FFFF (2 バイトの 16 進数表現)
rssi_bRSSI00 ~ FF (1 バイトの 16 進数表現)
rssiRSSI0 ~ 255
attr特別な監視1: 特別監視ビーコンの特定を開始、2: 特別監視ビーコンの特定が不可、3: 特別監視ビーコンの特定を継続、0: 特別な監視ビーコンではない

「IMEI 情報を送信する」が有効の場合

Keyデータの意味データ形式
imeiIMEI15 桁の数字

ユーザーデータを用いたキー名の変更

公開している 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 にしたがって、プログラムのカスタマイズが可能です。