BLE 网关传感器节点
AHT20 + BMP280 → WS53 BLE (Bluetooth Low Energy) Sensor Node → 外部 Gateway，支持二进制环境数据上报和采样周期回写
前置阅读：Hello Notify 和传感器上报
WS53 不支持 BLE Central（中心设备）/GATT Client（客户端）功能。本案例仅实现网关场景中的 Sensor Node Server：采集温度、湿度和气压，通过 BLE 向外部 Gateway 上报。Gateway 可使用 WS63 配套 Client 或其他支持 GATT Client 的设备实现。
学习目标
- 完成 AHT20、BMP280 共用 I2C0 总线的数据采集
- 理解文本传感器报告与固定长度二进制协议的取舍
- 掌握 14 字节环境报告的 little-endian 编解码方式
- 理解 Gateway 如何通过 GATT Write 回写采样周期
- 能够验证传感器采集、Notification 上报和周期更新
基本概念
为什么 Sensor Node 需要 Gateway
Sensor Node 负责传感器采集和低功耗近距离通信，不直接承担 Wi-Fi、云端鉴权或 MQTT 等 IP 网络功能。Gateway 在 BLE 与上层网络之间完成协议转换。
flowchart LR
A[AHT20 + BMP280] -->|I2C0| N[WS53 Sensor Node]
N -->|14 字节 BLE Notification| G[External Gateway]
G -->|可选| C[本地应用或云端]
C -->|采样周期命令| G
G -->|6 字节 GATT Write| NWS53 仓库不提供 Gateway Client、Wi-Fi 桥接或云端上报实现。外部 Gateway 接收报告后的存储、JSON 转换、网络上传和安全认证由其应用自行完成。
二进制环境报告
Sensor Node 每次发送固定 14 字节报告：
| 偏移 | 长度 | 字段 | 编码与单位 |
|---|---|---|---|
| 0 | 1 | version |
协议版本，当前为 1 |
| 1 | 1 | node_id |
节点 ID，当前固定为 1 |
| 2 | 4 | sequence |
递增序号，little-endian |
| 6 | 2 | temperature_x10 |
有符号温度，单位 0.1 ℃，little-endian |
| 8 | 2 | humidity_x10 |
相对湿度，单位 0.1%RH，little-endian |
| 10 | 4 | pressure_pa |
气压，单位 Pa，little-endian |
协议允许的字段范围：
| 字段 | 范围 |
|---|---|
node_id |
必须为 1 |
sequence |
不能为 0 |
| 温度 | -40.0～85.0 ℃ |
| 相对湿度 | 0.0～100.0%RH |
| 气压 | 30000～110000 Pa |
固定长度二进制格式比传感器上报的 ASCII 文本更紧凑，但 Client 必须严格按偏移、符号位和字节序解析。
采样周期命令
Gateway 通过 Data Characteristic 写入固定 6 字节命令：
| 偏移 | 长度 | 字段 | 说明 |
|---|---|---|---|
| 0 | 1 | version |
必须为 1 |
| 1 | 1 | command |
1 表示设置采样周期 |
| 2 | 4 | interval_s |
5～3600 秒，little-endian |
设置 10 秒周期的命令为：
WS53 先检查 Handle、长度、协议版本、命令类型和周期范围，只有全部通过后才更新周期并返回成功。
GATT 数据通道
| 对象 | UUID | 属性 | 用途 |
|---|---|---|---|
| Environment Service | 0x3333 |
Primary Service | 标识环境节点服务 |
| Data Characteristic | 0x3434 |
Read、Write | 接收采样周期命令 |
| Report Characteristic | 0x3435 |
Notify | 上报 14 字节环境报告 |
| Report CCCD | 0x2902 |
Read、Write | Gateway 写入 01 00 开启 Notification |
端到端流程
sequenceDiagram
participant M as AHT20 + BMP280
participant N as WS53 Sensor Node
participant G as External Gateway
N->>N: 建立 GATT 表并广播 sensor_node
N->>M: 初始化 I2C0 和传感器
G->>N: 连接、配对和服务发现
G->>N: 写 CCCD = 01 00
loop 每个采样周期
N->>M: 读取温度、湿度和气压
M-->>N: 原始测量数据
N->>N: 补偿并编码 14 字节报告
N-->>G: Notification
G->>G: 校验版本、长度、范围和序号
end
G->>N: Write 01 01 <interval_s LE32>
N->>N: 校验并更新采样周期涉及 API
| API | 用途 |
|---|---|
uapi_pin_set_mode() |
配置 MGPIO21、MGPIO22 的 I2C0 复用 |
uapi_i2c_master_init() |
以 100 kHz 初始化 I2C0 |
uapi_i2c_master_write() / uapi_i2c_master_read() |
访问 AHT20 |
uapi_i2c_master_writeread() |
读取 BMP280 寄存器 |
gatts_register_server() |
注册 Sensor Node GATT Server |
gatts_add_service_sync() |
创建 Environment Service |
gatts_add_characteristic_sync() |
创建 Data 和 Report Characteristic |
gatts_add_descriptor_sync() |
创建 Report CCCD |
gatts_notify_indicate() |
发送环境报告 Notification |
gatts_send_response() |
回复周期命令写请求 |
案例说明
功能规格
| 规格项 | 当前实现 |
|---|---|
| I2C 总线 | I2C0，SDA=MGPIO22、SCL=MGPIO21、100 kHz |
| 传感器 | AHT20 0x38、BMP280 0x76/0x77 |
| BLE 设备名 | sensor_node |
| BLE Service UUID | 0x3333 |
| 报告长度 | 14 字节 |
| 默认节点 ID | 1，不支持运行时修改或持久化 |
| 默认采样周期 | 10 秒 |
| 周期范围 | 5～3600 秒 |
| 连接角色 | WS53 仅作为 Peripheral/GATT Server |
源码对应关系
| 内容 | 源码位置 |
|---|---|
| 案例入口 | src/application/samples/bt/ble/ble_gateway/ble_gateway.c |
| 二进制协议编解码和范围检查 | ble_gateway/inc/ble_gateway_protocol.h |
| GATT Server 和报告循环 | ble_gateway_server/src/ble_gateway_server.c |
| AHT20/BMP280 驱动 | ble_gateway_server/src/ble_gateway_sensor.c |
| 广播数据和参数 | ble_gateway_server/src/ble_gateway_server_adv.c |
案例操作指导
第一步：连接传感器
| 传感器信号 | WS53 | 说明 |
|---|---|---|
| VCC | 3.3 V | 使用 3.3 V 供电 |
| GND | GND | 必须共地 |
| SDA | MGPIO22 | I2C0 数据线，PIN_MODE_3 |
| SCL | MGPIO21 | I2C0 时钟线，PIN_MODE_3 |
模块与开发板均断电后再接线，以模块 PCB 丝印为准。
第二步：配置案例
CONFIG_SAMPLE_ENABLE=y
CONFIG_ENABLE_BT_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_BLE_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_BLE_GATEWAY_SERVER_SAMPLE=y
BLE 案例使用 Kconfig choice 互斥选择，同一固件中只能启用一个 BLE 示例。
第三步：编译和烧录
第四步：验证传感器节点
- 复位 WS53，确认 AHT20、BMP280 初始化成功并开始广播
sensor_node。 - 使用 WS63 Gateway Client 或 BLE 调试工具连接 WS53。
- 发现 Service
0x3333和 Report Characteristic0x3435。 - 向 Report CCCD 写入
01 00。 - 接收并按协议解析 14 字节报告。
[aht20+bmp280] AHT20 ready, status=0x0c
[aht20+bmp280] BMP280 ready, addr=0x77 id=0x58
[ble environment node] sample ready: node=1 seq=2 temp_x10=301 hum_x10=548 pressure=100984 Pa
第五步：验证周期回写
向 Data Characteristic 0x3434 写入：
该命令将周期设置为 20 秒。除检查写响应成功外，还应观察后续至少两次样本的间隔是否变为约 20 秒。
关键配置
| 参数 | 当前值 | 说明 |
|---|---|---|
| 协议版本 | 1 | Client 必须检查版本再解析 |
| 节点 ID | 1 | 当前只支持单个固定节点 ID |
| 报告长度 | 14 字节 | 长度不符时应拒绝解析 |
| 命令长度 | 6 字节 | 长度、版本或类型错误时 WS53 拒绝执行 |
| 采样周期 | 默认 10 秒，范围 5～3600 秒 | 调小会增加 I2C 和无线活动 |
| 多字节编码 | little-endian | 包括序号、物理量和周期 |
当前协议没有节点 ID 持久化、协议版本协商或多节点连接管理。扩展产品功能时，应新增版本对应的解析分支，不要直接改变现有字段含义。
代码详解
1. 报告编码
ble_gateway_encode_report() 按固定偏移写入报告。温度先转换为 int16_t 的补码表示，再按 little-endian 写入；Gateway 解析时需要恢复有符号值。
2. 周期命令校验
ble_gateway_decode_interval_command() 依次检查数据指针、6 字节长度、版本、命令类型和 5～3600 秒范围。校验通过后才更新上报循环使用的周期。
3. 传感器异常恢复
传感器初始化或读取失败时，上报任务保留 BLE Server 并按当前周期重试，不因一次 I2C 错误退出。传感器恢复后可以继续产生报告。
常见问题
- AHT20 或 BMP280 初始化失败：检查 3.3 V、共地、MGPIO22/MGPIO21、I2C 上拉和 BMP280 地址。
- 能看到采样日志但收不到报告：确认 Gateway 已连接并成功写入 Report CCCD。
- 报告解析失败：检查长度是否为 14、协议版本是否为 1，以及多字节字段是否按 little-endian 解码。
- 周期命令被拒绝：检查长度是否为 6、命令类型是否为 1、周期是否处于 5～3600 秒。
- 需要上云：WS53 案例不包含 Gateway Client、Wi-Fi 或云端代码，需要在外部 Gateway 上实现。