BLE 接口

在 BLE API 设计中，DWM 模块作为 BLE 外围设备，可以通过 API 与 BLE 中央设备通信. 本文档介绍了 BLE 中央设备可用于通信的 API. 此外，还提供了 Android 应用程序和 PANS PRO Manager 来使用 BLE API.

BLE 中央装置可直接与网络节点连接，以设置和检索参数. 它需要单独连接到每个设备进行配置/控制.

在 BLE 方案中，提供正常的 GATT 操作，包括读取, 写入和通知.

../../../_images/image31.png

上图显示，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 字节), 硬件版本 (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 字节

用于向模块（BLE 外围设备）发送结构化数据（FW 更新数据包），其大小根据最大传输单位（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字节：元素数量（最多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字节

X,Y,Z

每个 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 可启动距离测量和检索. 工作流程如下:

  1. 测量:

    1. 找到并验证启动器（节点必须是*真正的启动器*，而不仅仅是*配置*为启动器*）.

    2. 启动程序/网络已进入测量距离模式：

      1. 确保位置数据模式被配置为距离或位置和距离.

      2. 开始观测位置数据特征（设置ccccd通知）.

      3. 接收来自启动器的所有测量距离，并将测量距离保存到矩阵中.

      4. 停止观测.

    3. 检索所有其他（非启动器）节点的距离:

      1. 连接.

      2. 确保位置数据模式配置为距离或位置和距离.

      3. 直接读取存储在位置数据特征中的值，并将测量的距离保存到矩阵中

      4. 断开连接.

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

  3. 将计算出的位置保存到节点（应用户要求）.

BLE 广告

BLE 广告是外围设备让他人知道其存在的常用方式. 根据 BLE 规范，广播有效载荷由三连串组成，即 [长度, 类型, <数据>]. 锚点和标签将广播有关其**存在和运行模式**的基本信息. BLE 广告的长度不足以同时包含位置信息.

在BLE广告中，使用了 31 字节:

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

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

存在广播

DWM 模块上的 BLE 采用可连接的非定向模式工作. 它发布的存在广播包含服务可用性和一些服务数据. 存在广播遵循 BLE 广告帧结构，使用 28 个字节来呈现信息.

由于 “存在 ”是一个将可连接标志设置为 true 的广播，因此这里必须包含一个 8 字节的本地名称 AD 短记录，以克服潜在的 Android BLE 堆栈错误（如*[1]*所述）. 其余字节填充服务数据: 2 字节的 AD 记录头, 16 字节的 UUID, 1 字节的缩短操作模式和 1 字节的更改计数器.

存在广播帧共有 3 + 20 + 8 字节，即 31字节（共31字节）.

AD三字节 - 部件标识

价值

LEN

0x02

类型

0x01 (标志)

价值

设备/广告标志 - 可连接

LEN

0x13（十进制为 19）

类型

0x21 (SERVICE_DAT).

价值
680c21d9-c946-4c1f-9c11-baa1c21329e7

（16 字节）

Bit layout: OXXEFFUU （1 字节） O - 运行模式（标记 0，锚 #. XX - 保留 E - 错误指示 FF - 标志:启动器, 网桥 UU - UWB:关闭 (0), 被动 (#.), 主动 (2)

更改计数器（1 字节） - 每次更改特征时，更改计数器都会更改（节点统计除外，特别是标签:位置数据#..

LEN

0x07 (最大值)

类型

0x08 (本地名称缩写)

价值

根据 GATT 规范定义的设备本地名称的前 6 字母（或更少）.

BLE 固件更新

固件更新功能用于更新模块的固件. 它可以通过 UWB 或 BLE 执行. 本节将介绍 BLE 的控制和数据流.

在固件更新过程中，固件更新推送 和 固件更新轮询 这两个特性用于实现请求/响应协议.

启动 FW 更新

步骤：

  1. 移动设备*（BLE 中央）会在**FW 更新轮询**特征变化（CCCD）时设置指示.

  2. 移动设备*通过向**FW更新推送**特性发送更新请求/offer数据包，询问网络节点是否愿意执行更新. 该初始化数据包包含固件版本, 校验和以及固件二进制总大小（以字节为单位）. 这个过程是可靠的写入，也称为带响应的写入.

  1. 在两种情况下，网络节点 会对 固件更新轮询 作出有指示的响应:

  • 情况1:是,“给我发送第一个数据缓冲区”. 更多信息，请参阅*传输FW二进制*章节；

  • 情况 2:否，并且 * 错误代码* 提供了拒绝原因.

错误状态:

移动设备:收到明确的 “NO ”指示以及错误代码/原因. 解决方法： 移动设备*在*FW 更新轮询*上禁用 CCCD 指示，并将拒绝原因通知上层. 网络节点： 突然断开连接 解决方法： 离开 FW 更新模式并重置当前状态，就像 FW 更新没有发生一样. 移动设备： 检测到连接已关闭. 解决方法*： 重试. 如果在 FW 更新初始化 30 秒后仍未成功，则向上层报告. 让用户根据要求重新启动固件更新.

传输 FW 二进制文件

本节受 [2] 启发.

网络节点启动数据传输，并准确地告诉移动设备它需要哪个数据缓冲区. 这种通信是通过*FW 缓冲区请求*：大小和偏移量来完成的. 移动设备使用写命令开始以小块形式发送所请求的缓冲区，不需要回应，因此不涉及完整的往返. 基本分块大小等于 MTU，以适合单个传输数据包. 小块包括：

  • 数据:大小应四舍五入为 2 的幂. 当前的数据块大小设置为 32 字节.

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

  • 信息类型标识: FIRMWARE_DATA_CHUNK (= 0x1):1字节

网络节点完全驱动数据传输. 数据缓冲发送完毕后，移动设备等待进一步的指令. 在传输过程中，网络节点通常会按顺序一个接一个地请求数据缓冲区，以获得固件的连续字节序列. 例如，如果出现异常情况，特别是当前缓冲区传输失败时，节点可能会请求一个意外的缓冲区.

错误状态:

网络节点:接收数据时缺少数据块（非连续序列），或数据块顺序不对. 解决方法:发送 FW 缓冲请求，指定丢失的数据块和缓冲区的其余部分. 移动设备：在数据传输过程中收到*FW 缓冲请求*. 解决方法:停止发送数据，将当前偏移量设置为*FW 缓冲请求*中的偏移量，然后重新开始数据传输.

完成传输

一旦成功接收到最后一个数据缓冲区，网络节点将通过*FW更新轮询*的指示，告知移动设备已收到完整的二进制固件.

收到后，移动设备会

  • 断开与网络节点的连接.

  • 等待 500 毫秒.

  • 尝试再次连接网络节点并检查其固件状态.

固件更新推送/轮询格式

FW 更新推送

更新提议/请求- 固件元

类型 == 0 (1 字节)

HW版本 (4 字节)

FW版本 (4 字节)

FW 校验和 (4 字节)

大小 (4 字节)

固件数据块

类型 == 1 (1 字节)

偏移量（4 字节）

数据（最多 32 字节）

FW更新投票

固件缓冲请求

类型 == 1 (1 字节)

偏移量（4 字节）

大小 (4 字节)

信号

类型 == 0 (拒绝上传), 2 (上传完成), 3 (保存失败) 14 (保存失败, 校验和无效) (1 字节)

0 字节