BLE インターフェース
BLE API 設計では、DWM モジュールは BLE 周辺機器として機能し、API を介して BLE 中央デバイスと通信できます。このドキュメントでは、BLE 中央デバイスが通信に使用できる API を紹介します。BLE API を実行するために、Android アプリケーションと PANS PRO Manager が提供されています。
BLE 中央デバイスは、ネットワーク ノードに直接接続してパラメータを設定および取得します。設定/制御するには各デバイスに個別に接続する必要があります。
BLE スキームでは、読み取り、書き込み、通知を含む通常の GATT 操作が提供されます。
上の図は、DWM1001 BLE イベント ハンドラーが GATT 操作を汎用 API コマンドに変換していることを示しています。その間、BLE 関連のイベントが発生すると、BLE イベント ハンドラーは対応する通知を BLE クライアントに送信します。
詳細な BLE API は、BLE API セクションで紹介されています。
LE GATTモデル
ネットワーク ノード サービス UUID は 680c21d9-c946-4c1f-9c11-baa1c21329e7 です。すべての特性値は、BLE 仕様が示唆するリトル エンディアンとしてエンコードされます。
ネットワークノードの特性
uuid |
名前 |
長さ |
価値 |
フラグ |
|---|---|---|---|---|
"標準 GAP サービス、ラベル0x2A00" |
ラベル |
Var |
UTF-8 でエンコードされた文字列 |
RW |
3f0afd88-7770-46b0-b5e7-9fc099598964 |
動作モード |
2バイト |
以下のセクションを参照してくださいデータエンコーディングの詳細については |
RW |
80f9d8bc-3bff-45bb-a181-2d6a37991208 |
ネットワークID |
2バイト |
ネットワークの一意の識別 (PAN ID) |
RW |
a02b947e-df97-4516-996a-1882521e0ead |
位置データモード |
1バイト |
0 - 位置 1 - 距離 2 - 位置 + 距離" |
RW |
003bbdf2-c634-4b3d-ab56-7ec889b89a37 |
位置データ |
最大 106 バイト |
以下のセクションを参照してくださいデータエンコーディングの詳細については |
RO |
f4a67d7d-379d-4183-9c03-4b6ea5103291 |
プロキシの位置 |
最大 76 バイト |
BLE セントラルの新しいタグ位置に関する通知としてモジュールによって使用されます。 |
RO |
1e63b1eb-d4ed-444e-af54-c1e965192501 |
デバイス情報 |
29バイト |
ノード ID (8 バイト)、HW バージョン (4 バイト)、FW1 バージョン (4 バイト)、FW2 バージョン (4 バイト)、FW1 チェックサム (4 バイト)、FW2 チェックサム (4 バイト)、RDonly 動作フラグ (1)バイト） |
RO |
1e630001-d4ed-444e-af54-c1e965192501 [PANS PRO] |
デバイスのステータス |
8バイト |
稼働時間 (4 バイト、符号なし整数)、バッテリー レベル (1 バイト、符号なし整数)、予約済み (1 バイト)、温度 (2 バイト、整数) |
RO |
0eb2bc59-baf1-4c1c-8535-8a0204c69de5 |
統計 |
120バイト |
ノード統計 |
RO |
5955aa10-e085-4030-8aa6-bdfac89ac32b |
FWアップデートのプッシュ |
最大 37 バイト |
構造化データ (FW 更新パケット) をモジュール (BLE ペリフェラル) に送信するために使用され、サイズは最大送信単位 (MTU) に従って設定されます。データのエンコードの詳細については、以下のセクションを参照してください。 |
WO |
9eed0e27-09c0-4d1c-bd92-7c441daba850 |
FW アップデートのポーリング |
9バイト |
モジュールによって次のように使用されます。 BLE セントラルの応答/通知。データ エンコーディングの詳細については、以下のセクションを参照してください。 |
RO |
ed83b848-da03-4a0a-a2dc-8b401080e473 |
切断 |
1バイト |
value=1 を書き込むことで BLE ペリフェラルから明示的に切断するために使用されます (Android の動作による回避策) |
WO |
"5b10c428-af2f-486f-aee1-9dbd79b6bccb [PANS PRO 修正済み]" |
アンカーリスト |
65バイト |
カウント (1 バイト)、ノード ID のリスト (2 バイト)、RSSI (1 バイト)、シート (1 バイト) リスト内の最大 16 要素 |
RO |
9d5ab03b-cbf8-4ae5-9f11-63e45f538ada |
AES キー |
16バイト |
AES 対称キー R2 で実装予定 |
RW |
注釈
ラベルの特性は特別なものです。これは、標準の名前特性 (0x2A00) の下にある標準の必須 GAP サービス (0x1800) の一部です。
動作モードの特性
動作モード特性は 2 バイトで、ノードの構成情報が含まれます。形式は次のように定義されます。
1 番目のバイト (ビット 7 から 0 まで) |
|
|---|---|
Bit |
価値 |
7 |
タグ (0)、アンカー (#. |
6 - 5 |
UWB - オフ (0)、パッシブ (#.、アクティブ (2)) |
4 |
ファームウェア 1 (0)、ファームウェア 2 (#. |
3 |
加速度計の有効化 (0, #. |
2 |
LED 表示が有効になりました (0、#. |
1 |
ファームウェアアップデートの有効化 (0, #. |
0 |
BLE が有効になっています (0,#. |
2 番目のバイト (ビット 7 から 0 まで) |
|
|---|---|
Bit |
価値 |
7 |
イニシエーター有効、アンカー固有 (0、#. |
6 |
低電力モード有効、タグ固有 (0、#. |
5 |
位置情報エンジン有効、タグ固有 (0、#. |
4 - 0 |
予約済み |
位置データの特性
位置データの特性には、位置、距離、またはその両方を含めることができます。位置と距離の形式は次のように定義されます:
タイプ (1 バイト) |
価値 |
|---|---|
0 - 位置のみ |
X、Y、Z 座標 (各 4 バイト) + 品質係数 (1 バイト)、サイズ: 13 バイト |
1 - 距離 |
最初のバイトは距離カウント (1 バイト) です。 ノード ID (2 バイト)、距離 (4 バイト)、および品質係数 (1 バイト) のシーケンス。 最大値には 15 個の要素が含まれ、サイズ: 8 ～ 106。 |
2 - 位置と距離 |
エンコードされた位置 (上記の通り、13 バイト) エンコードされた距離 (上記の通り、8 ～ 29 バイト) - 位置と距離はタグによって送信され、測距アンカーの数は最大 4 です。 |
注釈
特性値は完全に空 (長さゼロ) である可能性があります。これは、既知の位置も既知の距離も存在しないことを意味します。
注釈
位置データ モードには位置と距離が含まれますが、位置が不明な場合は特性でのみ距離を受信することも可能です。
プロキシ位置の特性
この特性は、BLE セントラル (モバイル デバイス) に同時に接続されたノードの制限を克服するために提供されています。パッシブ ノードはこの特性を使用して、タグ位置の更新をストリーミング/通知します。
この特性では、データは次のようにエンコードされます。
1 byte: number of elements (max 5)
[シーケンス] タグの位置: 2 バイトのノード ID、13 バイトの位置
したがって、5 つのタグ位置の最大サイズは 76 バイトです。
アンカー固有の特性
アンカーは、 ‘ブリッジ’ および ‘イニシエーター’ と呼ばれる特別なモードで動作する場合があります。これらは直交しており、互いに影響しません。ブリッジ フラグは読み取り専用ですが、ユーザーはイニシエータを設定できます。また、各アンカーにはそのクラスター内のシート番号があります。
UUID |
名前 |
長さ |
価値 |
フラグ |
|---|---|---|---|---|
3f0af d88-7770-46 b0-b5 e7-9fc09959 8964 |
動作モード (上記を参照) |
2バイト |
2 バイト目のビット 7: イニシエータ イネーブル (0、#. (詳細については、サブセクション |
RW |
1e63 b1eb-d4ed-4 44e-a f54-c1e9651 92501 |
デバイス情報 ( |
RD のみ 操作フラグ: BXXXXXXX B: ブリッジ 1/0 |
RO |
|
f0f26c 9b-2c8c-49a c-ab6 0-fe03def1b 40c |
|
13バイト |
各 4 バイトの精度 + 品質係数を調整します (1 バイト、値 1 ～ 100) |
WO |
28d0 1d60-89de-4 bfa-b 6e9-651ba59 6232c |
MAC 統計 |
4バイト |
内部デバッグ MAC 統計用に予約されています |
RO |
17b16 13e-98f2-44 36-bc de-23af17a1 0c72 |
クラスター情報 |
5バイト |
座席番号 (1 バイト)/クラスター マップ (2 バイト)/クラスターの近隣マップ (2 バイト) |
RO |
5b10c4 28-af2f-486 f-aee 1-9dbd79b6b ccb [Not in PANS PRO] |
アンカーリスト |
65バイト |
カウント (1 バイト)、ノード ID のリスト (2 バイト)、RSSI (1 バイト)、シート (1 バイト) リスト内の最大 16 要素 [アンカー固有ではなくなったため、PANS PRO では使用できなくなりました] |
RO |
タグ固有の特性
各タグは、周囲の 4 つのアンカーによって送信された情報に基づいてその位置を決定します。タグは、その位置の計算方法に関する完全な情報を提供します (読み取り専用)。
UUID |
名前 |
長さ |
価値 |
フラグ |
|---|---|---|---|---|
3f0a fd88-7770-4 6b0- b5e7-9fc099 598964 |
動作モード (上記を参照) |
2バイト |
2 バイト目のビット 6: 低電力モード有効 (0、#。2 バイトのビット 5: 位置エンジン有効 (0、#。詳細については、サブセクション``動作モード特性``を参照) |
RW |
7bd4 7f30-5602-4 389 -b069-83057 31308b6 |
更新レート |
8バイト |
レイアウト: U1 (4 バイト)、U2 (4 バイト) 移動中は U1 ミリ秒ごとに新しい位置をブロードキャストし、静止している場合は U2 ミリ秒ごとに新しい位置をブロードキャストします。 |
RW |
BLE 自動位置決め
BLE API を使用すると、自動位置決めプロセスを開始することもできます。モバイルデバイス上で自動位置決めプロセスが完了します (位置が計算されます)。 BLE API を使用すると、距離の測定と取得を開始できます。ワークフローは次のとおりです:
測定:
イニシエータが見つかり、検証されました (ノードは イニシエータ として 構成 されているだけでなく、実際のイニシエータ である必要があります)。
イニシエータ/ネットワークは距離測定モードに設定されます:
位置データ モードが距離または位置と距離に設定されていることを確認してください。
位置データの特性の監視を開始します (cccd 通知のセットアップ)。
イニシエーターからすべての測定距離を受信し、測定距離をマトリックスに保存します。
観察を停止します。
他のすべての (非イニシエーター) ノードからの距離が取得されます。
接続します。
位置データ モードが距離または位置と距離に設定されていることを確認してください。
位置データ特性に保存されている値を (直接) 取得し、測定された距離をマトリックスに保存します
切断します。
評価: 測定距離を評価し、直交性をチェックし、位置を計算します。
計算された位置をノードに保存します (ユーザーの要求に応じて)。
BLE アドバタイズメント
BLE アドバタイズメントは、周辺デバイスがその存在を他のデバイスに知らせる一般的な方法です。 BLE 仕様によれば、ブロードキャスト ペイロードは 3 つの要素、つまり [長さ、タイプ、<データ>] で構成されます。アンカーとタグは、存在と動作モード に関する基本情報をブロードキャストします。 BLE アドバタイズメントは、位置情報を含めるのに十分な長さではありません。
BLE アドバタイズメントでは、31 バイトが使用されます。
3 バイトは必須フラグです (1 つの AD トリプレット)。
アプリは残りの 28 バイトを使用して AD レコードを埋めることができます (各レコードには 2 バイトの長さと型のオーバーヘッドがあります)。
プレゼンスブロードキャスト
DWM モジュールの BLE は、接続可能なアンダイレクト モードで動作します。サービスの可用性と一部のサービス データを含むプレゼンス ブロードキャストをアドバタイズします。プレゼンス ブロードキャストは BLE アドバタイズメント フレーム構造に従い、28 バイトを使用して情報を表示します。
プレゼンスは接続可能フラグが true に設定されたブロードキャストであるため、潜在的な Android BLE スタックのバグを克服するために、8 バイトの短縮ローカル名 AD レコードをここに含める必要があります ([1] で説明されているように)。残りのバイトはサービス データで埋められます。AD レコード ヘッダー用の 2 バイト、UUID 16 バイト、短縮操作モード 1 バイト、および変更カウンター 1 バイトです。
プレゼンス ブロードキャスト フレームは、合計 3 + 20 + 8 バイト、つまり 31 バイト（31 バイト中）です。フレーム構造を次の表に示します。
AD トリプレット - 部分の識別 |
値 |
|---|---|
LEN |
0x02 |
タイプ |
0x01 (フラグ) |
値 |
デバイス/アドバタイズメントフラグ - 接続可能 |
LEN |
0x13（進数で19） |
タイプ |
0x21 (SERVICE_DAT). |
値 |
|
ビット レイアウト: OXXEFFUU (1 バイト) O - 動作モード (タグ 0、アンカー #. XX - 予約済み E - エラー表示 FF - フラグ: イニシエーター、ブリッジ UU - UWB: オフ (0)、パッシブ (#.、アクティブ (2)) |
|
変更カウンタ (1 バイト) - 変更カウンタは、特性が変更されるたびに変更されます (ノード統計および特にタグ: location dat# を除く)。 |
|
LEN |
0x07 (最大) |
タイプ |
0x08 (短縮されたローカル名) |
値 |
GATT 仕様で定義されているデバイス ローカル名の最初の 6 文字 (またはそれ以下)。 |
BLE ファームウェアのアップデート
ファームウェア更新機能は、モジュールのファームウェアを更新するために使用されます。これは、UWB または BLE 経由で実行できます。このセクションでは、制御とデータは BLE 経由で流れます。
FW アップデート中に、FW アップデート プッシュ と FW アップデート ポーリング という 2 つの特性を使用して、要求/応答プロトコルが実装されます。
FW アップデートを開始しています
手順:
モバイル デバイス (BLE セントラル) は、FW アップデート ポーリング 特性変更 (CCCD) に関する表示をセットアップします。
モバイル デバイス は、アップデート要求/オファー パケットを FW アップデート プッシュ 特性に送信することで、ネットワーク ノードにアップデートを実行する意思があるかどうかを尋ねます。この初期化パケットには、ファームウェアのバージョン、チェックサム、およびファームウェア全体のバイナリ サイズ (バイト単位) が含まれます。このプロセスは信頼性の高い書き込みであり、応答付き書き込みとも呼ばれます。
ネットワーク ノード は、次の 2 つの場合に FW 更新ポーリング の指示で応答します。
ケース 1: はい、
最初のデータ バッファーを送信してください。詳細については、FW バイナリの送信 セクションを参照してください。ケース 2: いいえ、エラー コード が拒否理由を示します。
エラー状態:
Mobile device: Received explicit NO indication along with error code/reason. Resolution: The Mobile device disables CCCD indication on the FW update poll and notifies the upper layer about the refused reason. Network node: Sudden disconnect Resolution: Leave the FW update mode and reset the current state as if the FW update did not happen. Mobile device: Detects that connection has been closed. Resolution: Retry. If still unsuccessful after 30 seconds from FW update initialization, report to the upper layer. Let the user re-initiate the firmware update on request.
FWバイナリを送信しています
このセクションは [2] からインスピレーションを受けています。
ネットワーク ノードはデータ送信を開始し、モバイル デバイスにどのデータ バッファが必要かを正確に伝えます。この通信は、FW バッファー要求: サイズとオフセットを使用して行われます。モバイル デバイスは、応答なしで書き込みコマンドを使用して、要求されたバッファを小さなチャンクで送信し始めるため、完全なラウンド トリップは発生しません。基本チャンク サイズは、単一の送信パケットに収まる MTU に等しくなります。チャンクは次のもので構成されます。
データ: サイズは 2 の累乗に丸める必要があります。現在のチャンク サイズは 32 バイトに設定されています。
相対オフセット (最初から): 4 バイト。
メッセージ タイプの識別: FIRMWARE_DATA_CHUNK (= 0x1): 1 バイト
ネットワーク ノードがデータ送信を完全に推進します。データ バッファが送信された後、モバイル デバイスはさらなる命令を待ちます。送信中、ネットワーク ノードは通常、ファームウェアの連続したバイト シーケンスを取得するために、データ バッファを 1 つずつ順番に要求します。たとえば、例外が発生した場合、特に現在のバッファの送信が失敗した場合、ノードは予期しないバッファを要求することがあります。
エラー状態:
ネットワーク ノード: 受信時にデータ チャンクが欠落している (連続していないシーケンス)、または順序が乱れているチャンク。解決策: 欠落しているチャンクと残りのバッファーを指定して FW バッファー要求 を送信します。モバイル デバイス: 進行中のデータ送信中に FW バッファー要求 を受信します。解決策: データの送信を停止し、現在のオフセットを FW バッファー要求 のオフセットに設定して、データ送信を再開します。
送信を終了しています
一度最後のデータ バッファが正常に受信されると、ネットワーク ノードは、FW 更新ポーリング の表示を通じて、完全なファームウェア バイナリを受信したことをモバイル デバイスに通知します。
受信すると、モバイル デバイスは次の処理を行います。
ネットワーク ノードから切断します。
500 ミリ秒待ちます。
ネットワーク ノードに再度接続して、ファームウェアの状態を確認します。
FW アップデートのプッシュ/ポーリング形式
FWアップデートのプッシュ |
|||||
|---|---|---|---|---|---|
アップデートオファー/リクエスト - ファームウェアメタ |
タイプ == 0 (1 バイト) |
HW バージョン (4 バイト) |
FWバージョン(4バイト) |
FW チェックサム (4 バイト) |
サイズ (4 バイト) |
ファームウェアデータチャンク |
タイプ == 1 (1 バイト) |
オフセット (4 バイト) |
データ (最大 32 バイト) |
||
FW アップデートのポーリング |
|||
|---|---|---|---|
ファームウェアバッファリクエスト |
タイプ == 1 (1 バイト) |
オフセット (4 バイト) |
サイズ (4 バイト) |
シグナル |
type == 0 (アップロード拒否)、2 (アップロード完了)、3 (保存失敗) 14 (保存失敗、無効なチェックサム) (1バイト） |
0 バイト |
|