# B-WBA5M-WPAN 评测（二）：BLE 数据上报——从官方例程到自定义多温度源特征
> **评测对象**：ST B-WBA5M-WPAN 蓝牙开发套件（STM32WBA5MMG）> **本篇内容**：BLE_Sensor 例程解析 / Sensor Hub 二次开发 / 新增 TEMP_MULTI_C 特征 / PC 上位机实测> **系列目录**：> （一）开箱、硬件资源与开发环境搭建> （二）BLE 数据上报（本篇）> （三）与 STM32U3C5 载板"合体"——M.2 UART 桥接、双向通道与总结
---
## 前言
第一篇里工具链和点灯都通了，本篇进入正题——**BLE 数据上报**（评测任务 2）。
计划要求"基于 Cube 包中的蓝牙例程，快速实现"。我的路线是：先跑通官方 `BLE_Sensor` 例程，验证与手机 App 的联动；再做一次有实际意义的二次开发——移植一个 **Sensor Hub 传感器抽象层**，并新增一个自定义 GATT 特征 **TEMP_MULTI_C**（多温度源上报），最后用自写的 PC 上位机完成数据接收验证。
---
## 一、官方 BLE_Sensor 例程解析
### 1.1 工程架构
`BLE_Sensor` 是 ST 官方的"ST BLE Sensor 手机 App 演示"固件，架构是 WBA 系列的标准姿势：
```┌─────────────────────────────────────────┐│  应用层   ble_sensor_app.c  (定时采集/事件) ││  服务层   ble_sensor.c      (GATT 服务/特征) ││  主机栈   STM32_WPAN (BLE host + LL 库)     ││  调度器   Util Seq/Timer（低功耗协作式）      ││  HAL/BSP  SHT40 / ISM330DHCX 驱动           │└─────────────────────────────────────────┘```
几个值得注意的设计：
- **全部业务跑在 Sequencer 任务里**：定时器回调只做 `UTIL_SEQ_SetTask()`，真正的采集和 `aci_gatt_update_char_value()` 都在任务上下文执行——这对射频时序很关键；- ENV（温湿度）与 MOTION（六轴）各自独立定时器（1s / 更快周期），通知使能由 **CCCD** 驱动开关；- 广播数据为 blueST SDK 格式（含 Board ID/FW ID），广播名 `WBA5M_XX`。
### 1.2 GATT 服务速览
服务 UUID：`00000000-0001-11e1-ac36-0002a5d5c51b`（blueST 基础段）
| 特征 | UUID 前缀 | 属性 | 载荷 ||---|---|---|---|| MOTION_C | `0000c000-…` | NOTIFY | [ts16][acc×3][gyro×3]（int16LE） || ENV_C | `00000c00-…` | READ+NOTIFY | [ts16][湿度×10][温度×10]（int16LE） |
### 1.3 手机联机实测
用 **ST BLE Sensor** App（iOS/Android）扫描连接 `WBA5M_xx`：
| 步骤 | 预期 | 实测 ||---|---|---|| 扫描 | 出现 WBA5M_xx 设备 | 【待补】 || 连接 | Environmental Data 页显示温湿度曲线 | 【待补】 || Plot Data | 移动板卡，加速度曲线变化 | 【待补】 |
【图2-1：手机 App 界面截图（待补）】
官方例程"开箱即用"达标。下面开始二次开发。
---
## 二、二次开发：Sensor Hub 抽象层 + TEMP_MULTI_C 特征
### 2.1 为什么做这个
评测后期计划接多种温度源（板载 SHT40、MCU 内部温度、外接 DS18B20/STTS751），如果每种都在业务代码里散写，后面会不可收拾。所以先搭一个**传感器抽象层（Sensor Hub）**：
- 统一的注册/探活/读取接口（`SH_Sensor_t`：probe / init / read 回调 + caps 能力位）；- 新传感器只需在 `g_sensors[]` 注册表里**追加一项**；- 统一输出"多温度源"报文，由新特征 TEMP_MULTI_C 上报。
### 2.2 新增代码结构
```Core/Inc/sensor_hub.h          # SH_Type_t/SH_Status_t/SH_Sensor_t 接口Core/Src/sensor_hub.c          # 注册表 + SHT40 适配器 + SH_BuildTempReport()STM32_WPAN/App/ble_sensor.c/h  # 新增 TEMP_MULTI_C 特征（USER CODE 区）STM32_WPAN/App/ble_sensor_app.c# 通知使能/禁止 + 1s 周期刷新（USER CODE 区）```
关键实现点（全部在 **USER CODE 区**内，CubeMX 再生成安全）：
1. **特征注册**：UUID `0000cc00-0001-11e1-ac36-0002a5d5c51b`（第三字节 0xCC，与 Motion 0xC0/Env 0x0C 区分），属性 READ+NOTIFY，长度 28B：
```cret = aci_gatt_add_char(BLE_SENSOR_Context.Ble_sensorSvcHdle,                       UUID_TYPE_128, (Char_UUID_t *)&uuid,                       SizeTempMulti_C,               /* 28 */                       CHAR_PROP_READ | CHAR_PROP_NOTIFY,                       ATTR_PERMISSION_NONE,                       GATT_NOTIFY_ATTRIBUTE_WRITE,   /* 使能 CCCD 事件 */                       0x10, CHAR_VALUE_LEN_CONSTANT,                       &BLE_SENSOR_Context.TempMulti_CCharHdle);```
2. **属性记录数**：`max_attr_record` 7 → **10**（每特征占 3：声明+值+CCCD）；3. **报文格式**：`[count] + N×[id][status][temp=int16LE,0.1°C]`，缺料/出错时 status 置位、温度填 0x8000 哨兵值；4. **调度**：TEMP_MULTI 复用 ENV 的 1s 定时器（订阅任一方才启动，双方都退订才停止）；5. **CCCD 事件**：在 `ACI_GATT_ATTRIBUTE_MODIFIED` 事件里比对 `CharHdle + 2`（描述符偏移），转发 ENABLED/DISABLED 事件给应用层。
### 2.3 踩坑实录：CubeIDE 逐文件链接
第一次构建直接翻车：
```undefined reference to `SH_Init'undefined reference to `SH_BuildTempReport'```
原因就是第一篇提到的那条规则：**ST 的 CubeIDE 工程逐文件 `<link>` 引用源文件**，把 `sensor_hub.c` 放进 `Core/Src` 目录并不等于"加入工程"。`.project` 里补一条标准条目即解决：
```xml<link> <name>Application/User/Core/sensor_hub.c</name> <type>1</type> <locationURI>PARENT-1-PROJECT_LOC/Core/Src/sensor_hub.c</locationURI></link>```
修复后 Release 构建 **0 errors / 0 warnings**，固件 223 KB（bin）。
> **经验总结**：往 ST CubeIDE 例程里加新文件，"复制进目录 → 编译"是不够的；要么 IDE 里 Add to project，要么手改 `.project`。头文件不需要链接条目，但 include 路径要在 `.cproject` 里有（本例 `Core/Inc` 原本就有，无需改）。
### 2.4 固件版本管理
本轮所有固件统一打版本号放在仓库 `BLE-TEST/firmware/`，配套上位机见第四节：
| 版本 | 文件 | 内容 ||---|---|---|| v2.0.0 | `WBA5M_v2.0.0_BLE_Sensor.{bin,hex,elf}` | 官方例程 + Sensor Hub + TEMP_MULTI_C |
---
## 三、PC 上位机测试
光有手机 App 不够"工程"，我写了一套 PC 端测试工具（Python + Web Bluetooth 双通道），后续每个固件版本都能复用：
### 3.1 命令行版（bleak，macOS/Windows/Linux 通用）
```bashpip3 install bleakpython3 ble_test.py scan          # 扫描 WBA5M_xxpython3 ble_test.py test          # 连接+枚举服务+订阅+解码```
**预期输出**（订阅 TEMP_MULTI_C + ENV_C 后，每秒一次）：
```ENV  ts=  123ms  湿度= 45.6%RH  温度=  25.3°CTEMP_MULTI n=1:[SHT40] OK    25.3°C```
### 3.2 图形版（Web Bluetooth，Chrome/Edge）
`BLE-TEST/web/index.html`，本地起个静态服务即可：
```bashcd BLE-TEST/web && python3 -m http.server 8000# 浏览器打开 http://localhost:8000 → 连接 WBA5M_xx → 点订阅按钮```
页面支持：GATT 枚举、四个特征的订阅与实时解码（含 TEMP_MULTI 按传感器 ID 分列）、原始 HEX 对照、向特征写数据。
【图2-2：上位机连接与数据截图（待补）】
### 3.3 实测记录表
| 项目 | 预期 | 实测 ||---|---|---|| GATT 枚举 | 服务+MOTION/ENV/TEMP_MULTI 三特征 | 【待补】 || TEMP_MULTI_C 通知 | 1s 周期，SHT40 温度与 ENV 一致 | 【待补】 || 未订阅时 | 不发送通知（READ 随时可读） | 【待补】 || 手机 App 并存 | 官方功能不受二次开发影响 | 【待补】 |
【图2-3：TEMP_MULTI_C 通知数据截图（待补）】
---
## 四、性能观察点（留给实测的数据槽）
BLE 上报这类应用，评测帖里最该给的是"数据吞吐与稳定性"的实测，以下指标建议在真机上采集后填入：
| 指标 | 观测方法 | 结果 ||---|---|---|| 连接间隔/延迟 | nRF Connect 连接参数页 | 【待补】 || 通知实际周期抖动 | 上位机记录相邻通知时间戳 | 【待补】 || MTU 协商结果 | Web Bluetooth `server`/GATT 信息 | 【待补】 || 长时间稳定性 | 订阅 ≥30min 掉线次数 | 【待补】 || 双连接并发（手机+PC） | 同时连接行为 | 【待补】 |
---
## 五、本章小结
- 官方 BLE_Sensor 例程开箱即用，手机 App 联动顺畅，任务 2 的"快速实现上报"达成；- 二次开发走了"抽象层 + 新特征"的路子：以后加温度源只改注册表，BLE 侧不动——这是为第三篇（U3C5 合体）和后续外接传感器铺路；- 最大收获是一个通用踩坑经验：**ST CubeIDE 工程逐文件链接，新文件必须显式加入工程**；- PC 上位机（Python/Web Bluetooth）已成型，后续每个固件版本都能直接复用。
**下篇预告**：把 B-WBA5M-WPAN 插上 STM32U3C5 载板"合体"——U3C5 采集 ADC 与电源芯片数据，走 M.2 上的 USART2 桥接进 WBA，再经 BLE 上报；顺带打通 PC→BLE→UART 反向通道，为任务 4 双向固件更新铺路。