企业官网建设流程全解析

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 组件之上。目前仓库已适配以下四款温湿度传感器：

从适配表可以看到，四款传感器均通过 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_t：MODE_DEFAULT（默认）、MODE_POLLING（按间隔轮询采集）、MODE_INTERRUPT（中断触发采集）；
• 量程sensor_range_t：RANGE_DEFAULT、RANGE_MIN、RANGE_MEDIUM、RANGE_MAX；
• 控制命令sensor_command_t：COMMAND_SET_MODE、COMMAND_SET_RANGE、COMMAND_SET_ODR、COMMAND_SET_POWER、COMMAND_SELF_TEST；
• 电源模式sensor_power_mode_t：POWER_MODE_WAKEUP、POWER_MODE_SLEEP。

HAL 层的接口实现位于 components/sensors/sensor_hub/hal/humiture_hal.c，对外提供如下 API：

从 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.c：

static 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：

1. 在工程的idf_component.yml中添加sensor_hub与所需传感器组件；
2. 使用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);

3. 注册事件回调：可通过iot_sensor_handler_register（按传感器句柄）或iot_sensor_handler_register_with_type（按传感器类型）注册；
4. 启动传感器：iot_sensor_start启动后发出SENSOR_STARTED事件，之后按设定周期持续采集并发送SENSOR_XXXX_DATA_READY事件，回调函数通过event_data获取具体数据；
5. 停止/删除：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读取周期数据，结束周期模式需发送0x3093（SHT3x_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) 湿度（%RH）：RH = 100 * SRH / (2^16 - 1)

其中ST、SRH为 16 位原始测量值。换算结果还会做量程校验：温度须处于 -20 ℃ 至 125 ℃、湿度须处于 0% 至 100% 之间才返回ESP_OK，否则视为采集异常。sht3x_get_single_shot还内置了最小采集间隔保护，两次单次采集间隔不足时直接返回上次缓存数据，避免高频无效访问总线。

其他控制命令

驱动还封装了软复位（sht3x_soft_reset，命令0x30A2）、停止周期模式（0x3093）、加速响应时间 ART（0x2B32）、设置测量模式（sht3x_set_measure_mode）以及加热器开关（sht3x_heater，默认关闭）等接口，均在 sht3x.h 中声明。硬件接线方面，SHT3X 的 SDA 接 GPIO1、SCL 接 GPIO2（示例默认引脚，可按工程实际修改），SDA 与数据信号相连、SCL 与时钟信号相连。

HTS221 驱动深入：寄存器配置与校准

HTS221 是 ST 推出的电容式数字温湿度传感器，I2C 地址为0x5F，WHO_AM_I 寄存器（0x0F）默认值为0xBC，可用于设备识别。驱动头文件 hts221.h 完整定义了寄存器映射与配置枚举：

• 平均采样数：湿度平均HTS221_AVGH_4~HTS221_AVGH_512（4~512 个样本），温度平均HTS221_AVGT_2~HTS221_AVGT_256（2~256 个样本），通过AV_CONF寄存器（0x10）配置；
• 输出数据率 ODR：HTS221_ODR_ONE_SHOT（单次）、1 Hz、7 Hz、12.5 Hz，通过CTRL_REG1（0x20）配置；
• 电源控制：CTRL_REG1的 PD 位控制上电/掉电，对应hts221_set_activate与hts221_set_powerdown；
• 数据更新保护（BDU）：hts221_set_bdumode开启后，输出寄存器在 MSB/LSB 未读完整前不会更新；
• 中断引脚 DRDY：CTRL_REG3（0x22）配置中断使能、推挽/开漏输出与有效电平；
• 内部加热器：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 的独立驱动：

• HDC2010：TI 出品的低功耗温湿度传感器，I2C 接口，组件内提供hdc2010_create等原生 API，并附带 test_apps 测试；
• MVH3004D：I2C 接口温湿度传感器，组件内提供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_hal（humiture_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