BLE 接口

简介

本页描述了通过蓝牙低功耗 (BLE) 链接提供的 LEAPS UWB 子系统应用程序接口 (UWBS).

在 UWBS BLE API 设计中，UWBS 模块作为 BLE 外围设备，可通过 API 与 BLE 中央设备通信. 本文件将介绍 BLE 中央装置可用于通讯的 API.

注解

如果Linux上的蓝牙完全停止运作，请使用以下指令重新启动蓝牙:

systemctl restart bluetooth.service

使用术语

  • UWBS: LEAPS UWB 子系统模块. UWBS 在 BLE 通讯中扮演 BLE 外围设备的角色.

  • CDEV: 连接 UWBS 外围设备的 BLE 中央设备.

  • ELDR: 扩展加载器.

位置表示

在实时定位系统中显示位置和距离时，有两件事需要考虑:

  • 准确性

  • 精度

精度是指节点报告的位置与实际位置之间的误差. 目前，本设计中使用的 UWBS 可提供约 10 厘米的精度.

精度是指最小有效位（LSB）的值. 在本系统的板载固件中，精度为 1 毫米，即 0.001 米. 位置以三维坐标（X, Y, Z）表示，其中 X, Y 和 Z 各为 32 位整数（4字节）. 每个 LSB 代表 1 毫米. 这样做是为了更容易解释数值和更容易计算所报告的数值.

在决定精度时，重要的是要结合准确度来选择，这样才能得到有意义的结果. 如果精度低，向用户显示精确值也是无用的. 就目前 10 厘米的精度而言，1 毫米的精度过于精细. 因此，在安卓应用程序中，使用的精度为 1 厘米，即 0.01 米. 只有当坐标/距离变化超过 1 厘米时，Android 应用程序才会显示更新值？这类似于将浮点数/二进制数值舍入到有意义的小数位数.

与 UWBS 进行 BLE 通信

BLE 中央设备直接与 UWBS 连接，以设置和检索
参数. 它需要单独连接到每个设备进行配置/控制. 与 UWBS 的通信是基于请求-响应模型(参见 BLE GATT 模型).
UWBS 接受 TLV API 请求，并将 TLV API 响应通知中心. BLE 中心必须在任何请求之前启用通知功能，以接收响应. UWBS 一次只支持一个请求. 有关 UWBS 可识别的所有 TLV 框架的编码详情，请参阅 LEAPS API. 除了接受请求，UWBS 还会生成事件. 要启用事件:
所有 API 请求, 响应和事件的有效载荷都以一个 2 字节长的 TLV 标头开始，其中第一个字节对应于帧的类型，第二个字节代表帧的长度. 在通过 BLE 特性进行流式传输时，长度应被用于检查帧是否完整.

BLE LUS（LEAPS UART 服务）接口

LEAPS UWBS 支持额外的 BLE LUS (LEAPS UART Service) 接口, 请按照以下步骤设置接口.

注解

如果正在开启 UART shell，将无法访问 BLE shell.

  1. 用下面的命令安装 python ble-serial 库:

    python -m pip install ble-serial==2.7.1

    注解

    如果使用的是 Windows 系统，请按照此链接 ble-serial 中的 “Windows 附加步骤” 进行操作.

  2. 使用下面的命令查找设备. LEAPS 显卡的名称应该是 “LEAPS….”.

    ble-scan

    以及成功扫描的结果：

    ../../../../_images/ble-lus-scan.png

  3. 要连接串行端口，请打开终端并运行以下命令，并输入在上述步骤中找到的

    ble-serial -d CA:E5:56:1F:57:3D -r e8573d97-6758-11e9-8860-cb4385c24b83 -w e6bfa235-6758-11e9-979f-5b24c4603eb8 -t 10

  4. 如果连接成功，将显示如下内容

    ../../../../_images/ble-lus-passed.png

  5. 根据日志，脚本创建了一个名为 “/tmp/ttyBLE” 的串口，用于与 LEAPS 板上的串口通信. 运行该终端，打开另一个终端，使用 minicom 等工具访问该串口.

  6. 按双击回车键进入 shell.

