拓冰网站定制 
WLED AHT10_v2 Usermod 接入指南用 ESP32 读取 AHT10/AHT15/AHT20 温湿度传感器【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLEDWLED 的AHT10_v2Usermod 是一个通过 I2C 总线读取 AHT10、AHT15、AHT20 三款温湿度传感器的官方扩展模块能够将温度、湿度数据接入 WLED 的信息面板并可选地通过 MQTT 发布到外部系统含 Home Assistant 自动发现。本文将以 usermods/AHT10_v2/README.md 为主线结合 AHT10_v2.cpp 的完整源码实现讲解该 Usermod 的配置参数、编译启用、数据输出格式与 MQTT 集成原理帮助你在自己的 WLED 固件中快速加入环境温湿度监测能力。一、Usermod 能做什么AHT10_v2专为 WLED v2 Usermod API 编写是 AHT 系列传感器在 WLED 中的标准接入方案。它完成三件事周期性采集按照可配置的间隔通过 I2C 读取传感器原始数据换算为温度摄氏度与相对湿度百分比状态可视化把最近一次读数写入 WLED 的 JSON Info API/u节点在 Web UI 的 Info 页面即可看到实时温湿度可选 MQTT 上报把温度、湿度发布到 MQTT Broker并支持 Home Assistant Discovery让 HA 自动创建传感器实体。从源码看该模块由 AHT10_v2.cpp 中的UsermodAHT10类实现其 Usermod ID 为USERMOD_ID_AHT10定义于 wled00/src/const.h值为 51并最终通过REGISTER_USERMOD(aht10_v2)宏注册进 WLED 的 usermod 管理框架宏定义见 wled00/src/fcn_declare.h。二、Usermod 菜单配置参数详解配置在 WLED 的Usermod 菜单Settings → Usermod中完成。官方 README 列出的核心参数及其源码中的处理逻辑如下参数含义取值范围 / 默认值源码依据I2CAddressI2C 地址十进制560x38默认或570x39_i2cAddress AHT10_ADDRESS_0X38SensorType传感器型号0 AHT10、1 AHT15、2 AHT20默认0ASAIR_I2C_SENSOR枚举转换CheckInterval两次读取的间隔秒1 ~ 600 秒默认 60 秒内部换算为毫秒存储默认 60000msDecimals输出保留的小数位数0 ~ 5默认 2内部以10^n的_decimalFactor存储默认 1002.1 I2CAddress地址选择AHT10/15/20 的 I2C 地址由芯片引脚决定常见为0x3856或0x3957。代码中默认采用AHT10_ADDRESS_0X38。若你的模块是0x39地址请在菜单中改为57。2.2 SensorType芯片型号同一颗驱动对不同型号的校准命令有差异务必与实物对应0对应 AHT101对应 AHT152对应 AHT20。源码在readFromConfig()中对输入做了严格校验非法值会被回退为AHT10_SENSOR见 AHT10_v2.cpp。2.3 CheckInterval 与 DecimalsCheckInterval用户在界面中填写秒源码在配置加载时将其乘以 1000 转为毫秒若超出 1~600 秒范围则回退为默认 60000ms见 AHT10_v2.cpp。注意600秒是硬上限即最长 10 分钟一次。Decimals用户在界面中填写小数位数0~5源码用pow10f换算为倍率因子并在读取时通过truncateDecimals()做四舍五入截断见 AHT10_v2.cpp 与 L269-L277。2.4 额外 MQTT 开关源码补充除 README 列出的四项外源码还提供了三个编译期随 MQTT 功能启用的配置项在WLED_DISABLE_MQTT未定义时可用MqttPublish是否发布 MQTT 值MqttPublishAlways是否无视变化量、每次都发布否则仅在变化超过阈值时发布MqttHomeAssistantDiscovery是否启用 Home Assistant 自动发现。三、编译启用步骤3.1 添加依赖库在platformio.ini或你自己的platformio_override.ini的lib_deps中加入以下两个库enjoyneering/AHT10~1.1.0AHT10/15/20 驱动WireArduino I2C 库实际上该 Usermod 自带的 library.json 已经声明了enjoyneering/AHT10:~1.1.0依赖并设置了build: { libArchive: false }这是所有 WLED usermod 必须满足的编译约束见 pio-scripts/load_usermods.py因此当你通过custom_usermods启用它时PlatformIO 会自动解析库依赖README 中的Wire依赖主要用于 I2C 总线的底层支持。3.2 在 custom_usermods 中启用编辑platformio_override.ini新建一个基于现有 env 的环境并追加AHT10[env:aht10_example] extends env:esp32dev custom_usermods ${env:esp32dev.custom_usermods} AHT10构建脚本 load_usermods.py 会依次在usermods/AHT10、usermods/AHT10_v2、usermods/usermod_v2_AHT10中定位模块因此这里填AHT10即可命中usermods/AHT10_v2目录无需改名。若你希望一次性编译全部 usermod可参考 platformio.ini 中[env:usermods]的写法custom_usermods *星号会展开为usermods/下所有带library.json的模块。3.3 接线提醒AHT10/15/20 通过 I2C 与 ESP32 连接VCC→ 3.3VGND→ GNDSCL/SDA接到开发板对应的 I2C 引脚。WLED 启动时会自动初始化 I2C 总线Usermod 的setup()中调用initializeAht()完成驱动对象创建见 AHT10_v2.cpp。四、读取流程与容错机制源码剖析UsermodAHT10::loop()是核心读取逻辑其流程如下见 AHT10_v2.cpp开关与冲突检查若 Usermod 被禁用或 LED 灯带正处于刷新strip.isUpdating()状态直接返回避免影响显示性能节流以millis()与_lastLoopCheck的差值判断是否到达_checkInterval未到则跳过读取原始数据调用_aht-readRawData()错误软复位若返回AHT10_ERROR打印调试信息并调用_aht-softReset()复位传感器后重试一次复位失败则放弃本轮换算与截断读取成功后用readTemperature(AHT10_USE_READ_DATA)与readHumidity(AHT10_USE_READ_DATA)得到温度与湿度再经truncateDecimals()按配置的小数位数取整缓存结果将读数存入_lastTemperature/_lastHumidity供 Info JSON 使用。这种“失败→软复位→重试”的容错设计可有效应对传感器上电时序不稳定、总线偶发错误导致的读取失败。五、数据输出Info JSON 与 Web UIaddToJsonInfo()见 AHT10_v2.cpp把数据写入 JSON Info 的u节点输出结构形如{ u: { Temperature: [23.45, °C], Humidity: [51.2, %] } }状态处理上很有讲究首次运行尚未读取时输出Not read yet最近一次读取出错时输出An error occurred而不是展示过期的脏数据。温度带单位°C湿度带单位%方便前端直接渲染。六、MQTT 与 Home Assistant 集成当编译未定义WLED_DISABLE_MQTT时Usermod 提供完整的 MQTT 支持发布 Topic温度发布到{mqttDeviceTopic}/temperature湿度发布到{mqttDeviceTopic}/humidity见 AHT10_v2.cpp变化量阈值mqttPublishIfChanged()仅在变化超过阈值时才发布除非勾选MqttPublishAlways。温度阈值取0.1湿度阈值取0.5——源码注释明确说明这是基于传感器精度温度 ±0.3°C、湿度 ±2%合理选择的既避免无意义的频繁上报又保证变化可感知见 AHT10_v2.cppHome Assistant DiscoverymqttCreateHassSensor()会在homeassistant/sensor/{mqttClientID}/{名称}/config发布传感器配置 JSON声明device_classtemperature/humidity、unit_of_measurement、unique_id并把两个传感器挂载到同一台 WLED 设备wled-sensor-{mqttClientID}HA 侧可自动识别设备并分组展示见 AHT10_v2.cpp。注意MQTT 相关的初始化在onMqttConnect()中触发见 AHT10_v2.cpp保证只有在 MQTT 已连接时才创建 Discovery 主题发布前也会检查WLED_MQTT_CONNECTED避免在断线时向空指针发布导致崩溃。七、配置持久化与热重载addToConfig()/readFromConfig()实现配置的保存与加载见 AHT10_v2.cpp配置以AHTxx为键存放在 WLED 的cfg.json中源码中类名为UsermodAHT10但 PROGMEM 存储的名字是AHTxx见 AHT10_v2.cpp保存时把内部毫秒值除以 1000 转回秒、把小数倍率取对数转回位数与用户界面保持一致加载时对每个字段做范围校验任一字段缺失则整体判定configComplete false若配置在运行中被修改_initDone为真会立即重新创建驱动对象并重建 MQTT 传感器实现“热重载”无需重启设备。八、常见问题排查Info 面板显示 An error occurred多为接线问题或 I2C 地址不符检查I2CAddress是否与模块实际地址一致确认 SCL/SDA 接线正确读数恒为 0 或异常值确认SensorType与芯片型号一致AHT15/AHT20 与 AHT10 的校准命令不同选错会导致解析错误MQTT 无数据确认MqttPublish已开启、WLED 已连接 Broker若开启MqttPublishAlways可强制每轮发布以便调试编译报错确认lib_deps中已引入enjoyneering/AHT10~1.1.0且该 Usermod 的library.json未被改动libArchive: false是链接所必需的。九、扩展阅读若你想了解 v2 Usermod API 的通用规范多 Usermod 共存、addToConfig/readFromConfig约定可阅读 usermods/EXAMPLE/readme.md 与示例源码 usermod_v2_example.cpp传感器 Usermod 的更多同类实现BME280、DHT、Si7021 等位于 usermods/ 目录可对比学习不同传感器的接入模式Usermod 的整体启用机制与构建脚本说明见 pio-scripts/load_usermods.py 与 platformio.ini 中的custom_usermods相关配置。通过以上配置你的 WLED 设备即可化身环境监测节点LED 灯效之外还能在 Web 界面看到实时温湿度并自动同步到 Home Assistant 等智能家居平台为后续联动如根据温度自动调整灯光亮度、湿度超限告警打下基础。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WLED AHT10_v2 Usermod 接入指南：用 ESP32 读取 AHT10/AHT15/AHT20 温湿度传感器
WLED AHT10_v2 Usermod 接入指南用 ESP32 读取 AHT10/AHT15/AHT20 温湿度传感器【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLEDWLED 的AHT10_v2Usermod 是一个通过 I2C 总线读取 AHT10、AHT15、AHT20 三款温湿度传感器的官方扩展模块能够将温度、湿度数据接入 WLED 的信息面板并可选地通过 MQTT 发布到外部系统含 Home Assistant 自动发现。本文将以 usermods/AHT10_v2/README.md 为主线结合 AHT10_v2.cpp 的完整源码实现讲解该 Usermod 的配置参数、编译启用、数据输出格式与 MQTT 集成原理帮助你在自己的 WLED 固件中快速加入环境温湿度监测能力。一、Usermod 能做什么AHT10_v2专为 WLED v2 Usermod API 编写是 AHT 系列传感器在 WLED 中的标准接入方案。它完成三件事周期性采集按照可配置的间隔通过 I2C 读取传感器原始数据换算为温度摄氏度与相对湿度百分比状态可视化把最近一次读数写入 WLED 的 JSON Info API/u节点在 Web UI 的 Info 页面即可看到实时温湿度可选 MQTT 上报把温度、湿度发布到 MQTT Broker并支持 Home Assistant Discovery让 HA 自动创建传感器实体。从源码看该模块由 AHT10_v2.cpp 中的UsermodAHT10类实现其 Usermod ID 为USERMOD_ID_AHT10定义于 wled00/src/const.h值为 51并最终通过REGISTER_USERMOD(aht10_v2)宏注册进 WLED 的 usermod 管理框架宏定义见 wled00/src/fcn_declare.h。二、Usermod 菜单配置参数详解配置在 WLED 的Usermod 菜单Settings → Usermod中完成。官方 README 列出的核心参数及其源码中的处理逻辑如下参数含义取值范围 / 默认值源码依据I2CAddressI2C 地址十进制560x38默认或570x39_i2cAddress AHT10_ADDRESS_0X38SensorType传感器型号0 AHT10、1 AHT15、2 AHT20默认0ASAIR_I2C_SENSOR枚举转换CheckInterval两次读取的间隔秒1 ~ 600 秒默认 60 秒内部换算为毫秒存储默认 60000msDecimals输出保留的小数位数0 ~ 5默认 2内部以10^n的_decimalFactor存储默认 1002.1 I2CAddress地址选择AHT10/15/20 的 I2C 地址由芯片引脚决定常见为0x3856或0x3957。代码中默认采用AHT10_ADDRESS_0X38。若你的模块是0x39地址请在菜单中改为57。2.2 SensorType芯片型号同一颗驱动对不同型号的校准命令有差异务必与实物对应0对应 AHT101对应 AHT152对应 AHT20。源码在readFromConfig()中对输入做了严格校验非法值会被回退为AHT10_SENSOR见 AHT10_v2.cpp。2.3 CheckInterval 与 DecimalsCheckInterval用户在界面中填写秒源码在配置加载时将其乘以 1000 转为毫秒若超出 1~600 秒范围则回退为默认 60000ms见 AHT10_v2.cpp。注意600秒是硬上限即最长 10 分钟一次。Decimals用户在界面中填写小数位数0~5源码用pow10f换算为倍率因子并在读取时通过truncateDecimals()做四舍五入截断见 AHT10_v2.cpp 与 L269-L277。2.4 额外 MQTT 开关源码补充除 README 列出的四项外源码还提供了三个编译期随 MQTT 功能启用的配置项在WLED_DISABLE_MQTT未定义时可用MqttPublish是否发布 MQTT 值MqttPublishAlways是否无视变化量、每次都发布否则仅在变化超过阈值时发布MqttHomeAssistantDiscovery是否启用 Home Assistant 自动发现。三、编译启用步骤3.1 添加依赖库在platformio.ini或你自己的platformio_override.ini的lib_deps中加入以下两个库enjoyneering/AHT10~1.1.0AHT10/15/20 驱动WireArduino I2C 库实际上该 Usermod 自带的 library.json 已经声明了enjoyneering/AHT10:~1.1.0依赖并设置了build: { libArchive: false }这是所有 WLED usermod 必须满足的编译约束见 pio-scripts/load_usermods.py因此当你通过custom_usermods启用它时PlatformIO 会自动解析库依赖README 中的Wire依赖主要用于 I2C 总线的底层支持。3.2 在 custom_usermods 中启用编辑platformio_override.ini新建一个基于现有 env 的环境并追加AHT10[env:aht10_example] extends env:esp32dev custom_usermods ${env:esp32dev.custom_usermods} AHT10构建脚本 load_usermods.py 会依次在usermods/AHT10、usermods/AHT10_v2、usermods/usermod_v2_AHT10中定位模块因此这里填AHT10即可命中usermods/AHT10_v2目录无需改名。若你希望一次性编译全部 usermod可参考 platformio.ini 中[env:usermods]的写法custom_usermods *星号会展开为usermods/下所有带library.json的模块。3.3 接线提醒AHT10/15/20 通过 I2C 与 ESP32 连接VCC→ 3.3VGND→ GNDSCL/SDA接到开发板对应的 I2C 引脚。WLED 启动时会自动初始化 I2C 总线Usermod 的setup()中调用initializeAht()完成驱动对象创建见 AHT10_v2.cpp。四、读取流程与容错机制源码剖析UsermodAHT10::loop()是核心读取逻辑其流程如下见 AHT10_v2.cpp开关与冲突检查若 Usermod 被禁用或 LED 灯带正处于刷新strip.isUpdating()状态直接返回避免影响显示性能节流以millis()与_lastLoopCheck的差值判断是否到达_checkInterval未到则跳过读取原始数据调用_aht-readRawData()错误软复位若返回AHT10_ERROR打印调试信息并调用_aht-softReset()复位传感器后重试一次复位失败则放弃本轮换算与截断读取成功后用readTemperature(AHT10_USE_READ_DATA)与readHumidity(AHT10_USE_READ_DATA)得到温度与湿度再经truncateDecimals()按配置的小数位数取整缓存结果将读数存入_lastTemperature/_lastHumidity供 Info JSON 使用。这种“失败→软复位→重试”的容错设计可有效应对传感器上电时序不稳定、总线偶发错误导致的读取失败。五、数据输出Info JSON 与 Web UIaddToJsonInfo()见 AHT10_v2.cpp把数据写入 JSON Info 的u节点输出结构形如{ u: { Temperature: [23.45, °C], Humidity: [51.2, %] } }状态处理上很有讲究首次运行尚未读取时输出Not read yet最近一次读取出错时输出An error occurred而不是展示过期的脏数据。温度带单位°C湿度带单位%方便前端直接渲染。六、MQTT 与 Home Assistant 集成当编译未定义WLED_DISABLE_MQTT时Usermod 提供完整的 MQTT 支持发布 Topic温度发布到{mqttDeviceTopic}/temperature湿度发布到{mqttDeviceTopic}/humidity见 AHT10_v2.cpp变化量阈值mqttPublishIfChanged()仅在变化超过阈值时才发布除非勾选MqttPublishAlways。温度阈值取0.1湿度阈值取0.5——源码注释明确说明这是基于传感器精度温度 ±0.3°C、湿度 ±2%合理选择的既避免无意义的频繁上报又保证变化可感知见 AHT10_v2.cppHome Assistant DiscoverymqttCreateHassSensor()会在homeassistant/sensor/{mqttClientID}/{名称}/config发布传感器配置 JSON声明device_classtemperature/humidity、unit_of_measurement、unique_id并把两个传感器挂载到同一台 WLED 设备wled-sensor-{mqttClientID}HA 侧可自动识别设备并分组展示见 AHT10_v2.cpp。注意MQTT 相关的初始化在onMqttConnect()中触发见 AHT10_v2.cpp保证只有在 MQTT 已连接时才创建 Discovery 主题发布前也会检查WLED_MQTT_CONNECTED避免在断线时向空指针发布导致崩溃。七、配置持久化与热重载addToConfig()/readFromConfig()实现配置的保存与加载见 AHT10_v2.cpp配置以AHTxx为键存放在 WLED 的cfg.json中源码中类名为UsermodAHT10但 PROGMEM 存储的名字是AHTxx见 AHT10_v2.cpp保存时把内部毫秒值除以 1000 转回秒、把小数倍率取对数转回位数与用户界面保持一致加载时对每个字段做范围校验任一字段缺失则整体判定configComplete false若配置在运行中被修改_initDone为真会立即重新创建驱动对象并重建 MQTT 传感器实现“热重载”无需重启设备。八、常见问题排查Info 面板显示 An error occurred多为接线问题或 I2C 地址不符检查I2CAddress是否与模块实际地址一致确认 SCL/SDA 接线正确读数恒为 0 或异常值确认SensorType与芯片型号一致AHT15/AHT20 与 AHT10 的校准命令不同选错会导致解析错误MQTT 无数据确认MqttPublish已开启、WLED 已连接 Broker若开启MqttPublishAlways可强制每轮发布以便调试编译报错确认lib_deps中已引入enjoyneering/AHT10~1.1.0且该 Usermod 的library.json未被改动libArchive: false是链接所必需的。九、扩展阅读若你想了解 v2 Usermod API 的通用规范多 Usermod 共存、addToConfig/readFromConfig约定可阅读 usermods/EXAMPLE/readme.md 与示例源码 usermod_v2_example.cpp传感器 Usermod 的更多同类实现BME280、DHT、Si7021 等位于 usermods/ 目录可对比学习不同传感器的接入模式Usermod 的整体启用机制与构建脚本说明见 pio-scripts/load_usermods.py 与 platformio.ini 中的custom_usermods相关配置。通过以上配置你的 WLED 设备即可化身环境监测节点LED 灯效之外还能在 Web 界面看到实时温湿度并自动同步到 Home Assistant 等智能家居平台为后续联动如根据温度自动调整灯光亮度、湿度超限告警打下基础。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考