说明¶

概述¶

在线传感模块提供连续的传感器数据采集和传输功能。它支持可配置的采样频率和多个输出通道（MQTT、串口，以及可选的LCD），实现传感器数据的实时监控。

功能特性¶

✅ 可配置采样频率（默认：20 Hz，范围：0.1 - 10000 Hz）
✅ MQTT传输（开启/关闭）
✅ 串口输出（开启/关闭）
✅ 可选LCD显示（当定义 TINY_MEASUREMENT_ENABLE_LCD 时）
✅ 使用ESP定时器进行固定频率数据采集
✅ 自动数据格式化
✅ 线程安全操作
✅ 运行时配置更新

架构¶

基于定时器的采样¶

模块使用ESP定时器进行精确的周期性采样：

定时器创建：创建周期定时器，周期 = 1 / 采样频率
定时器回调：在每个定时器滴答时执行，读取传感器数据
数据输出：格式化数据并输出到配置的通道（MQTT、串口、LCD）

数据流¶

ESP定时器 → 定时器回调 → 传感器读取 → 数据格式化 → 输出通道
                                                          ├─ MQTT
                                                          ├─ 串口
                                                          └─ LCD（可选）

配置¶

默认配置¶

默认值在 tiny_measurement_config.h 中定义：

#define TINY_MEASUREMENT_ONLINE_SENSING_DEFAULT_FREQ_HZ 20.0f
#define TINY_MEASUREMENT_ONLINE_SENSING_DEFAULT_ENABLE_MQTT true
#define TINY_MEASUREMENT_ONLINE_SENSING_DEFAULT_ENABLE_SERIAL true

配置结构¶

typedef struct
{
    float sampling_frequency_hz;  // 采样频率（Hz）
    bool enable_mqtt;              // 启用MQTT传输
    bool enable_serial;            // 启用串口输出
    bool enable_lcd;               // 启用LCD显示（可选）
    const char *mqtt_topic;        // MQTT主题（NULL使用默认）
} online_sensing_config_t;

数据格式¶

MQTT格式¶

紧凑格式，6位小数精度，支持完整的20位精度：

x,y,z,temp

示例：

0.012345,-0.045678,0.987654,25.50

串口格式¶

与MQTT格式相同，带换行符：

x,y,z,temp\n

LCD格式¶

每行一个轴： - 第1行：X:0.012345 - 第2行：Y:-0.045678 - 第3行：Z:0.987654 - 第4行：T:25.50C

使用流程¶

初始化传感器：初始化ADXL355传感器
设置传感器句柄：调用 online_sensing_set_sensor_handle()
初始化模块：调用 online_sensing_init() 并传入配置（或NULL使用默认值）
启动传感：调用 online_sensing_start()
运行时更新：可选地更新频率或启用/禁用通道
停止传感：完成后调用 online_sensing_stop()
反初始化：调用 online_sensing_deinit() 清理资源

性能考虑¶

采样频率限制¶

最小值：0.1 Hz（10秒周期）
最大值：10000 Hz（100微秒周期）
推荐值：大多数应用使用 1 - 1000 Hz

资源使用¶

CPU：定时器回调以采样频率执行
内存：回调中最小栈使用
网络：MQTT带宽取决于频率和负载大小
串口：高频率可能导致串口缓冲区溢出

优化建议¶

禁用串口输出：对于高频率（>100 Hz），禁用串口输出
MQTT QoS：对高频数据使用QoS 0（默认）
LCD更新：LCD更新相对较慢，仅用于低频率（<10 Hz）

错误处理¶

常见错误¶

ESP_ERR_INVALID_ARG：无效频率（超出范围）
ESP_ERR_INVALID_STATE：已在运行或未初始化
ESP_FAIL：定时器创建或启动失败

错误恢复¶

在启动前检查传感器句柄是否已设置
在初始化前验证频率范围
使用新配置重启前先停止

线程安全¶

定时器回调在定时器上下文中执行（高优先级）
配置更改需要停止并重新启动
状态检查防止并发操作

集成注意事项¶

MQTT集成¶

需要MQTT客户端已连接
发布前检查 s_is_mqtt_connected
如果 mqtt_topic 为NULL，使用默认主题

传感器集成¶

需要ADXL355传感器句柄
必须在设置句柄前初始化
传感器读取操作是非阻塞的

LCD集成¶

仅在定义 TINY_MEASUREMENT_ENABLE_LCD 时可用
启动时清除LCD屏幕
更新是同步的（高频率时可能影响时序）