自动断开连接

如果 CDEV 没有通过向 CCCD 写入 0x0001 来启用 “（API Response）” 或 “（API Events）” 特征的通知，UWBS 将在 15 秒后自动终止连接（参见 BLE GATT 模型）.

BLE 吞吐量

使用最大可能的 ATT MTU 和最高的连接优先级，以便在与 UWBS 之间进行数据流传输时，利用最大可能的吞吐量. UWBS 支持的最大 MTU 为 150 字节. 节点首选的连接间隔为最小 10 毫秒到最大 40 毫秒，延迟为 0，超时 2 秒. 请注意，在蓝牙 v4.0 和 v4.1 中，无论 MTU 协商与否，最大数据长度都会保持默认值，因此与蓝牙 v4.2 及更高版本相比，这些蓝牙版本的最大吞吐量会受到限制.

安全/加密

系统支持两种 BLE 操作模式：无加密或仅加密 (AES-OFB). 加密功能和操作将在下一节中说明：

  • 功能

    • 访问控制和信息完整性 (MIC/MAC - 信息完整性代码或信息验证码)

    • 保密性

    • 重放保护

  • BLE 无线加密采用 AES OFB 128 密码.

  • 在加密网络中，每个想要参与通讯的节点，都需要有一个由用户设置的128位对称密钥.

    • 在LEAPS Android管理器里:通过设置

    • On module:UART/SPI/UserApp/Shell API

  • 加密/解密是分块进行的，每个块的大小固定为 16字节. 因此，加密有效载荷的大小必须取整为 16 字节的倍数. 换句话说，如果启用了安全功能，信息的有效载荷必须对齐到 16 字节的倍数. 如果禁用加密，则有效载荷不得对齐到 16 字节.

  • 每条信息将包含

    • Nonce - 16 字节

    • MIC/MAC - 2 字节

    • 有效载荷 (如果启用加密，对齐为 16 字节)

    • See also 信息编码

  • 下图解释了如何使用AES加密数据

    • In red: 密钥，必须保护

    • In blue: 公共数据 - 分布在每条 BLE 信息中

    • In grey: 加密加速器/控制器

    • In yellow: 计算/加密区块

    • In green: 明文/解密区块

../../../../_images/encryptedusingaes.png

  • 下图解释了如何使用 AES OFB 对数据进行加密和链式处理

../../../../_images/aes_ofb.png ../../../../_images/aes_ofb_02.png

  • 参与加密网络的节点要求

    • 使用正确的Nonce进行加密/解密

    • 拥有 128 位 AES 密钥

  • 有两种nonce - 用于信息加密/解密的nonce和用于信息完整性检查的nonce.

    • 每个加密/解密nonce的长度为16字节. 发送方生成并在发送的信息中嵌入nonce. 在解密过程中，接收方会使用收到的nonce作为初始化向量（IV）.

    • 每个完整性 nonce 长度为 16 字节. 它从接收到的信息 nonce 中提取，并将其 nonce 递增 1.

  • 为了抵御中继攻击，每个nonce都必须是唯一的，在网络中的任何时候，任何信息都不能重复使用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 请求

最大变量 50 字节

信息头 + TLV 编码的 API 请求

WO

e8573d96- 6758-11e9- 8860-cb4 385c24b83

API 响应

最多 273 字节

信息头 + TLV 编码的 API 响应

RO

003bbdf2- c634-4b3d- ab56-7ec889 b89a37

API 事件

最多 273 字节

信息头 + TLV 编码的 API 事件

RO

注解

标签特性是一个特殊特性. 它是标准 “名称” 特性（0x2A00）下标准强制 GAP 服务（0x1800）的一部分.

信息编码

项目

长度

有效载荷

传输头

2字节

索引(1字节) 合计(1字节)

无

16字节

无信息，如果关闭了安全机制，则与此无关

mic/mac

2字节

如果启用加密，则进行信息完整性检查；如果禁用加密，则进行有效载荷的简单字节总和检查

