传感器上报#
使用技术:SLE(SparkLink Low Energy)、SSAP(SLE Service Access Protocol) Notification/Indication、AHT20、I2C0、定长应用帧、阈值告警
前置阅读:必须了解 Hello SLE 的扫描与连接流程,建议先完成 Hello Notify 的 Notification 实验。
本案例使用两块 WS53:Server 通过 I2C0 读取 AHT20 兼容温湿度传感器,按固定延时循环组装 11 字节数据帧;Client 扫描名为 sensor_server 的设备,连接、配对并完成服务发现后接收数据。
运行前置修正#
当前 WS53 源码存在两个会影响端到端验证的问题。第一,Server 广播参数中的连接间隔、最大时延和监管超时组合不满足当前 API 的监管超时约束,但 sle_set_announce_param() 的返回值被忽略。第二,常规数据属性 0x5656 只添加了用户描述符,没有客户端配置描述符(CCCD);Client 也只为告警属性写入 0x0002,没有为常规属性写入 0x0001。根据 ssaps_notify_indicate() 的 API 说明,Notification/Indication 的发送状态取决于 CCCD。执行完整上报实验前应先修正这两处源码问题。
学习目标#
掌握 WS53 I2C0 与 AHT20 兼容传感器的接线、初始化、测量和 CRC 校验流程。
理解 11 字节定长应用帧的字段、缩放、端序和时间戳限制。
区分固定延时工作任务与周期定时器,理解当前上报周期为何大于 1000 ms。
理解正常数据属性和告警属性的操作位、描述符及 CCCD 配置关系。
掌握 Client 的扫描、配对、MTU 交换、属性发现和数据接收流程。
能分层验证传感器采样、SLE 建链、常规 Notification、告警 Indication 和指示确认。
识别当前广播参数、描述符配置、属性发现和业务协议方面的源码限制。
基本概念#
固定延时循环不是周期定时器#
Server 入口创建一个永久工作任务。初始化成功后,任务每轮先休眠 1000 ms,再同步读取传感器并尝试发送:
while (1) {
(void)osal_msleep(SENSOR_REPORT_INTERVAL_MS);
sle_sensor_report_server_process();
}
源码没有使用 osal_timer_init()、osal_timer_start() 或定时器回调。因此 SENSOR_REPORT_INTERVAL_MS = 1000 表示相邻两次处理之间的固定等待时间,不是严格的 1 秒采样周期。
AHT20 每次测量至少还包含 80 ms 测量等待,并可能包含状态查询和忙重试等待。串口输出和协议栈调用也会占用时间。因此相邻两次采样的实际间隔通常大于 1080ms 。
若产品要求固定采样频率,应使用绝对时间基准补偿处理耗时,不能直接把这个循环称为“精确 1 秒定时器”。
采样与无线发送是两个阶段#
sle_sensor_report_server_process() 先调用 sensor_aht20_read(),成功后组帧、打印硬件数据,最后才检查:
if (!g_connected || !g_reporting_enabled) {
return;
}
因此:
Server 未连接时仍会周期读取 AHT20 并打印
source=hardware;已连接但配对尚未成功时也会采样,但不会调用
ssaps_notify_indicate();g_reporting_enabled只在配对成功回调中置为true;断链时先关闭上报门控,再清除连接状态和连接句柄。
“串口有传感器数据”只能证明硬件采样成功,不能证明数据已经通过 SLE 发出。
AHT20 测量值与校验#
Server 使用地址 0x38 的 AHT20 兼容器件。驱动的主要步骤为:
配置 MIO21/MIO22 的 PinMux,并以 100 kHz 初始化 I2C0。
读取状态并等待设备空闲;未校准时发送
{0xBE, 0x08, 0x00}。每次测量发送
{0xAC, 0x33, 0x00},等待 80 ms 后读取 7 字节响应。检查忙状态、校准状态和第 7 字节 CRC。
把 20 位原始值换算为温度放大 100 倍和整数湿度百分比。
CRC-8 的初值为 0xFF,多项式为 0x31,计算范围是响应的前 6 字节。温度换算结果只接受 -40.00~85.00 ℃,湿度四舍五入到 0~100 的整数百分比。
这里的 CRC 只校验 AHT20 的 I2C 测量响应。11 字节 SLE 应用帧本身没有 CRC,不能把传感器 CRC 当成端到端无线数据完整性校验。
两个属性与 CCCD#
Server 在服务 0x5555 下添加两个属性:
属性 |
操作指示位 |
当前描述符 |
源码意图 |
|---|---|---|---|
|
READ、NOTIFY |
USER_DESCRIPTION,值 |
正常温度数据 Notification |
|
READ、INDICATE |
CLIENT_CONFIGURATION,初值 |
越阈值数据 Indication |
SSAP_DESCRIPTOR_USER_DESCRIPTION 是属性说明描述符,不是 CCCD。把 {0x01,0x00} 放在用户描述符中,不等于允许 Notification。
WS53 ssaps_notify_indicate() 的 API 说明明确给出客户端配置描述符值:
0x0000:不允许 Notification 和 Indication
0x0001:允许 Notification
0x0002:允许 Indication
当前 Client 在服务发现完成后只向 g_alarm_property_handle + 1 写入 0x0002,没有给正常数据属性写入 0x0001。要可靠验证正常上报,至少需要让 0x5656 具有可写 CCCD,并由 Client 向发现到的真实 CCCD handle 写入 0x0001。
告警是周期采样结果,不是即时中断#
源码的告警条件为:
bool is_alarm = (frame.temperature > TEMP_ALARM_HIGH ||
frame.temperature < TEMP_ALARM_LOW);
其中高阈值为 80.00 ℃,低阈值为 -10.00 ℃。比较使用严格大于和严格小于,所以恰好 80.00 ℃或 -10.00 ℃仍走常规路径。
告警判断只在每次固定延时循环采样后执行,不是传感器中断触发的“立即告警”。只要温度持续越界,每一轮都会尝试发送告警 Indication;源码没有告警边沿检测、去抖、迟滞或最小重复间隔。
头文件还定义了 HUMIDITY_ALARM_LOW = 20,但业务判断没有使用该宏。低湿度不会触发告警。
11 字节应用帧#
Server 和 Client 分别定义了布局相同的 packed 结构体:
typedef struct {
uint8_t frame_type;
uint8_t sensor_count;
uint32_t timestamp;
int16_t temperature;
uint8_t humidity;
uint16_t light;
} __attribute__((packed)) sensor_data_frame_t;
偏移 |
字段 |
长度 |
当前取值或含义 |
|---|---|---|---|
0 |
|
1 |
|
1 |
|
1 |
固定为 2,表示温度和湿度 |
2 |
|
4 |
|
6 |
|
2 |
摄氏度放大 100 倍,有符号 |
8 |
|
1 |
四舍五入后的相对湿度百分比 |
9 |
|
2 |
当前固定为 0,日志显示 |
各字段长度之和为 11 字节。
当前代码直接复制 packed 结构体,未定义网络字节序;Client 也直接把接收缓冲区强转为结构体。两端都是 WS53 时布局一致,但这不是可移植的跨架构协议。uint32_t 毫秒时间戳约 49.7 天回绕一次,帧中也没有版本、序号或应用层校验字段。
涉及 API#
阶段 |
核心 API |
调用方 |
当前用途与注意事项 |
|---|---|---|---|
I2C 引脚 |
|
Server |
可选使能输入,配置 MIO21/MIO22 为 Pin Mode 3 |
I2C 初始化 |
|
Server |
初始化 I2C0,100 kHz;接受“已经初始化”返回值 |
传感器命令 |
|
Server |
AHT20 状态、校准和测量 |
BMP280 探测 |
|
Server |
只读地址 |
广播 |
|
Server |
配置并启动 |
扫描与建链 |
|
Client |
按名称查找 Server、连接并配对 |
MTU 与发现 |
|
Client |
请求 MTU 520,在 |
服务注册 |
|
Server |
注册服务和两个数据属性 |
描述符 |
|
两端 |
Server 添加描述符;Client 当前只写告警 CCCD |
数据发送 |
|
Server |
根据属性和 CCCD 状态发送 Notification 或 Indication |
指示确认 |
|
Server |
只打印确认结果,没有失败重试 |
时间戳 |
|
Server |
秒和微秒换算为 32 位毫秒值 |
案例说明#
功能规格#
项目 |
Server |
Client |
|---|---|---|
硬件 |
WS53 + 3.3 V AHT20 兼容模块 |
WS53,不接传感器 |
角色 |
SLE Peripheral、SSAP Server |
SLE Central、SSAP Client |
广播/匹配 |
扫描响应名称 |
在原始扫描数据中查找该字符串 |
本端地址 |
固定 |
由当前 Client 初始化流程决定 |
采样方式 |
任务固定延时循环,真实 I2C 数据 |
不采样 |
数据帧 |
packed 11 字节 |
要求接收长度严格等于 11 字节 |
正常路径 |
属性 |
Notification 回调打印完整帧 |
告警路径 |
属性 |
Indication 回调打印温度和类型 |
MTU 请求 |
配对成功后调用 |
配对成功后请求 520 |
断链恢复 |
关闭发送门控并重新广播 |
重新扫描 |
端到端流程#
sequenceDiagram
participant H as AHT20
participant S as WS53 Server
participant C as WS53 Client
S->>H: 初始化 I2C0、检查状态与校准
S->>S: 注册服务 0x5555 和两个属性
S->>S: 广播 sensor_server
C->>C: 启动后等待 5000 ms,再使能 SLE
C->>C: 扫描命中名称并停止扫描
C->>C: 删除该地址的旧配对记录
C->>S: 发起连接并重新配对
C->>S: 请求 MTU 520
C->>S: 在 1~0xFFFF 发现属性
C->>S: 向告警属性 handle+1 写入 CCCD 0x0002
loop 每轮先等待 1000 ms
S->>H: 触发测量,等待并读取 7 字节
H-->>S: 状态、温湿度原始值、CRC
S->>S: 校验并组装 11 字节帧
alt 未连接或未配对
S->>S: 仅打印硬件数据,不发送
else 正常温度
S-->>C: 尝试通过 0x5656 发送 Notification
Note over S,C: 当前源码缺少正常属性 CCCD 配置
else 温度 >80.00℃ 或 <-10.00℃
S->>C: 通过 0x5757 发送 Indication
C-->>S: Indication 确认
end
end
验收层次#
层次 |
直接证据 |
不能据此证明 |
|---|---|---|
I2C 初始化 |
|
AHT20 测量已经成功 |
AHT20 可用 |
|
SLE 已连接或已发送 |
SLE 建链 |
两端 |
CCCD 已正确配置 |
服务发现 |
Client |
|
正常接收 |
Client Notification 回调打印 |
告警 Indication 正常 |
告警接收 |
Client 打印 |
Server 收到确认 |
指示确认 |
Server |
应用层已持久化或处理告警 |
必须以接收端回调作为数据到达的证据。Server 的 source=hardware 日志只说明本地采样成功;service discovery done, waiting for sensor data... 又是在 Client 忽略 CCCD 写命令返回值后直接打印的,也不能单独作为接收配置成功的证据。
案例操作指导#
准备硬件并接线#
准备两块 WS53 和一个使用 3.3 V 的 AHT20 兼容模块。传感器只连接到 Server:
AHT20 模块 |
WS53 Server |
|---|---|
VDD/VCC |
3.3 V |
GND |
GND |
SCL |
MIO21 / I2C0_SCL,源码 README 标注排针位置 36 |
SDA |
MIO22 / I2C0_SDA,源码 README 标注排针位置 5 |
不得向只支持 3.3 V 的模块供入 5 V。若模块没有板载 I2C 上拉电阻,应依据模块和开发板硬件设计为 SDA/SCL 配置合适的上拉。
Server 启动还会探测 0x76 和 0x77 的 BMP280,但 BMP280 不是温湿度上报的前置条件。没有 BMP280 时会打印两次探测失败或未发现信息,不应据此判定 AHT20 失败。
先处理源码阻塞项#
完整双板实验前至少应完成以下修正,并重新检查最终代码:
重新选择合法的
conn_interval_*、conn_max_latency和conn_supervision_timeout,满足当前 WS53 API 的范围与监管超时约束;同时检查并向上返回sle_set_announce_param()、sle_set_announce_data()的实际结果。为常规数据属性配置客户端配置描述符,让 Client 发现真实 CCCD handle 并写入
0x0001;告警属性写入0x0002。不要用用户描述符值代替 CCCD。Client 应按服务 UUID、属性 UUID 和描述符类型保存 handle,而不是只按操作位和
property_handle + 1推算。
本文不直接选择具体源码改法。修正后应通过日志或回调确认每个配置 API 成功,再进行业务验收。
配置、构建并烧录 Server#
在 SDK 根目录执行:
fbb config set CONFIG_SAMPLE_SUPPORT_SLE_SENSOR_REPORT_SERVER_SAMPLE=y --target ws53_liteos_app
fbb build ws53_liteos_app --clean
fbb flash ws53_liteos_app --port <SERVER_COM> --json-summary
对应的 Kconfig 选择链为:
CONFIG_ENABLE_BT_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_SLE_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_SLE_SENSOR_REPORT_SERVER_SAMPLE=y
CONFIG_SUPPORT_SLE_PERIPHERAL=y
配置、构建并烧录 Client#
Server 烧录完成后,切换到 Client 角色并重新构建:
fbb config set CONFIG_SAMPLE_SUPPORT_SLE_SENSOR_REPORT_CLIENT_SAMPLE=y --target ws53_liteos_app
fbb build ws53_liteos_app --clean
fbb flash ws53_liteos_app --port <CLIENT_COM> --json-summary
对应的 Kconfig 选择链为:
CONFIG_ENABLE_BT_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_SLE_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_SLE_SENSOR_REPORT_CLIENT_SAMPLE=y
CONFIG_SUPPORT_SLE_CENTRAL=y
Server 与 Client 位于同一个 SLE 案例 choice 中,需要分别构建和烧录。固件包位于:
output/ws53/fwpkg/pack_all_core/ws53_liteos_app/ws53_liteos_app_all_in_one.fwpkg
运行与分层验收#
打开两块板的调试串口,先启动接有传感器的 Server。
检查 I2C 和 AHT20 日志;即使 Client 尚未启动,Server 也应继续采样。
再启动 Client。Client 初始化会先等待 5000 ms,然后扫描
sensor_server。检查两端是否完成连接和配对,Client 是否完成 MTU 交换和属性发现。
源码阻塞项修正后,检查 Client 是否持续收到
type=0x01的 Notification。使用受控测试固件调整告警阈值,或在传感器安全工作范围内改变环境温度,验证
type=0x02的 Indication 和 Server 确认回调。
Server 硬件侧日志可能包括:
[sensor hw] i2c ready: bus=0, scl=GPIO21, sda=GPIO22, rate=100000
[sensor hw] bmp280 detected: addr=0x77, id=0x58 (pressure disabled)
[sensor hw] aht20 compatible device ready
[sensor server] source=hardware temp=32.10C hum=54% light=N/A
没有 BMP280 时,对应日志可能是:
[sensor hw] bmp280 not detected at 0x76/0x77 (pressure disabled)
正常数据真正到达 Client 后,Notification 回调输出形式为:
[sensor client] [T=12345ms] temp=32.10C, hum=54%, light=N/A, type=0x01
告警链路的三层证据为:
[sensor server] ** ALARM ** temp=80.01C, using IND Indicate
[sensor client] ** ALARM ** temp=80.01C exceeds threshold! type=0x02
[sensor server] indicate cfm cbk, conn_id: ..., result: ..., status: 0x0
具体温度、连接 ID 和确认结果以实际运行值为准。不要为了触发告警而对传感器进行可能损坏器件或造成人身风险的极端加热、冷却。
常见问题#
现象 |
检查项 |
|---|---|
Server 没有 |
检查 MIO21/MIO22 PinMux、供电、I2C0 是否被其他模块占用 |
有 I2C 日志但没有 |
检查地址 |
每隔若干轮打印 |
源码只打印首次和每 10 次连续失败;根据 |
BMP280 探测失败 |
只影响气压器件识别,不影响地址 |
Client 一直扫描 |
确认 Server 广播已成功启动、名称为 |
已连接但不做服务发现 |
检查旧配对删除和配对回调;当前 MTU 交换只由配对成功回调触发 |
服务发现完成但没有正常数据 |
首先修正常规属性 CCCD,并确认 Client 成功写入 |
告警属性没有启用 |
检查选中的属性是否确为 UUID |
Server 有发送失败日志 |
检查连接门控、CCCD、在途 Indication 和协议栈返回码;当前源码不会自动重试 |
周期不是精确 1 秒 |
当前是 1000 ms 固定休眠加同步测量时间,不是周期定时器 |
低湿度不告警 |
|
关键配置#
传感器与任务参数#
参数 |
WS53 当前值 |
说明 |
|---|---|---|
|
1000 ms |
每轮处理前的休眠时间 |
Server 任务优先级 |
28 |
|
Server 任务栈 |
|
Client 任务也使用同样大小 |
I2C 控制器 |
I2C0 |
|
I2C 速率 |
100000 bit/s |
高速码参数为 0 |
SCL/SDA |
MIO21/MIO22 |
两者 Pin Mode 均为 3 |
AHT20 地址 |
|
7 字节测量响应 |
测量等待 |
80 ms |
忙时最多再检查 3 次,每次间隔 10 ms |
温度有效范围 |
-40.00~85.00 ℃ |
超范围则本轮失败 |
高/低告警阈值 |
80.00/-10.00 ℃ |
只在严格越界时告警 |
|
2 |
温度和湿度;光照未实现 |
服务与扫描参数#
参数 |
WS53 当前值 |
说明 |
|---|---|---|
Server 应用 UUID |
|
注册 SSAP Server |
Service UUID |
|
传感器服务 |
正常数据 UUID |
|
READ、NOTIFY |
告警数据 UUID |
|
READ、INDICATE |
MTU 请求 |
520 |
两端都使用版本 1 |
Client 启动等待 |
5000 ms |
等待后才调用 |
扫描 PHY |
|
主动扫描 |
扫描间隔/窗口 |
100/100 |
API 单位 0.125 ms,即均为 12.5 ms |
重复过滤 |
关闭 |
|
广播连接参数的合法性#
参数 |
原始值 |
按当前 API 的含义 |
|---|---|---|
广播间隔 |
|
200 × 0.125 ms = 25 ms |
首选连接间隔 |
|
100 × 0.25 ms = 25 ms |
最大时延 |
|
499 个连接事件,不是 4990 ms |
监管超时 |
|
500 × 10 ms = 5 s |
源码把 0x64 注释为 12.5 ms,把最大时延注释为 4990 ms;这两处注释与当前 WS53 API 的连接参数定义不一致。监管超时应满足:
supervision_timeout × 20 > (max_latency + 1) × interval_max
代入当前值:
500 × 20 = 10000
(499 + 1) × 100 = 50000
左侧没有严格大于右侧,因此参数组合不合法。修正时可以降低 max_latency、提高合法范围内的监管超时,或重新设计整组连接参数;不能只改注释。
代码详解#
1. 代码目录与调用关系#
sle_sensor_report/
├── sle_sensor_report.c
├── Kconfig
├── sle_sensor_report_server/src/
│ ├── sensor_aht20.c
│ ├── sensor_aht20.h
│ ├── sle_sensor_report_server.c
│ ├── sle_sensor_report_server.h
│ └── sle_sensor_report_server_adv.c
└── sle_sensor_report_client/src/
└── sle_sensor_report_client.c
Server 任务的主调用链为:
sle_sensor_report_entry()
-> sle_sensor_report_server_task()
-> sle_sensor_report_server_init()
-> sensor_aht20_init()
-> enable_sle()
-> 注册广播、连接和 SSAPS 回调
-> 注册服务和两个属性
-> sle_sensor_report_server_adv_init()
-> osal_msleep(1000)
-> sle_sensor_report_server_process()
-> sensor_aht20_read()
-> 组帧并选择属性
-> ssaps_notify_indicate()
2. 传感器故障会自动重试并节流日志#
任一读取阶段失败都会执行:
g_sensor_ready = false;
g_failure_pending = true;
g_consecutive_failures++;
下一轮 sensor_aht20_read() 会重新进入 sensor_aht20_init()。失败日志只在第 1 次和每累计 10 次连续失败时输出;恢复后的首次成功读取会打印 sensor recovered 并清零计数。
BMP280 探测只执行一次。它会在 I2C 初始化后额外等待 500 ms,检查 0x76 和 0x77 的 0xD0 寄存器是否等于 0x58,但不执行复位、校准、补偿或压力上报。
3. Server 在发送前做二次连接快照检查#
处理函数先检查连接和上报门控,再保存连接句柄快照。帧复制完成后会再次检查:
if (!g_connected || !g_reporting_enabled ||
(g_sle_conn_hdl != conn_handle)) {
return;
}
这可以降低采样、组帧期间发生断链后仍使用旧连接句柄的风险。随后 ssaps_notify_indicate() 的直接返回值会被检查并打印,但源码没有排队重试。
4. Client 的发现范围和 CCCD 推算#
MTU 交换成功后,Client 在完整 handle 范围发现 Property:
find_param.type = SSAP_FIND_TYPE_PROPERTY;
find_param.start_hdl = 1;
find_param.end_hdl = 0xFFFF;
属性回调只判断 SSAP_OPERATE_INDICATION_BIT_INDICATE,不检查服务 UUID 或属性 UUID。发现完成后又直接使用:
wparam.handle = g_alarm_property_handle + 1;
wparam.type = SSAP_DESCRIPTOR_CLIENT_CONFIGURATION;
wparam.data = cccd_val; /* {0x02, 0x00} */
(void)ssapc_write_cmd(0, g_conn_id, &wparam);
这段代码依赖“告警 CCCD 紧跟属性”的注册顺序,并隐藏写命令的直接返回值。更稳健的实现应发现并校验服务、属性和描述符 UUID/类型,再保存真实 handle。
5. Client 只严格检查帧长度#
Notification 和 Indication 回调都会拒绝空指针和非 11 字节数据,这避免了按错误长度读取结构体。但回调没有检查:
status是否成功;sensor_count是否为 2;Notification 是否携带
frame_type == 0x01;Indication 是否携带
frame_type == 0x02;时间戳、温湿度是否在业务允许范围;
是否存在重复、丢失或倒序帧。
因此“长度为 11 字节”只是内存边界检查,不是完整的业务协议校验。