UART 透传#
BLE (Bluetooth Low Energy) GATT (Generic Attribute Profile) Indication、Write Request 与 UART (Universal Asynchronous Receiver/Transmitter) 双向数据桥接
学习目标#
理解 UART 字节流与 BLE 属性数据包之间的差异
掌握 WS53 UART_H1 的接线、初始化和中断接收方式
理解使用环形队列将 UART 回调、BLE 回调和工作任务解耦的方法
理解 ATT MTU、分片、Indication 确认和背压处理
能够使用外部 BLE Client 验证 UART_H1 与 BLE 的双向透传
规格与功能#
WS53 不支持 BLE Central(中心设备)/GATT Client(客户端)功能。本案例将 WS53 作为透传 Server,由 WS63 BLE UART Bridge Client、手机或 PC BLE 调试工具承担 Client。
规格项 |
WS53 透传 Server |
外部 Client |
|---|---|---|
BLE 角色 |
Peripheral / GATT Server |
Central / GATT Client |
设备发现 |
广播 |
扫描并识别该设备 |
GATT Service UUID |
|
发现 |
Data Characteristic |
|
写入需要通过 UART 输出的数据 |
UART Indication Characteristic |
|
订阅并接收 UART 输入数据 |
UART 接口 |
UART_H1,MGPIO12 TX、AGPIO4 RX |
根据 Client 平台确定 |
UART 参数 |
115200 bit/s、8 数据位、1 停止位、无校验、无流控 |
- |
UART 工作方式 |
中断接收,不使用 DMA |
- |
软件环形队列 |
RX、TX 各 640 字节存储,有效容量各 639 字节 |
- |
目标 ATT MTU |
247 字节 |
需要支持并完成协商 |
单个 BLE 分片 |
最大 244 字节 |
同左 |
断连行为 |
重新广播并保留尚未确认的数据 |
由 Client 自行恢复连接和订阅 |
程序运行流程:
WS53 初始化 UART_H1、事件信号量、双向环形队列和 BLE Server。
WS53 建立 GATT 服务并广播
uart1_bridge。外部 Client 连接、配对、协商 MTU、发现服务并向 CCCD 写入
02 00。WS53 先发送
uart_from_peripheral握手 Indication;收到确认后才开放 UART 数据发送通道。UART_H1 收到数据后写入 RX 队列,工作任务按当前 MTU 分片发送 Indication。
Client 向 Data Characteristic 写入数据后,WS53 将数据写入 TX 队列,再由工作任务输出到 UART_H1。
UART 数据 Indication 只有确认成功后才消费 RX 队列;失败或断连时保留数据并重试。
基本概念#
UART 字节流与 BLE 数据包#
UART 提供连续字节流。发送方一次写入多少字节,不代表接收回调会一次返回相同长度;串口空闲、驱动缓冲区状态和任务调度都可能改变回调分段。
BLE GATT 以具有明确长度的属性操作传输数据。ATT MTU 为 247 时,扣除 3 字节协议开销,本案例每个分片最多承载 244 字节。
对比项 |
UART |
BLE GATT |
|---|---|---|
数据模型 |
连续字节流 |
有长度的数据包 |
单次边界 |
不保证与发送调用一致 |
每个属性操作有明确长度 |
速度约束 |
波特率和帧格式 |
连接参数、MTU 和协议栈队列 |
拥塞表现 |
驱动或软件队列溢出 |
API 返回忙、失败或等待确认 |
本案例处理 |
写入环形队列 |
取出不超过当前 MTU 限制的分片 |
透传表示保持字节内容和顺序,不表示 UART 的每次写调用与 Client 的每次接收回调一一对应。验证长数据时应比较总长度和完整内容,而不是比较回调次数。
双向数据路径#
flowchart LR
A[外部 UART 设备发送] --> B[WS53 UART_H1 RX]
B --> C[UART RX 环形队列]
C --> D[BLE Indication 0x4546]
D --> E[外部 BLE Client]
E --> F[BLE Write 0x4545]
F --> G[UART TX 环形队列]
G --> H[WS53 UART_H1 TX]
H --> I[外部 UART 设备接收]
UART 到 BLE 方向使用 Indication;BLE 到 UART 方向使用 Write Request 或 Write Without Response。Client 使用 Write Without Response 时不会收到 ATT 写响应,仍需在应用层自行判断业务是否成功。
为什么使用两个环形队列#
UART 和 BLE 回调由驱动或协议栈触发,不适合执行长时间阻塞操作。本案例使用两个独立队列:
队列 |
生产者 |
消费者 |
保存的数据 |
|---|---|---|---|
UART RX 队列 |
UART 接收回调 |
BLE 工作任务 |
等待发给 Client 的数据 |
UART TX 队列 |
BLE 写回调 |
UART 工作任务 |
等待写入 UART_H1 的数据 |
每个队列使用“保留一个空槽”的方式区分队空和队满,因此 640 字节数组的有效容量为 639 字节。只有当前数据能够完整写入时才更新队列头指针;空间不足时整段拒绝,避免消费者读取到半段数据。
Indication 确认#
同一时刻只保留一个在途 UART 数据分片。工作任务预读队列数据并发送 Indication,收到确认成功回调后才推进队列尾指针。
Client 向 CCCD 写入 02 00 后,Server 会先发送 20 字节 ASCII 握手消息 uart_from_peripheral。该握手使用同一个 0x4546 Indication Characteristic,但不属于 UART RX 队列数据;Server 收到握手确认前不会发送队列中的 UART 数据。Client 应识别并确认该消息,再开始校验透传载荷。
sequenceDiagram
participant U as UART RX 回调
participant Q as RX 环形队列
participant W as 工作任务
participant C as External BLE Client
U->>Q: 完整写入本次 UART 数据
U-->>W: 唤醒任务
W->>Q: 预读不超过当前最大载荷的数据
W-->>C: Indication
C-->>W: Indication Confirm
W->>Q: 确认成功后消费分片
Indication 确认只表示 Client 协议栈接收了当前分片,不表示 Client 应用或外部 UART 设备已经处理数据。产品需要端到端可靠性时,应增加序号、确认和重传协议。
缓冲、背压与溢出#
环形队列可以吸收短时间突发数据,但不能无限提高 BLE 链路吞吐量。本案例采用以下策略:
RX 或 TX 队列空间不足时整段拒绝,并累计丢弃帧数和字节数。
BLE 提交或确认失败时不消费 RX 队列,短暂退避后重试。
UART 驱动拒绝写入时保留数据;部分写入时只消费实际写入的字节。
UART、BLE 状态和发送完成事件通过信号量唤醒工作任务,队列为空时任务阻塞等待。
持续 UART 输入速率高于 BLE 实际传输速率时,最终仍会出现 UART RX/TX queue overflow。
涉及 API#
API |
用途 |
|---|---|
|
配置 UART_H1 引脚复用 |
|
以 115200 8N1 初始化 UART_H1 |
|
注册 UART 接收回调 |
|
将 BLE 接收数据写入 UART_H1 |
|
在回调和工作任务之间传递事件 |
|
注册连接和配对回调 |
|
注册 GATT Server 读写、MTU 和 Indication 确认回调 |
|
设置 Server 接收 MTU 上限 |
|
连接后请求 MTU 交换 |
|
创建 UART Bridge Service |
|
创建 Data 和 UART Indication Characteristic |
|
创建 Indication CCCD |
|
发送 UART 数据 Indication |
案例说明#
GATT 服务#
对象 |
UUID |
属性 |
用途 |
|---|---|---|---|
UART Bridge Service |
|
Primary Service |
标识透传服务 |
Data Characteristic |
|
Read、Write、Write Without Response |
Client 向 WS53 发送 UART 数据 |
UART Indication Characteristic |
|
Indicate |
WS53 向 Client 发送 UART 数据 |
CCCD |
|
Read、Write |
写入 |
源码对应关系#
内容 |
源码位置 |
|---|---|
应用入口、UART 初始化、双环形队列和工作任务 |
|
公共最大载荷和跨模块接口 |
|
GATT Server 逻辑 |
|
广播数据和参数 |
|
案例配置 |
|
案例操作指导#
第一步:连接 UART_H1#
准备 WS53 开发板、3.3 V USB-TTL 模块和杜邦线:
USB-TTL |
WS53 |
说明 |
|---|---|---|
TXD |
板上 pin 4 / AGPIO4 |
UART_H1 RX |
RXD |
板上 pin 12 / MGPIO12 |
UART_H1 TX |
GND |
GND |
两端必须共地 |
WS53 由自身 USB 接口供电时,不需要连接 USB-TTL 的 VCC。不要连接 USB-TTL 的 5 V 或 3.3 V 电源脚,也不要将 5 V TTL 信号接入 WS53。
开发板调试串口用于烧录和日志,外接 USB-TTL 用于 UART_H1 透传数据,两类端口用途不同。
第二步:配置案例#
CONFIG_SAMPLE_ENABLE=y
CONFIG_ENABLE_BT_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_BLE_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_BLE_UART_BRIDGE_SERVER_SAMPLE=y
该选项自动选择 UART_SUPPORT_LPM。为了保持 UART 连续接收,案例会持有 sleep veto,功耗高于允许深睡的应用。
BLE 案例使用 Kconfig choice 互斥选择,同一固件中只能启用一个 BLE 示例。
第三步:编译和烧录#
fbb build ws53_liteos_app
fbb flash ws53_liteos_app
第四步:建立 BLE 通道#
复位 WS53,确认 UART_H1 初始化和
uart1_bridge广播日志。使用 WS63 BLE UART Bridge Client 或 BLE 调试工具连接 WS53。
完成配对和 MTU 协商。
发现 Service
0x4444、Data0x4545和 UART Indication0x4546。向
0x4546对应的 CCCD 写入02 00。确认 Client 首先收到 20 字节 ASCII 握手消息
uart_from_peripheral,并完成 Indication 确认。
[ble uart bridge] UART_H1 ready: IRQ mode, RX queue=639, TX queue=639, no DMA, UART_H1 TX=MGPIO12 RX=AGPIO4 mode2 115200 8N1
[ble uart bridge server] ATT MTU updated: 247
[ble uart bridge server] UART RX indication CCCD enabled
第五步:验证双向透传#
从 USB-TTL 向 WS53 发送:
WS53_H1_TO_BLE_OK
完成握手后,Client 应通过 Indication 收到与 UART 输入相同的字节。再由 Client 向 0x4545 写入:
uart_from_central
USB-TTL 应收到相同字节,WS53 输出:
[ble uart bridge server] BLE write queued to UART TX: bytes=17
关键配置#
参数 |
当前值 |
影响 |
|---|---|---|
UART 波特率 |
115200 bit/s |
外部串口必须使用相同参数 |
UART RX/TX 队列 |
各 639 字节有效容量 |
只能吸收有限突发数据 |
目标 ATT MTU |
247 字节 |
协商成功时最大载荷为 244 字节 |
CCCD |
|
开启 Indication; |
初始握手 |
|
开启 CCCD 后首先发送;确认完成前暂停 UART 队列发送 |
BLE 提交失败退避 |
短暂退避后重试 |
保留未确认数据 |
当前固定 BLE 地址可能与其他案例冲突。量产应用应使用唯一地址或通过 NV (Non-Volatile) 配置地址。
代码详解#
1. UART 回调与工作任务#
UART RX 回调只把完整数据写入 RX 环形队列并唤醒工作任务。工作任务根据连接、CCCD 和 MTU 状态决定是否发送下一包 Indication,不在中断回调中调用耗时的 BLE 流程。
2. BLE 写入到 UART#
GATT 写回调先区分 CCCD Handle 和 Data Handle。Data 数据能够完整进入 TX 队列时才返回成功;随后工作任务调用 uapi_uart_write(),并按驱动实际接受的字节数推进队列。
3. 断连恢复#
断连时案例清除连接、CCCD 和当前 MTU 状态,将在途 Indication 标记为失败但不消费数据,然后重新广播。Client 重连并再次订阅后,工作任务可以继续发送保留的数据。
常见问题#
扫描不到
uart1_bridge:确认固件启用了 UART Bridge Server 案例,并检查 WS53 是否输出广播启动日志。已连接但收不到 UART 数据:确认 Client 已向
0x4546对应的 CCCD 写入02 00。USB-TTL 没有输出:检查 TX/RX 是否交叉连接、是否共地以及串口参数是否为 115200 8N1。
只能单向传输:分别检查
0x4545写入和0x4546Indication 订阅。出现 queue overflow:降低持续输入速率、增加应用层流控,或扩大队列并重新评估 RAM 占用。
MTU 未达到 247:实际分片会按协商结果缩小,不应假设每包始终为 244 字节。