esp-iot-solution 中 AHT20 温湿度传感器 I2C 驱动组件使用指南【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution导读本文围绕 esp-iot-solution 仓库中的 AHT20 驱动组件 展开系统讲解如何在乐鑫 ESP-IDF 工程中通过 I2C 总线接入 ASAIR AHT20 温湿度传感器从总线初始化、设备地址选择到温湿度数据读取与资源回收的完整流程。读完本文你将掌握该组件的全部公开 API 用法理解其底层测量命令、状态位校验、CRC 校验与 20bit 原始数据解析原理并能在自己的项目中直接复用这套驱动。组件概览AHT20 与兼容型号aht20是 esp-iot-solution 中一款基于 I2C 接口的温湿度传感器驱动组件位于 components/sensors/humiture/aht20核心功能由 aht20.c 实现对外接口定义在 include/aht20.h。根据组件 README 与 CHANGELOG.md 的说明组件不仅支持 AHT20还兼容 AHT30v1.0.0 起在说明中补充了 AHT30 描述以及 AHT21官方标注 AHT21 已 deprecated不推荐在新设计中选用芯片关键参数在 priv_include/aht20_reg.h 中定义型号名为ASAIR AHT20供电电压范围 2.2V ~ 5.5V工作温度范围 -40℃ ~ 125℃组件版本为 v2.0.02025-08-08 发布该版本引入了对i2c_bus通用总线组件的支持将底层 I2C 通信完全委托给 espressif/i2c_bus 组件依赖版本^1.4.0。组件的依赖信息见 idf_component.yml要求IDF 版本 4.3并依赖cmake_utilities与espressif/i2c_buspublic: true即使用方可以直接访问其头文件。I2C 总线初始化AHT20 驱动本身不管理 I2C 总线而是复用 esp-iot-solution 的i2c_bus组件。因此使用前必须先在应用侧创建总线句柄这一步骤与 AHT20 的驱动代码无关属于标准前置操作。#define I2C_MASTER_SCL_IO CONFIG_I2C_MASTER_SCL /*! GPIO number for I2C master clock */ #define I2C_MASTER_SDA_IO CONFIG_I2C_MASTER_SDA /*! GPIO number for I2C master data */ #define I2C_MASTER_NUM I2C_NUM_0 /*! I2C port number for master dev */ #define I2C_MASTER_FREQ_HZ 100000 /*! I2C master clock frequency */ const i2c_config_t i2c_bus_conf { .mode I2C_MODE_MASTER, .sda_io_num I2C_MASTER_SDA_IO, .sda_pullup_en GPIO_PULLUP_ENABLE, .scl_io_num I2C_MASTER_SCL_IO, .scl_pullup_en GPIO_PULLUP_ENABLE, .master.clk_speed I2C_MASTER_FREQ_HZ }; i2c_bus_handle_t i2c_bus i2c_bus_create(I2C_MASTER_NUM, i2c_bus_conf);要点说明I2C_MASTER_SCL_IO/I2C_MASTER_SDA_IO在测试工程中由 Kconfig 配置项提供默认 SCL40、SDA41见 test_apps/main/Kconfig.projbuild实际项目中可根据硬件接线替换为具体 GPIO 编号总线时钟频率I2C_MASTER_FREQ_HZ设为 100000100 kHz 标准模式符合 AHT20 数据手册对标准 I2C 速率的要求内部上下拉GPIO_PULLUP_ENABLE建议保持开启因为传感器模块通常不带强上拉i2c_bus_create返回的总线句柄需判空检查失败时返回NULL。该接口的完整定义可参考 components/i2c_bus/include/i2c_bus.h。创建 AHT20 设备句柄总线就绪后通过aht20_new_sensor在指定总线上创建 AHT20 设备句柄。设备配置结构体aht20_i2c_config_t定义于 include/aht20.haht20_i2c_config_t i2c_conf { .bus_inst i2c_bus, // I2C bus instance .i2c_addr AHT20_ADDRRES_0, // Device address }; aht20_dev_handle_t handle; aht20_new_sensor(i2c_conf, handle);设备地址如何确定AHT20 的 I2C 7 位地址由芯片的CEA0引脚决定定义在 include/aht20.h宏定义地址值CE 引脚电平AHT20_ADDRRES_00x38CE 拉低AHT20_ADDRESS_10x39CE 拉高从源码看aht20_new_sensor的实现aht20.c本质上是调用i2c_bus_device_create(bus_inst, i2c_addr, 0)在总线上挂载一个地址为 0x38/0x39 的子设备第三个参数 0 表示不覆盖总线时钟频率沿用总线默认时钟。创建成功时句柄非空若失败函数打印i2c_bus_device_create failed并返回ESP_FAIL。同时该函数会打印芯片型号与版本号、供电电压范围、工作温度范围等日志便于上电确认器件身份。aht20_dev_handle_t为void *类型对调用方透明内部实际是i2c_bus_device_handle_t。读取温湿度数据创建句柄后即可周期性调用aht20_read_temperature_humidity获取实时数据。该 API 同时输出原始值raw与换算后的物理量见 include/aht20.huint32_t temperature_raw, humidity_raw; float temperature, humidity; aht20_read_temperature_humidity(handle, temperature_raw, temperature, humidity_raw, humidity); ESP_LOGI(TAG, %-20s: %2.2f %%, humidity is, humidity); ESP_LOGI(TAG, %-20s: %2.2f degC, temperature is, temperature);参数说明temperature_raw/humidity_raw传感器返回的 20bit 原始 ADC 数据可用于自行换算或调试比对temperature/humidity驱动换算后的物理量湿度单位为 %RH温度单位为摄氏度返回值ESP_OK表示读取成功ESP_ERR_INVALID_ARG表示句柄非法ESP_ERR_NOT_FINISHED表示数据未就绪I2C 通信失败或 CRC 校验失败也会返回对应错误码。源码级原理一次温湿度读取的完整链路深入 aht20.c 的实现可以看到一次读取包含四个关键步骤1. 发送测量触发命令。驱动向命令寄存器写入AHT20_START_MEASURMENT_CMD0xAC定义于 aht20_reg.h并携带两个参数字节0x33, 0x00要求传感器进行一次温湿度测量。命令写完后驱动主动vTaskDelay(pdMS_TO_TICKS(100))等待 100ms——这是数据手册规定的测量时间余量属于阻塞等待实际应用中如需非阻塞流程可自行调度。2. 读取状态字节并检查标志位。驱动先读 1 字节状态依据 aht20_reg.h 定义的位含义进行三重校验BIT(AT581X_STATUS_Calibration_Enable)bit3校准已启用1才算数据有效BIT(AT581X_STATUS_CRC_FLAG)bit4CRC 标志位为 1 表示校验通过BIT(AT581X_STATUS_BUSY_INDICATION)bit7忙标志必须为 0即设备空闲。三者同时满足才进入数据读取否则打印data is not ready并返回ESP_ERR_NOT_FINISHED。3. 读取 7 字节数据并做 CRC 校验。数据帧为 6 字节有效数据 1 字节 CRC。驱动用aht20_calc_crc对前 6 字节计算 CRC8多项式 0x31初值 0xFF即 CRC-8/MAXIM并与第 7 字节比对不一致返回crc is error。4. 解析 20bit 原始数据并换算物理量。AHT20 的温湿度各占 20bit在 6 字节数据中交叉存放湿度由字节 1、2、3 拼接成 24bit 后右移 4 位得到 20bit 原始值换算公式humidity raw * 100 / 10485761048576 2^20将 0~2^20 的原始值映射到 0~100 %RH温度由字节 3 低 4 位 字节 4、5 拼接得到 20bit 原始值换算公式temperature raw * 200 / 1048576 - 50将原始值映射到 -50℃ ~ 150℃ 区间实际有效量程以芯片数据手册为准。这套解析逻辑完全对齐 AHT20 数据手册规定的数据格式如果你需要自行移植或二次开发可参照 aht20.c 中的位拼接与换算代码。资源清理传感器使用完毕或进入低功耗休眠前应释放资源与创建过程对称aht20_del_sensor(handle); i2c_bus_delete(i2c_bus);aht20_del_sensor内部调用i2c_bus_device_delete释放设备句柄aht20.c失败时打印i2c_bus_device_delete failed并返回对应错误码i2c_bus_delete释放整条总线资源。注意先删设备、再删总线顺序不可颠倒否则会留下悬垂引用。测试验证与内存泄漏检查仓库为组件提供了完整的单元测试工程位于 test_apps入口为 main/aht20_test.c配套 pytest_aht20.py 可实现自动化测试。测试用例sensor aht20 test完整走了一遍「总线创建 → 传感器创建 → 读取温湿度断言返回ESP_OK→ 删除传感器 → 删除总线」的生命周期同时通过setUp/tearDown对比测试前后的MALLOC_CAP_8BIT与MALLOC_CAP_32BIT堆空闲内存阈值 -400 字节验证驱动在创建/删除过程中不存在内存泄漏。这套测试代码本身就是一份可直接参考的最小可运行示例比 README 中的片段更完整。测试工程的 sdkconfig.defaults 关闭了任务看门狗兼容 IDF 4.4 与 5.0 两种写法并启用 USB Serial/JTAG 控制台便于在开发板上直接运行测试菜单。集成到你的工程在 ESP-IDF 工程中启用该组件有两条途径本地路径引用将 components/sensors/humiture/aht20 目录加入工程的EXTRA_COMPONENT_DIRSesp-iot-solution 仓库本身就是按组件目录组织可直接复用IDF Component Manager通过idf_component.yml声明依赖espressif/aht20组件清单见 idf_component.yml由构建系统自动拉取。无论哪种方式i2c_bus组件espressif/i2c_bus版本^1.4.0都会作为传递依赖自动引入。按照「总线初始化 → 传感器创建 → 周期读取 → 资源清理」四步即可完成一次完整的 AHT20 温湿度采集闭环整个过程不依赖具体板卡仅需根据硬件原理图确认 SCL/SDA 引脚与 CE 引脚的地址电平。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 esp-iot-solution 中 AHT20 温湿度传感器 I2C 驱动组件使用指南
esp-iot-solution 中 AHT20 温湿度传感器 I2C 驱动组件使用指南【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution导读本文围绕 esp-iot-solution 仓库中的 AHT20 驱动组件 展开系统讲解如何在乐鑫 ESP-IDF 工程中通过 I2C 总线接入 ASAIR AHT20 温湿度传感器从总线初始化、设备地址选择到温湿度数据读取与资源回收的完整流程。读完本文你将掌握该组件的全部公开 API 用法理解其底层测量命令、状态位校验、CRC 校验与 20bit 原始数据解析原理并能在自己的项目中直接复用这套驱动。组件概览AHT20 与兼容型号aht20是 esp-iot-solution 中一款基于 I2C 接口的温湿度传感器驱动组件位于 components/sensors/humiture/aht20核心功能由 aht20.c 实现对外接口定义在 include/aht20.h。根据组件 README 与 CHANGELOG.md 的说明组件不仅支持 AHT20还兼容 AHT30v1.0.0 起在说明中补充了 AHT30 描述以及 AHT21官方标注 AHT21 已 deprecated不推荐在新设计中选用芯片关键参数在 priv_include/aht20_reg.h 中定义型号名为ASAIR AHT20供电电压范围 2.2V ~ 5.5V工作温度范围 -40℃ ~ 125℃组件版本为 v2.0.02025-08-08 发布该版本引入了对i2c_bus通用总线组件的支持将底层 I2C 通信完全委托给 espressif/i2c_bus 组件依赖版本^1.4.0。组件的依赖信息见 idf_component.yml要求IDF 版本 4.3并依赖cmake_utilities与espressif/i2c_buspublic: true即使用方可以直接访问其头文件。I2C 总线初始化AHT20 驱动本身不管理 I2C 总线而是复用 esp-iot-solution 的i2c_bus组件。因此使用前必须先在应用侧创建总线句柄这一步骤与 AHT20 的驱动代码无关属于标准前置操作。#define I2C_MASTER_SCL_IO CONFIG_I2C_MASTER_SCL /*! GPIO number for I2C master clock */ #define I2C_MASTER_SDA_IO CONFIG_I2C_MASTER_SDA /*! GPIO number for I2C master data */ #define I2C_MASTER_NUM I2C_NUM_0 /*! I2C port number for master dev */ #define I2C_MASTER_FREQ_HZ 100000 /*! I2C master clock frequency */ const i2c_config_t i2c_bus_conf { .mode I2C_MODE_MASTER, .sda_io_num I2C_MASTER_SDA_IO, .sda_pullup_en GPIO_PULLUP_ENABLE, .scl_io_num I2C_MASTER_SCL_IO, .scl_pullup_en GPIO_PULLUP_ENABLE, .master.clk_speed I2C_MASTER_FREQ_HZ }; i2c_bus_handle_t i2c_bus i2c_bus_create(I2C_MASTER_NUM, i2c_bus_conf);要点说明I2C_MASTER_SCL_IO/I2C_MASTER_SDA_IO在测试工程中由 Kconfig 配置项提供默认 SCL40、SDA41见 test_apps/main/Kconfig.projbuild实际项目中可根据硬件接线替换为具体 GPIO 编号总线时钟频率I2C_MASTER_FREQ_HZ设为 100000100 kHz 标准模式符合 AHT20 数据手册对标准 I2C 速率的要求内部上下拉GPIO_PULLUP_ENABLE建议保持开启因为传感器模块通常不带强上拉i2c_bus_create返回的总线句柄需判空检查失败时返回NULL。该接口的完整定义可参考 components/i2c_bus/include/i2c_bus.h。创建 AHT20 设备句柄总线就绪后通过aht20_new_sensor在指定总线上创建 AHT20 设备句柄。设备配置结构体aht20_i2c_config_t定义于 include/aht20.haht20_i2c_config_t i2c_conf { .bus_inst i2c_bus, // I2C bus instance .i2c_addr AHT20_ADDRRES_0, // Device address }; aht20_dev_handle_t handle; aht20_new_sensor(i2c_conf, handle);设备地址如何确定AHT20 的 I2C 7 位地址由芯片的CEA0引脚决定定义在 include/aht20.h宏定义地址值CE 引脚电平AHT20_ADDRRES_00x38CE 拉低AHT20_ADDRESS_10x39CE 拉高从源码看aht20_new_sensor的实现aht20.c本质上是调用i2c_bus_device_create(bus_inst, i2c_addr, 0)在总线上挂载一个地址为 0x38/0x39 的子设备第三个参数 0 表示不覆盖总线时钟频率沿用总线默认时钟。创建成功时句柄非空若失败函数打印i2c_bus_device_create failed并返回ESP_FAIL。同时该函数会打印芯片型号与版本号、供电电压范围、工作温度范围等日志便于上电确认器件身份。aht20_dev_handle_t为void *类型对调用方透明内部实际是i2c_bus_device_handle_t。读取温湿度数据创建句柄后即可周期性调用aht20_read_temperature_humidity获取实时数据。该 API 同时输出原始值raw与换算后的物理量见 include/aht20.huint32_t temperature_raw, humidity_raw; float temperature, humidity; aht20_read_temperature_humidity(handle, temperature_raw, temperature, humidity_raw, humidity); ESP_LOGI(TAG, %-20s: %2.2f %%, humidity is, humidity); ESP_LOGI(TAG, %-20s: %2.2f degC, temperature is, temperature);参数说明temperature_raw/humidity_raw传感器返回的 20bit 原始 ADC 数据可用于自行换算或调试比对temperature/humidity驱动换算后的物理量湿度单位为 %RH温度单位为摄氏度返回值ESP_OK表示读取成功ESP_ERR_INVALID_ARG表示句柄非法ESP_ERR_NOT_FINISHED表示数据未就绪I2C 通信失败或 CRC 校验失败也会返回对应错误码。源码级原理一次温湿度读取的完整链路深入 aht20.c 的实现可以看到一次读取包含四个关键步骤1. 发送测量触发命令。驱动向命令寄存器写入AHT20_START_MEASURMENT_CMD0xAC定义于 aht20_reg.h并携带两个参数字节0x33, 0x00要求传感器进行一次温湿度测量。命令写完后驱动主动vTaskDelay(pdMS_TO_TICKS(100))等待 100ms——这是数据手册规定的测量时间余量属于阻塞等待实际应用中如需非阻塞流程可自行调度。2. 读取状态字节并检查标志位。驱动先读 1 字节状态依据 aht20_reg.h 定义的位含义进行三重校验BIT(AT581X_STATUS_Calibration_Enable)bit3校准已启用1才算数据有效BIT(AT581X_STATUS_CRC_FLAG)bit4CRC 标志位为 1 表示校验通过BIT(AT581X_STATUS_BUSY_INDICATION)bit7忙标志必须为 0即设备空闲。三者同时满足才进入数据读取否则打印data is not ready并返回ESP_ERR_NOT_FINISHED。3. 读取 7 字节数据并做 CRC 校验。数据帧为 6 字节有效数据 1 字节 CRC。驱动用aht20_calc_crc对前 6 字节计算 CRC8多项式 0x31初值 0xFF即 CRC-8/MAXIM并与第 7 字节比对不一致返回crc is error。4. 解析 20bit 原始数据并换算物理量。AHT20 的温湿度各占 20bit在 6 字节数据中交叉存放湿度由字节 1、2、3 拼接成 24bit 后右移 4 位得到 20bit 原始值换算公式humidity raw * 100 / 10485761048576 2^20将 0~2^20 的原始值映射到 0~100 %RH温度由字节 3 低 4 位 字节 4、5 拼接得到 20bit 原始值换算公式temperature raw * 200 / 1048576 - 50将原始值映射到 -50℃ ~ 150℃ 区间实际有效量程以芯片数据手册为准。这套解析逻辑完全对齐 AHT20 数据手册规定的数据格式如果你需要自行移植或二次开发可参照 aht20.c 中的位拼接与换算代码。资源清理传感器使用完毕或进入低功耗休眠前应释放资源与创建过程对称aht20_del_sensor(handle); i2c_bus_delete(i2c_bus);aht20_del_sensor内部调用i2c_bus_device_delete释放设备句柄aht20.c失败时打印i2c_bus_device_delete failed并返回对应错误码i2c_bus_delete释放整条总线资源。注意先删设备、再删总线顺序不可颠倒否则会留下悬垂引用。测试验证与内存泄漏检查仓库为组件提供了完整的单元测试工程位于 test_apps入口为 main/aht20_test.c配套 pytest_aht20.py 可实现自动化测试。测试用例sensor aht20 test完整走了一遍「总线创建 → 传感器创建 → 读取温湿度断言返回ESP_OK→ 删除传感器 → 删除总线」的生命周期同时通过setUp/tearDown对比测试前后的MALLOC_CAP_8BIT与MALLOC_CAP_32BIT堆空闲内存阈值 -400 字节验证驱动在创建/删除过程中不存在内存泄漏。这套测试代码本身就是一份可直接参考的最小可运行示例比 README 中的片段更完整。测试工程的 sdkconfig.defaults 关闭了任务看门狗兼容 IDF 4.4 与 5.0 两种写法并启用 USB Serial/JTAG 控制台便于在开发板上直接运行测试菜单。集成到你的工程在 ESP-IDF 工程中启用该组件有两条途径本地路径引用将 components/sensors/humiture/aht20 目录加入工程的EXTRA_COMPONENT_DIRSesp-iot-solution 仓库本身就是按组件目录组织可直接复用IDF Component Manager通过idf_component.yml声明依赖espressif/aht20组件清单见 idf_component.yml由构建系统自动拉取。无论哪种方式i2c_bus组件espressif/i2c_bus版本^1.4.0都会作为传递依赖自动引入。按照「总线初始化 → 传感器创建 → 周期读取 → 资源清理」四步即可完成一次完整的 AHT20 温湿度采集闭环整个过程不依赖具体板卡仅需根据硬件原理图确认 SCL/SDA 引脚与 CE 引脚的地址电平。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考