BLE インターフェース
はじめに
このページでは、Bluetooth Low Energy (BLE) リンク経由で利用できる LEAPS UWB Subsystem API (UWBS) について説明します。
UWBS BLE API 設計では、UWBS モジュールは BLE ペリフェラルとして機能し、API を介して BLE セントラル デバイスによって通信できます。このドキュメントでは、BLE セントラル デバイスが通信に使用できる API を紹介します。
注釈
Linux 上の Bluetooth が完全に動作しなくなった場合は、次のコマンドを使用して Bluetooth を再起動します。
systemctl restart bluetooth.service
使用されている用語
UWBS: LEAPS UWB サブシステム モジュール。 UWBS は、BLE 通信において BLE ペリフェラルとして機能します。
CDEV: UWBS ペリフェラルに接続する BLE 中央デバイス。
ELDR: 拡張ローダー。
位置表現
リアルタイム測位システムで位置と距離を表示する場合、考慮すべき点が 2 つあります。
精度
精度
精度は、ノードによって報告された位置と実際の位置との間の誤差です。現在、この設計で使用されている UWBS は約 10 cm の精度を提供します。
精度は、表現される最下位ビット (LSB) の値です。このシステムのオンボードファームウェアでは、精度は 1 mm、つまり 0.001 メートルです。位置は 3 次元座標 (X、Y、Z) で表されます。X、Y、Z はそれぞれ 32 ビット整数 (4 バイト) です。各 LSB は 1 mm を表します。これは、値の解釈を容易にし、報告された値の計算を容易にするためです。
精度を決定するときは、意味のある結果を得るために、精度を考慮して精度を選択することが重要です。精度が低い場合、ユーザーに正確な値を表示しても意味がありません。現在の 10 cm の精度に対して 1 mm の精度は細かすぎます。したがって、Android アプリケーションでは 1 cm、つまり 0.01 メートルの精度が使用されます。座標/距離が 1 cm 以上変化した場合にのみ、更新された値が Android アプリケーションに表示されますか? これは、float/double 値を意味のある小数点以下の桁数に丸めるのと似ています。
UWBS との BLE 通信
leaps_ble_evt_cfg_set によって UWBS のイベントを有効にします。
専用特性の通知を有効にします
BLE LUS (LEAPS UART サービス) インターフェイス
LEAPS UWBS は追加の BLE LUS (LEAPS UART Service) インターフェイスをサポートしており、次の手順でインターフェイスを設定します。
注釈
UART シェルが開かれている場合、BLE シェルにはアクセスできません。
以下のコマンドを使用して、Python ble-serial ライブラリをインストールします。
python -m pip install ble-serial==2.7.1注釈
Windows を使用している場合は、このリンク ble-serial の追加手順``Windows の追加手順``に従ってください。
以下のコマンドを使用してデバイスを検索します。 LEAPS ボードは``LEAPS….``という名前で表示されます。
ble-scanおよび成功したスキャンの結果:
シリアル ポートに接続するには、ターミナルを開き、上記の手順で見つかった MAC アドレスを使用して以下のコマンドを実行します。
ble-serial -d CA:E5:56:1F:57:3D -r e8573d97-6758-11e9-8860-cb4385c24b83 -w e6bfa235-6758-11e9-979f-5b24c4603eb8 -t 10成功すると、以下のように表示されます
ログとして、スクリプトは LEAPS ボード上のシリアル ポートと通信するために``/tmp/ttyBLE``という名前のシリアル ポートを作成しました。このターミナルを実行し、別のターミナルを開き、minicom としてツールを使用してこのシリアル ポートにアクセスしましょう。
Enter キーを 2 回押してシェルに入ります。
自動切断
CDEV が特性 “API Response“ または “API Events“ の 0x0001 を CCCD に書き込むことによる通知を有効にしていない場合、UWBS は 15 秒後に接続を自動的に終了します (BLE GATT モデル を参照)
BLEスループット
UWBS との間でデータをストリーミングするときに、最大可能な ATT MTU と最高の接続優先度を使用して、最大可能なスループットを活用します。UWBS でサポートされる最大 MTU は 150 バイトです。ノードが推奨する接続間隔は、最小 10 ミリ秒から最大 40 ミリ秒、レイテンシ 0、タイムアウト 2 秒です。Bluetooth v4.0 および v4.1 では、MTU ネゴシエーションに関係なく最大データ長がデフォルト値のままであるため、Bluetooth v4.2 以降と比較して、これらの Bluetooth バージョンの最大スループットが制限されることに注意してください。
セキュリティ/暗号化
機能
アクセス制御とメッセージの整合性 (MIC/MAC - メッセージ整合性コードまたはメッセージ認証コード)
機密保持
リプレイ保護
BLE のワイヤレス暗号化では、AES OFB 128 暗号が使用されます。
暗号化されたネットワークでは、通信に参加したい各ノードは、ユーザーが次の方法で設定した 128 ビットの対称キーを持っている必要があります。
LEAPS Android Manager: 設定経由
モジュール上: UART/SPI/UserApp/Shell API
暗号化/復号化はブロック単位で行われ、各ブロックのサイズは 16 バイトに固定されています。したがって、暗号化されたペイロードのサイズは 16 バイトの倍数に丸められる必要があります。つまり、セキュリティが有効になっている場合、メッセージのペイロードは 16 バイトの倍数に揃える必要があります。暗号化が無効になっている場合、ペイロードは 16 バイトに揃えてはなりません。
各メッセージには次の内容が含まれます
ナンス - 16 バイト
MIC/MAC - 2バイト
ペイロード (暗号化が有効な場合は 16 バイトに調整されます)
See also メッセージのエンコーディング
下の図は、AES を使用してデータがどのように暗号化されるかを説明しています。
赤色: 秘密キーであり、保護する必要があります
青色: 公開データ - すべての BLE メッセージで配布されます
灰色: 暗号化アクセラレータ/コントローラ
黄色: 計算/暗号化されたブロック
緑色: 平文/復号化されたブロック
下の図は、AES OFB を使用してデータがどのように暗号化され、チェーンされるかを説明しています。
暗号化されたネットワークに参加したいノードの要件
暗号化/復号化に正しい Nonce を使用する
128 ビット AES キーを持つ
nonce には、メッセージの暗号化/復号化に使用される nonce と、メッセージの整合性チェックに使用される nonce の 2 種類があります。
各暗号化/復号化ノンスの長さは 16 バイトです。送信者は nonce を生成し、送信メッセージに埋め込みます。受信者は、受信したノンスを復号化中に初期化ベクトル (IV) として使用します。
各整合性ノンスの長さは 16 バイトです。これは、受信したメッセージの nonce を 1 ずつインクリメントすることで、その nonce から導出されます。
リレー攻撃に対抗するには、すべてのノンスが一意である必要があり、ネットワーク内でいつでもどのメッセージに対してもノンスを再利用してはなりません。
BLE GATT モデル
UWBS サービス UUID は 680c21d9-c946-4c1f-9c11-baa1c21329e7 です。すべての特性値は、BLE 仕様が示唆するリトル エンディアンとしてエンコードされます。
UWBS の特性
UUID |
名前 |
長さ |
価値 |
フラグ |
|---|---|---|---|---|
Std.GAP サービス、ラベル 0x2A00 |
ラベル |
Var |
UTF-8 でエンコードされた文字列 |
RW |
e6bfa234- 6758-11e9- 979f-5b2 4c4603eb8 |
API リクエスト |
Var 最大 50 バイト |
メッセージヘッダー + TLV エンコードされた API リクエスト |
WO |
e8573d96- 6758-11e9- 8860-cb4 385c24b83 |
API レスポンス |
Var 最大 273 バイト |
メッセージヘッダー + TLV エンコードされた API 応答 |
RO |
003bbdf2- c634-4b3d- ab56-7ec889 b89a37 |
API イベント |
Var 最大 273 バイト |
メッセージ ヘッダー + TLV エンコードされた API イベント |
RO |
注釈
ラベルの特性は特別なものです。これは、標準の名前特性 (0x2A00) の下にある標準の必須 GAP サービス (0x1800) の一部です。
メッセージのエンコーディング
アイテム |
長さ |
ペイロード |
|---|---|---|
トランスポートヘッダー |
2バイト |
インデックス (1 バイト) 合計 (1 バイト) |
ノンス |
16バイト |
メッセージ nonce、セキュリティがオフになっている場合は関係ありません |
mic/mac |
2バイト |
暗号化が有効な場合はメッセージの整合性チェック、暗号化が無効な場合はペイロードの単純なバイト数の合計 |
ペイロード |
0 ～ 255バイト |
値または TLV エンコードされたフレーム (特定の特性に応じて) |
動作モード
API リクエスト leaps_cfg_get を使用して、現在の設定を読み取ります。 UWBS 構成を設定するには、leaps_cfg_anchor_set および leaps_cfg_tag_set API リクエストを使用します。
位置データ
API リクエスト leaps_loc_get を使用して、位置、距離、またはその両方を含む位置データを読み取ります。 UWBS 位置のみを操作するには、リクエスト leaps_pos_set および leaps_pos_get を使用します。
leaps_ble_evt_cfg_set によってイベント``位置データ準備完了``を有効にし、特性``イベント``に関する通知を受信して、UWBS から現在位置と距離を自動的に取得します。
位置データのエンコーディング、特性``イベント``の BLE 通知として受信 |
|||||
|---|---|---|---|---|---|
タイプ |
長さ |
価値 |
|||
int32_t - リトルエンディアン、ミリメートル単位の X 座標です |
int32_t - リトルエンディアン、y 座標 (ミリメートル単位) |
int32_t - リトルエンディアン、ミリメートル単位の Z 座標です |
uint8_t- は位置品質係数です。パーセント (0 ～ 100) |
||
0x41 |
0x0D |
0x4b 0x0a 0x00 0x00 0x1f 0x04 0x00 0x00 0x9c 0x0e 0x00 0x00 0x64 |
|||
前のテーブルのフレームの残り |
|||||||
|---|---|---|---|---|---|---|---|
タイプ |
長さ |
価値 |
|||||
uint8_t - 値にエンコードされた距離の数 |
uint16_t - UWB アドレスリトルエンディアンで |
uint32_t - リトルエンディアンでのミリメートル単位の距離 |
uint8_t - パーセント単位の距離品質係数 (0 ～ 100) |
標準の 13 バイト形式での位置 (x、y、z、qf) |
... |
||
0x49 |
0x51 |
0x04 |
位置と距離番号。 1 |
nr. 2, 3, 4 |
|||
タイプ 0x49 は測距アンカーの位置と距離を意味します
ユーザーデータ
leaps_ble_evt_cfg_set によってイベント``ユーザー データ準備完了``を有効にし、特性``イベント``に関する通知を受信して、UWBS から BLE ユーザー データを自動的に受信します。
BLE ユーザー データ エンコーディング、特性``イベント``の BLE 通知として受信 |
||
|---|---|---|
タイプ |
長さ |
価値 |
最大 128 バイト |
||
0x51 |
0x80 |
0x01 0x02 0x03 … 0x7F 0x80 |
ノードID
UWBS のアドレスを取得するには、要求 leaps_node_id_get を使用します。
ネットワークID
リクエスト leaps_panid_set および leaps_panid_get を使用して、ネットワークの ID を操作します。
リセットまたは再起動
leaps_reset や leaps_factory_reset などの UWBS をリセットするリクエストは、リセット前に BLE セントラルを切断します。中央は再度接続する前に 1 秒待つ必要があります。
アンカーリスト
リクエスト leaps_anchor_list_get を参照してください。
デバイス情報
ファームウェア、ハードウェア、構成のバージョンを読み取るには、リクエスト leaps_dev_info_get を参照してください。
自動配置
BLE API を使用すると、自動位置決めプロセスを開始することもできます。 CDEV 上で自動位置決めプロセスが終了します (位置が計算されます)。 BLE API を使用すると、距離の測定と取得を開始できるようになります。ワークフローは次のとおりです。
測定:
イニシエータが見つかり、検証されました (ノードは イニシエータとして構成されている だけでなく、実際のイニシエータ である必要があります。動作モード と BLE アドバタイズメント を参照してください)
イニシエーターに接続します。
まだ有効になっていない場合は、leaps_ble_evt_cfg_set によって``location Ready``イベントを有効にします (特性に関する BLE cccd 通知を有効にすることを忘れないでください)。
leaps_autopos_start リクエストにより自動位置決めを開始します。
イニシエーターからすべての測定距離を受信しました。測定距離をマトリックスに保存します。
イニシエータから切断します。
他のすべての (非イニシエーター) ノードからの距離を取得します。
接続
API リクエスト leaps_loc_get を使用して UWBS から位置データを取得し、マトリックスまでの距離を保存します。
切断
測定距離を評価し、直交性を確認し、位置を計算します。
ユーザーのリクエストに応じて、計算された位置をノードに保存します (leaps_pos_set リクエストを使用します)。
BLE アドバタイズメント
BLE アドバタイズメントは、周辺デバイスがその存在を他のデバイスに知らせる一般的な方法です。 BLE 仕様によれば、ブロードキャスト ペイロードは 3 つの要素、つまり [長さ、タイプ、<データ>] で構成されます。
UWBS は、存在と動作モード に関する基本情報をブロードキャストします。 BLE アドバタイズメントは、位置情報を含めるのに十分な長さではありません。
BLE アドバタイズメントでは、31 バイトが使用されます。
3 バイトは必須フラグです (1 つの AD トリプレット)。
残りの 28 バイトは、アプリが AD レコードを埋めるために使用できます (各レコードには 2 バイトの長さ + タイプのオーバーヘッドがあります)
プレゼンスブロードキャスト
UWBS モジュールの BLE は、接続可能なアンダイレクト モードで動作します。これは、サービスの可用性と一部のサービス データを含むプレゼンス ブロードキャストをアドバタイズします。プレゼンス ブロードキャストは BLE アドバタイズメント フレーム構造に従い、28 バイトを使用して情報を表示します。デバイス名はスキャン応答に含まれており、アクティブなスキャンが必要です。
プレゼンス ブロードキャストとスキャン応答のエンコーディングについては、次の表で説明します。
広告 |
値 |
|---|---|
LEN |
0x02 |
タイプ |
0x01 (フラグ) |
値 |
デバイス/アドバタイズメントフラグ - 接続可能 |
LEN |
0x19 (25 dec) |
タイプ |
0x21 (12 月 33 日、サービスデータ) |
値 |
680c2 1d9-c946-4c1f-9c11-baa1c21329e7 (16 バイト) |
PAN ID (2バイト) |
|
节点 ID (2バイト) |
|
标志（1 バイト）
ビットレイアウト: OXSEIBUU O - 動作モード (タグ 0、アンカー 1)
X - 予約済み
S - security_enabled
E - エラー表示
I - initiator_enabled,
B - ブリッジ有効
UU - UWB モード: オフ (0)、パッシブ (1)、アクティブ (2)
|
|
変更カウンタ (1 バイト) - UWBS の重要な内部状態が変更されるたびに変更カウンタが変更されます (構成など)。 |
|
UWB カウンタ (1 バイト) - 低電力デバイスによって使用されるカウントダウン カウンタ。 LP デバイスのこのカウンタが 0 に達すると、デバイスの UWB アクティビティが無効になります。アンカーは、デバイス上のこのカウンタが設定された最低水準点値を下回ったことを検出すると、デバイスに接続し、カウンタをリセットしてデバイスの UWB をアクティブに保ちます。 |
|
UWBS フラグ (1 バイト)
ビットレイアウト: FUSR
F - ファームウェアのタイプ (2ビット、0=BLDR、1=ELDR、2=MAIN)
U - UWB システム (2 ビット、0=LEAPS RTLS、1=FIRA)
S - UWB サブシステム (2 ビット、0=UCI、1=NIQ)
R - 予約済み、
|
|
顧客情報（1バイト） 顧客固有の情報 |
スキャン応答 |
|
|---|---|
LEN |
0x16 (22 dec) |
タイプ |
0x09 (デバイス名、スキャン応答パケットに配置され、アクティブ スキャンを使用して検出します) |
値 |
|
ファームウェアのアップデート
ファームウェア更新機能は、UWBS のファームウェアを更新するために使用されます。このセクションでは、BLE インターフェイス上の制御とデータ フローについて説明します。ファームウェア更新プロセスの詳細については、API リクエスト leaps_fw_update_start および leaps_fw_update_xfer を参照してください。
FWバイナリを更新しています
CDEV は UWBS に接続します。
CDEV は leaps_fw_update_start によって FW の更新を開始します。
UWBS がステータス``ok``で応答した場合、CDEV はこの手順をスキップできます。UWBS がステータス``again``で応答した場合、CDEV は UWBS をリセットし、UWBS の再起動後に再接続し、CDEV は更新を再度開始します。UWBS がステータス``not permitted``で応答した場合、FW の更新は不可能です。UWBS で FW の更新が無効になっている可能性があります。
CDEV は leaps_fw_update_xfer によって FW のチャンクを送信します。
CDEV は、最後のチャンクが正常に送信された後、UWBS をリセットします。
ELDR バイナリを更新しています
CDEV は、UWBS の再起動後に再接続します。
CDEV は leaps_fw_update_start によって ELDR の更新を開始します。
CDEV は leaps_fw_update_xfer によって ELDR のチャンクを送信します。
CDEV は、最後のチャンクが正常に送信された後、UWBS をリセットします。
CDEV は UWBS の再起動後に接続し、FW 情報を観察してファームウェアが更新されて実行中であることを確認できます。
CDEV は、UWBS の自動切断を防ぐために、UWBS に接続するたびに API 応答 特性に関する通知を有効にする必要があります (自動切断 を参照)。
ファームウェアのアップデート中に UWBS が突然切断された場合は、アップデートの現在の段階に応じて、ステップ 7 またはステップ 1 からやり直すことで処理できます。
FWバイナリを送信しています
データは、leaps_fw_update_start によってファームウェアのアップデートが開始された後、leaps_fw_update_xfer によって UWBS に転送されます。 UWBS は、サイズとオフセットを応答にエンコードすることで、CDEV にどのデータ バッファーが必要かを正確に伝えます。 CDEV は、応答なしの書き込みを使用して、要求されたバッファ チャンクの送信を開始するため、完全な往復は必要ありません。 BLE 転送の MTU に要求されたバッファ サイズが含まれない場合、各チャンクは複数の BLE 転送で送信される可能性があることに注意してください。チャンクは次のもので構成されます:
データ: UWBS によって要求されたサイズの FW バッファ (240)
相対オフセット (最初から): 4 バイト。
データ バッファーが送信された後、CDEV はさらなる命令を待ちます。送信中、UWBS は通常、ファームウェアの連続バイト シーケンスを取得するために、データ バッファを 1 つずつ順番に要求します。現在のバッファ送信が失敗するなど、例外が発生した場合、ノードは予期しないバッファを要求する可能性があります。
エラーが発生するとファームウェアのアップデートが停止されるため、再度開始する必要があります。
送信を終了しています
最後のデータ チャンクが正常に受信されると、UWBS は CDEV に完全なファームウェア バイナリを受信したことを通知します。それを受信すると:
CDEV は、leaps_reset コマンドによって UWBS をリセットします。これにより、UWBS が CDEV から切断されます。
CDEV は 1 秒待機します。
CDEV は UWBS に再度接続してファームウェアのステータスを確認しようとします (デバイス情報 を参照)。
付録 - 参考文献
付録 - DWM BLE API からの移行
次の表は、以前の DWM BLE API と比較した LEAPS BLE API の変更点をまとめたものです。これは、LEAPS BLE API への移行を容易にすることを目的としています。DWM BLE API で使用されていた以前の GATT モデルは、以前のモデルよりも特性の少ない要求/応答モデルに置き換えられました。セクション UWBS との BLE 通信 を参照してください。
以前の BLE GATT モデル
名前
以前の GATT 特性
|
DWM と LEAPS の比較 |
|---|---|
ラベル |
DWM: 標準の名前特性 (0x2A00) の下にある標準の必須 GAP サービス (0x1800)
LEAPS: 変更なし、同じまま
|
動作モード |
DWM: UWBS の現在の構成は特別なファイルに含まれていました
特性
LEAPS: UWBS の設定の読み取り/書き込みについては 動作モード を参照、ファームウェア 1 とファームウェア間の切り替えについては ファームウェアのアップデート を参照してください。 2.
|
更新レート |
DWM: 現在の更新レートは特別な特性 LEAPS に含まれていました: 現在の更新レート設定の読み取り/書き込みについては、セクション 更新レート を参照してください |
ネットワークID |
DWM: 現在のネットワーク ID は特殊特性 LEAPS に含まれていました: 現在のネットワーク ID の読み取り/書き込みについては、ネットワークID セクションを参照してください |
位置データモード |
DWM: |
位置データ |
DWM: UWBS の現在位置 (自動位置決め手順を実行するときの距離も含まれます) は特別な特性 LEAPS に含まれていました: 位置と距離を取得するには、位置データ セクションを参照してください |
永続的な位置 |
DWM: 永続化された位置は特殊な特性を介して書き込まれました
LEAPS: UWBS に永続的な位置を書き込む方法については、ユーザーデータ セクションを参照してください。
|
デバイス情報 |
|
統計 |
DWM: 統計は特別な特性に含まれていました LEAPS: 統計はサポートされなくなりました |
MAC 統計 |
DWM: MAC 統計は特別な特性に含まれていました LEAPS: MAC 統計はサポートされなくなりました |
クラスター情報 |
DWM: UWB クラスター情報は特殊な特性に含まれていました LEAPS: クラスター情報はサポートされなくなりました |
アンカーリスト |
DWM: 隣接アンカー ノードの現在のリストは特殊な特性に含まれていました
LEAPS: アンカー ノードの現在のリストを読み取るには、セクション アンカーリスト を参照してください。
|
FWアップデートのプッシュ |
DWM: 新しいファームウェアを UWBS に転送するためにも使用される特別な特性を介してファームウェアの更新が開始されました。
LEAPS: ファームウェアのアップデートを開始する方法とファームウェアをノードに転送する方法については、セクション ファームウェアのアップデート を参照してください。
|
FW アップデートのポーリング |
DWM: UWBS は、この特性に関する通知を使用して、ファームウェアの更新中に BLE セントラルに応答しました
LEAPS: ファームウェアのアップデートの実行方法については、ファームウェアのアップデート セクションを参照してください。
|
切断 |
DWM: BLE セントラルは特殊な特性を介して切断されます。これは API のバグに対処するための回避策でした
LEAPS: バグが修正されているためサポートされていません
|