ESP IoT Solution 温湿度传感器驱动详解已适配型号、硬件抽象层与 Sensor Hub 集成【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution温湿度传感器是环境感知类应用的基础器件可用于智慧人居、智慧农场、智能工厂等场景下的环境温湿度检测。本文基于 ESP IoT Solution 仓库中 docs/zh_CN/sensors/humiture.rst 文档结合仓库内 components/sensors/humiture 目录下的驱动源码系统梳理已适配的温湿度传感器型号、硬件抽象层humiture HAL接口定义以及如何通过 Sensor Hub 实现更简单的传感器应用开发帮助开发者快速完成环境温湿度采集方案的选型与落地。温湿度传感器适配总览温湿度传感器包括温度传感器、湿度传感器以及兼具两种功能的传感器。在本仓库中所有温湿度传感器驱动均基于 I2C 总线实现统一挂在 i2c_bus 组件之上。目前仓库已适配以下四款温湿度传感器名称功能总线供应商硬件抽象层HDC2010温度、湿度I2CTI—HTS221温度、湿度I2CST√SHT3X温度、湿度I2CSensirion√MVH3004D温度、湿度I2C——从适配表可以看到四款传感器均通过 I2C 接口通信其中 HTS221 与 SHT3X 已完成对硬件抽象层的实现表格中标记 √可以直接通过统一的humiture_hal接口或 Sensor Hub 调用HDC2010 与 MVH3004D 则提供了独立驱动组件可直接调用其原生 API 使用。硬件抽象层Humiture HAL设计在 components/sensors/sensor_hub/include/hal/humiture_hal.h 中定义了温湿度传感器的统一抽象接口核心是humiture_impl_t结构体。该结构体以函数指针的形式封装了驱动开发者需要实现的所有操作typedef struct { esp_err_t (*init)(bus_handle_t handle, uint8_t addr); // 初始化传感器 esp_err_t (*deinit)(void); // 反初始化 esp_err_t (*test)(void); // 自检 esp_err_t (*acquire_humidity)(float *humidity); // 采集相对湿度单位% esp_err_t (*acquire_temperature)(float *temperature); // 采集温度单位摄氏度 esp_err_t (*sleep)(void); // 进入睡眠 esp_err_t (*wakeup)(void); // 唤醒 esp_err_t (*set_mode)(sensor_mode_t work_mode); // 设置工作模式 esp_err_t (*set_range)(sensor_range_t range); // 设置量程 } humiture_impl_t;其中sensor_mode_t、sensor_range_t、sensor_command_t等类型定义在 components/sensors/sensor_hub/include/sensor_type.h工作模式sensor_mode_tMODE_DEFAULT默认、MODE_POLLING按间隔轮询采集、MODE_INTERRUPT中断触发采集量程sensor_range_tRANGE_DEFAULT、RANGE_MIN、RANGE_MEDIUM、RANGE_MAX控制命令sensor_command_tCOMMAND_SET_MODE、COMMAND_SET_RANGE、COMMAND_SET_ODR、COMMAND_SET_POWER、COMMAND_SELF_TEST电源模式sensor_power_mode_tPOWER_MODE_WAKEUP、POWER_MODE_SLEEP。HAL 层的接口实现位于 components/sensors/sensor_hub/hal/humiture_hal.c对外提供如下 APIAPI功能返回说明humiture_create(bus, sensor_name, addr)创建温湿度传感器实例成功返回句柄失败返回 NULLhumiture_delete(sensor)删除并释放传感器资源ESP_OK/ESP_FAILhumiture_test(sensor)检测传感器是否在线ESP_OK/ESP_FAIL/ESP_ERR_NOT_SUPPORTEDhumiture_acquire_humidity(sensor, humidity)单次采集相对湿度单位百分比humiture_acquire_temperature(sensor, temperature)单次采集温度单位摄氏度humiture_sleep(sensor)进入睡眠模式驱动不支持时返回ESP_ERR_NOT_SUPPORTEDhumiture_wakeup(sensor)唤醒传感器同上humiture_acquire(sensor, data_group)一次性采集一组数据填充sensor_data_group_thumiture_control(sensor, cmd, args)控制命令通道统一分发至模式/量程/电源/自检从 humiture_hal.c 的实现看humiture_create会遍历链接器脚本生成的传感器驱动段__sensor_hub_detect_fn_array_start至__sensor_hub_detect_fn_array_end按sensor_name字符串匹配驱动并调用其init完成底层初始化humiture_acquire则依次调用acquire_temperature与acquire_humidity成功采集的数据分别挂上SENSOR_TEMP_DATA_READY与SENSOR_HUMI_DATA_READY事件 ID 后填充进sensor_data_group_t。humiture_control内部通过switch将COMMAND_SET_MODE、COMMAND_SET_RANGE、COMMAND_SET_POWER、COMMAND_SELF_TEST等命令分发给对应的实现函数对COMMAND_SET_ODR当前返回ESP_ERR_NOT_SUPPORTED。结合 Sensor Hub 实现更简单的调用原文档指出用户既可以直接调用上述 HAL 层 API 编写应用程序也可以使用 Sensor Hub 中的传感器接口实现更简单的调用。Sensor Hub 是一个传感器管理组件实现了对传感器设备的硬件抽象、设备管理和数据分发用户只需关注传感器的工作方式、采集间隔、量程等配置再向关心的事件注册回调即可。驱动开发者侧注册温湿度驱动以 SHT3X 为例驱动开发者需将操作函数填入humiture_impl_t并通过SENSOR_HUB_DETECT_FN注册宏挂载到 Sensor Hub。该注册代码位于 components/sensors/humiture/sht3x/sht3x.cstatic humiture_impl_t sht3x_impl { .init humiture_sht3x_init, .deinit humiture_sht3x_deinit, .test humiture_sht3x_test, .acquire_humidity humiture_sht3x_acquire_humidity, .acquire_temperature humiture_sht3x_acquire_temperature, }; SENSOR_HUB_DETECT_FN(HUMITURE_ID, sht3x, sht3x_impl);HUMITURE_ID即传感器类型枚举sensor_type_t中定义的温湿度类型sensor_type.h。同时需要在组件的CMakeLists.txt中添加接口依赖target_link_libraries(${COMPONENT_LIB} INTERFACE -u humiture_sht3x_init)应用开发者侧创建实例与事件回调应用开发者按以下步骤使用 Sensor Hub在工程的idf_component.yml中添加sensor_hub与所需传感器组件使用iot_sensor_create创建传感器实例配置项中bus指定总线句柄、addr指定 I2C 地址、type指定类型、mode指定工作模式、min_delay指定采集间隔其余为非必须项sensor_config_t sht3x_config { .bus i2c0_bus_handle, .addr 0x44, .mode MODE_POLLING, .min_delay SENSOR_PERIOD, }; iot_sensor_create(sht3x, sht3x_config, sht3x_handle);注册事件回调可通过iot_sensor_handler_register按传感器句柄或iot_sensor_handler_register_with_type按传感器类型注册启动传感器iot_sensor_start启动后发出SENSOR_STARTED事件之后按设定周期持续采集并发送SENSOR_XXXX_DATA_READY事件回调函数通过event_data获取具体数据停止/删除iot_sensor_stop临时关闭采集iot_sensor_delete释放资源支持电源管理的驱动在停止时会进入睡眠模式。仓库为此提供了两个可直接运行的示例sensors/sensor_control_led温湿度传感器控制 LED 开关与 sensors/sensor_hub_monitor传感器监测。Sensor Hub 的测试代码位于 components/sensors/sensor_hub/test_apps/main/sensor_hub_test.c其中通过虚拟温湿度传感器virtual_humiture_sensor.c验证了驱动的加载与事件分发链路。SHT3X 驱动深入测量模式与数据转换SHT3X 是 Sensirion 的下一代温湿度传感器基于 CMOSens 芯片支持两个可选 I2C 地址0x44与0x45以及最高 1 MHz 的通信速率。驱动源码位于 components/sensors/humiture/sht3x/sht3x.c头文件 sht3x.h 中定义了全部测量命令。单次测量与周期测量SHT3X 支持两种测量模式单次测量模式Single Shot每发送一条测量命令触发一次数据采集得到一组温湿度数据对周期测量模式Periodic一条命令启动后持续输出数据流使用前需先发送0xE000读取周期数据结束周期模式需发送0x3093SHT3x_STOP_PERIODIC。两种模式均提供高/中/低三档可重复性repeatability配置对应不同的测量精度与转换时间。驱动在humiture_sht3x_init中默认将传感器配置为SHT3x_PER_4_MEDIUM即周期模式下中等可重复性、4 mps每秒 4 次测量约 250 ms 间隔——从源码可见该默认值在sht3x_measure_period中被映射为 250 ms 的最小采集间隔。CRC 校验与物理量换算SHT3X 的原始测量数据通过 I2C 返回 6 字节温度与湿度各 2 字节数据 1 字节 CRC8 校验。驱动中的CheckCrc8使用多项式0x31逐字节校验sht3x.c校验失败返回ESP_FAIL。物理量换算公式在 sht3x.c 中温度℃T -45 175 * ST / (2^16 - 1) 湿度%RHRH 100 * SRH / (2^16 - 1)其中ST、SRH为 16 位原始测量值。换算结果还会做量程校验温度须处于 -20 ℃ 至 125 ℃、湿度须处于 0% 至 100% 之间才返回ESP_OK否则视为采集异常。sht3x_get_single_shot还内置了最小采集间隔保护两次单次采集间隔不足时直接返回上次缓存数据避免高频无效访问总线。其他控制命令驱动还封装了软复位sht3x_soft_reset命令0x30A2、停止周期模式0x3093、加速响应时间 ART0x2B32、设置测量模式sht3x_set_measure_mode以及加热器开关sht3x_heater默认关闭等接口均在 sht3x.h 中声明。硬件接线方面SHT3X 的 SDA 接 GPIO1、SCL 接 GPIO2示例默认引脚可按工程实际修改SDA 与数据信号相连、SCL 与时钟信号相连。HTS221 驱动深入寄存器配置与校准HTS221 是 ST 推出的电容式数字温湿度传感器I2C 地址为0x5FWHO_AM_I 寄存器0x0F默认值为0xBC可用于设备识别。驱动头文件 hts221.h 完整定义了寄存器映射与配置枚举平均采样数湿度平均HTS221_AVGH_4~HTS221_AVGH_5124~512 个样本温度平均HTS221_AVGT_2~HTS221_AVGT_2562~256 个样本通过AV_CONF寄存器0x10配置输出数据率 ODRHTS221_ODR_ONE_SHOT单次、1 Hz、7 Hz、12.5 Hz通过CTRL_REG10x20配置电源控制CTRL_REG1的 PD 位控制上电/掉电对应hts221_set_activate与hts221_set_powerdown数据更新保护BDUhts221_set_bdumode开启后输出寄存器在 MSB/LSB 未读完整前不会更新中断引脚 DRDYCTRL_REG30x22配置中断使能、推挽/开漏输出与有效电平内部加热器hts221_set_heaterstate控制用于高湿凝结场景下驱除传感器表面水汽单次触发hts221_start_oneshot置位CTRL_REG2的 ONE_SHOT 位启动一次转换。与 SHT3X 直接给出物理量不同HTS221 的温湿度输出需结合片内校准系数0x30~0x3F校准寄存器进行线性换算hts221_get_humidity与hts221_get_temperature返回的数值需分别除以 10 才得到百分比湿度和摄氏度温度而hts221_get_raw_humidity/hts221_get_raw_temperature直接返回原始 ADC 值。HTS221 同样实现了humiture_hts221_init、humiture_hts221_acquire_humidity、humiture_hts221_sleep等 HAL 接口见 hts221.h可通过 Sensor Hub 统一管理。独立驱动组件HDC2010 与 MVH3004D除上述两款已接入 HAL 的传感器外仓库还提供 HDC2010 与 MVH3004D 的独立驱动HDC2010TI 出品的低功耗温湿度传感器I2C 接口组件内提供hdc2010_create等原生 API并附带 test_apps 测试MVH3004DI2C 接口温湿度传感器组件内提供mvh3004d_create等原生 API 与测试工程。这两款驱动可直接调用组件原生 API 使用若需要接入 Sensor Hub 统一管理可参照 SHT3X/HTS221 的humiture_impl_t实现方式自行补全适配表格中硬件抽象层一栏为空即表示当前未完成 HAL 实现。各组件均位于 components/sensors/humiture 目录可通过组件管理器添加依赖例如idf.py add-dependency espressif/sht3x*组件在 CMake 阶段会自动下载。小结在 ESP IoT Solution 中温湿度传感器的使用形成了清晰的三层结构底层是各传感器的独立驱动组件components/sensors/humiture中间是统一的温湿度硬件抽象层humiture_halhumiture_hal.c最上层是可选的 Sensor Hub 事件驱动框架docs/zh_CN/sensors/sensor_hub.rst。开发者按需选择追求轻量直接调用驱动原生 API追求统一管理则接入 Sensor Hub 按创建实例 → 注册回调 → 启动 → 收事件四步完成采集。无论是 SHT3X 的周期/单次测量与 CRC 校验还是 HTS221 的寄存器级配置与线性校准仓库源码都给出了完整可运行的参考实现可作为智慧人居、智慧农场、智能工厂等环境监测方案的直接基础。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考