付费

从 0 到 255 字节

值或 TLV 编码帧（取决于特定特性）

操作模式

使用 API 请求 leaps_cfg_get 读取当前配置. 使用 leaps_cfg_anchor_set 和 leaps_cfg_tag_set API 请求来设置 UWBS 配置.

位置数据

使用 API 请求 leaps_loc_get 来读取包含位置, 距离或两者的位置数据. 使用请求 leaps_pos_set 和 leaps_pos_get 只操作 UWBS 位置.

通过 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
类型0x40表示请求/命令状态
类型0x41表示位置

上一表格中的残留帧

类型

长度

价值

uint8_t - 值中编码的距离数

uint16_t - UWB 地址，小端序

uint32_t - 小端序中的距离（单位：毫米）

uint8_t - 距离品质因数，以百分比表示 (0-100)

标准13字节格式的位置(x,y,z,qf)

…

0x49

0x51

0x04

位置和距离 nr.2,3,4

nr. 2, 3, 4

类型0x49表示测距锚的位置和距离

用户数据

通过 leaps_ble_evt_cfg_set 启用事件 “用户数据就绪”，并接收关于特征 “事件” 的通知，以自动从UWBS接收ble用户数据.

BLE用户数据编码，作为特征 “事件” 的BLE通知接收

类型

长度

价值

最大128字节

0x51

0x80

0x01 0x02 0x03 … 0x7F 0x80

节点 id

使用请求 leaps_node_id_get 来读取 UWBS 的地址.

网络id

使用请求 leaps_panid_set 和 leaps_panid_get 来操作网络 ID.

重置或重启

重置 UWBS 的请求，如 leaps_reset 或 leaps_factory_reset 会在重置前断开 BLE 中央连接. 中心应等待 1 秒后再重新连接.

锚点列表

参见请求 leaps_anchor_list_get.

设备信息

请参阅请求 leaps_dev_info_get 来读取固件, 硬件和配置的版本.

更新率

请参阅请求 leaps_upd_rate_set 和 leaps_upd_rate_get 来更改标签节点的更新率.

自动定位

BLE API 也能启动自动定位程序. 自动定位过程已在 CDEV 上完成（位置已计算）. BLE API 可启动距离测量和检索. 工作流程如下:

  1. 测量:

    1. 找到并验证启动器 (节点必须是 真正的启动器，而不仅仅是 配置为启动器，请参阅 操作模式 和 BLE 广告)

    2. 连接到启动器.

    3. 如果尚未启用，通过 leaps_ble_evt_cfg_set 启用 “位置就绪” 事件（不要忘记启用 BLE cccd 特性通知）.

    4. 通过 leaps_autopos_start 请求启动自动定位.

    5. 从启动器接收到所有测得的距离，将测得的距离保存到矩阵中.

    6. 断开与启动器的连接.

    7. 获取所有其他（非启动器）节点的距离:

    1. 连接

    2. 使用 API 请求从 UWBS 获取位置数据 leaps_loc_get 从 UWBS 获取位置数据，并将距离保存到矩阵中.

    3. 断开连接

  2. 评估测量距离, 检查正交性并计算位置.

  3. 根据用户请求，将计算出的位置保存到节点上（使用 leaps_pos_set 请求）.

BLE 广告

BLE 广告是外围设备让他人知道其存在的常用方式. 根据 BLE 规范，广播有效载荷由三连串组成，即 [长度, 类型, <数据>].

UWBS 将广播关于其 存在和运行模式 的基本信息. BLE 广告的长度不足以同时包含位置信息.

在BLE广告中，有31个字节需要使用:

  • 3 字节为强制标志（一个 AD 三字节）.

  • 其余的 28 个字节可用于应用程序填写 AD 记录（每条记录有 2 个字节的长度+类型开销）.

存在广播

UWBS 模块上的 BLE 采用可连接的非定向模式工作. 它发布存在广播，其中包含服务可用性和一些服务数据. 存在广播遵循BLE广告帧结构，使用 28 个字节来呈现信息. 设备名称放在扫描响应中，需要主动扫描.

存在广播和扫描响应编码如下表所示.

广告

价值

LEN

0x02

类型

0x01 (标志)

价值

设备/广告标志 - 可连接

LEN

0x19 (25 dec)

类型

0x21 (33 dec, 服务数据)

价值

680c2 1d9-c946-4c1f-9c11-baa1c21329e7 (16字节)

PAN ID (2 字节)

节点 ID (2 字节)
标志（1 字节）
Bit layout: OXSEIBUU O - 操作模式 (标记 0, 锚点 1)
X - 保留
S - security_enabled
E - 错误提示
I - initiator_enabled,
B - bridge_enabled
UU - UWB 模式:关闭 (0), 被动 (1), 主动 (2)

变化计数器 (1 字节) - 每次 UWBS 的重要内部状态发生变化 (例如配置) 时，变化计数器也会随之变化

UWB 计数器（1 字节）–低功耗设备使用的倒计时计数器. 当低功耗设备上的此计数器达到 0 时，设备的 UWB 活动将被禁用. 当锚检测到设备上的计数器低于配置的低水位值时，锚会连接到设备并重置计数器，以保持设备的 UWB 活动.
UWBS 标志（1 字节）
位布局: FUSR
F - 固件类型(2 bits, 0=BLDR, 1=ELDR, 2=MAIN)
U - UWB系统(2 bits, 0=LEAPS RTLS, 1=FIRA)
S - UWB 子系统 (2 bits, 0=UCI, 1=NIQ)
R - 保留,

客户信息 (1 字节) 客户的具体信息

扫描响应

LEN

0x16 (22 dec)

类型

0x09 (设备名称，放置在扫描响应数据包中，使用主动扫描来检测它)

价值

“LEAPS” 前缀 (5 个字符) + 十六进制格式的完整节点 ID（16 个字符）

固件更新

固件更新功能用于更新 UWBS 的固件. 本节描述 BLE 接口的控制和数据流. 有关固件更新过程的更多详情，请参阅 API 请求 leaps_fw_update_start 和 leaps_fw_update_xfer .

更新 FW 二进制文件

  1. CDEV 连接到 UWBS.

  2. CDEV 通过 leaps_fw_update_start 开始更新 FW.

  3. 如果 UWBS 响应状态为 “ok”，CDEV 可以跳过此步骤. 如果 UWBS 响应状态为 “really”，CDEV 将重置 UWBS，并在 UWBS 重启后重新连接，CDEV 将重新开始更新. 如果 UWBS 响应状态为 “不允许”，则无法进行 fw 更新. UWBS 中可能禁用了 fw 更新.

  4. CDEV 通过 leaps_fw_update_xfer 发送 FW 片段.

  5. CDEV 在成功发送最后一个数据块后，会重置 UWBS.

更新 ELDR二进制文件

  1. 在 UWBS 重新启动后，CDEV 重新连接.

  2. CDEV通过 leaps_fw_update_start 开始更新 ELDR.

  3. CDEV 通过 leaps_fw_update_xfer 发送 ELDR 片段.

  4. CDEV 在成功发送最后一个数据块后，会重置 UWBS.

  5. CDEV 可以在 UWBS 重启后连接，并观察 FW 信息，以验证固件更新是否正在运行.

CDEV 应该在每次连接到 UWBS 时，启用 API 响应 特性的通知，以防止 UWBS 自动断开连接 (参见 自动断开连接).

在固件更新过程中，如果 UWBS 突然断开连接，可以根据当前的更新阶段，从步骤 7 或步骤 1 重新开始.

传输 FW 二进制文件

在 leaps_fw_update_start 启动固件更新后，数据会通过 leaps_fw_update_xfer 传输到 UWBS. UWBS 通过在响应中编码大小和偏移量，准确地告诉 CDEV 它需要哪个数据缓冲区. CDEV 开始使用写入（write）方式发送所请求的缓冲区块，而不做响应，因此不涉及整个往返. 请注意，如果 BLE 传输的 MTU 无法容纳所请求的缓冲区大小，则每个数据块可由多个 BLE 传输来传输. 数据块包括:

  • Data: UWBS 要求的fw缓冲区大小(240)

  • 相对偏移（从最开始）:4 字节.

发送数据缓冲区后，CDEV 等待进一步的指令. 在传输过程中，UWBS 通常会一个接一个地按顺序请求数据缓冲区，以获得固件的连续字节序列. 如果出现异常，例如当前缓冲区传输失败，节点可能会请求一个意外的缓冲区.

如果出现错误，固件更新会停止，需要重新启动.

完成传输

一旦成功接收到最后一个数据块，UWBS就会让 CDEV知道它已经接收到完整的二进制固件. 收到后

  1. CDEV 通过 leaps_reset 命令重置 UWBS，这将导致 UWBS 与 CDEV 断开连接.

  2. CDEV 等待 1 秒.

  3. CDEV 尝试再次连接 UWBS 并检查其固件状态（参见 设备信息）.

附录 - 迁移自 DWM BLE API

下表总结了 LEAPS BLE API 与之前的 DWM BLE API 相比的变化. 这样做的目的是为了更容易过渡到 LEAPS BLE API. DWM BLE API 中使用的前 GATT 模型被请求/响应模型取代，该模型比前模型的特性更少，参见 与 UWBS 进行 BLE 通信 部分.

前 BLE GATT 模型

名称
原关贸总协定特性

DWM和LEAPS比较

标签
DWM: 标准名称特性(0x2A00) 下的标准强制 GAP 服务(0x1800)
LEAPS: 无变化，保持不变

操作模式
DWM: 当前的 UWBS 配置包含在特殊的
特性
LEAPS: see 操作模式 读取/写入 UWBS 的配置, 参阅 固件更新 在固件 1 和固件 2 之间切换.

更新率

DWM: 当前更新速率包含在特殊特性 LEAPS 中: 请参阅 更新率 部分以读取/写入当前更新速率配置

网络 ID

DWM: 当前网络ID包含在特殊特征LEAPS中：请参阅 网络id 部分读/写当前网络ID

位置数据模式

DWM: 用作 “位置数据” 这一特殊特性的设置. LEAPS：不再需要，请参阅 用户数据 从 UWBS 获取位置，并参阅 自动定位 部分获取自动定位程序时的距离.

位置数据

DWM:UWBS 的当前位置（在执行自动定位程序时也包含距离）包含在一个特殊的特性中 LEAPS：请参阅 位置数据 一节获取位置和距离.

持续位置
DWM: 持久位置是通过特殊特性写入的
LEAPS: 请参阅 用户数据 部分，了解如何将持久位置写入 UWBS

设备信息
DWM: 设备信息，如配置, 节点 ID 和固件
从特殊特性读取版本信息
请参阅 设备信息 部分读取节点固件版本，请参阅 节点 id 部分读取节点 ID，请参阅 操作模式 部分读取节点配置.

统计

DWM: 统计数据包含在一个特殊的特性中 LEAPS: 统计数据不再支持

MAC 统计

DWM: MAC 统计数据包含在特殊特性 LEAPS 中: 不再支持 MAC 统计

集群信息

DWM: UWB 集群信息包含在一个特殊特性中 LEAPS: 不再支持集群信息

锚点列表
DWM: 当前邻居锚节点列表包含在一个特殊属性中
LEAPS：请参阅 锚点列表 部分来读取当前的锚节点列表

FW 更新推送
DWM: 固件更新通过一个特殊的特性启动，该特性也用于将新固件传输到 UWBS 中.
LEAPS: 请参阅 固件更新 部分，了解如何启动固件更新以及如何将固件传输到节点中

FW更新投票
DWM: UWBS 在固件更新期间使用此特性的通知对 BLE 中心做出响应
LEAPS: 请参阅 固件更新 章节，了解如何执行固件更新

断开连接
DWM: BLE 中央断开连接通过一个特殊的特性，它是处理 API bug 的变通方法
LEAPS: 错误修复后不支持