WLED Si7021_MQTT_HA Usermod将温湿度传感器数据发布到 MQTT 并自动注册 Home Assistant【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLEDWLED 不仅是一个灯带控制器其 usermod 扩展机制还允许把 ESP32/ESP8266 变成通用传感器节点。本文以仓库中的 Si7021_MQTT_HA usermod 为主线讲解如何通过 I²C 读取 Si7021 温湿度传感器、按固定周期发布到 WLED 内置 MQTT 设备主题以及自动发布 Home Assistant MQTT Auto-Discovery 配置、让传感器在 Home Assistant 中免手动配置直接出现。读完本文你可以完成从接线、PlatformIO 编译配置到 MQTT 主题与 HA 传感器注册的完整部署并理解该 usermod 在源码层面的生命周期与调度细节。功能定位与 MQTT 主题设计该 usermod 实现了 Si7021 I²C 温湿度传感器 的支持。需要注意的是传感器数据不会显示在 WLED 的 Web UI 上它的作用纯粹是作为传感器数据的 MQTT 发布器。核心行为如下基础数据温度、湿度发布到 WLED 内置 MQTT 设备主题$mqttDeviceTopic即 WLED 自身 MQTT 功能所使用的设备前缀下temperature: $mqttDeviceTopic/si7021_temperature humidity: $mqttDeviceTopic/si7021_humidity可选的衍生量由代码调用EnvironmentCalculations库计算得出heat_index: $mqttDeviceTopic/si7021_heat_index dew_point: $mqttDeviceTopic/si7021_dew_point absolute_humidity: $mqttDeviceTopic/si7021_absolute_humidity传感器数据每60 秒更新并发布一次对应源码loop()中的nextMeasure tempTimer 60000见 Si7021_MQTT_HA.cpp。同时支持 Home Assistant MQTT Auto-Discovery无需在 HA 中手写 YAML 传感器定义。从源码结构看该文件头部注释说明它 remix 自 sensors_to_mqtt 与 multi_relay 两个 usermod因此其 MQTT 发布与 I²C 初始化套路与这两个成熟 usermod 一致。依赖与编译前提该 usermod 的 library.json 声明了以下依赖PlatformIO 编译时会自动拉取{ name: Si7021_MQTT_HA, build: { libArchive: false }, dependencies: { finitestate/BME280: 3.0.0, adafruit/Adafruit Si7021 Library: 1.5.3, SPI: *, adafruit/Adafruit BusIO: 1.17.1 } }其中Adafruit Si7021 Library负责 I²C 寄存器级读写EnvironmentCalculations由 BME280 库提供负责根据温湿度计算热指数、露点与绝对湿度。还有一个硬性前提构建时 MQTT 必须处于启用状态。源码开头有编译期检查#ifdef WLED_DISABLE_MQTT #error This user mod requires MQTT to be enabled. #endif也就是说如果你的构建环境使用了-D WLED_DISABLE_MQTTplatformio_override.sample.ini 的注释中也列出了该开关该 usermod 会直接编译失败——这是作者显式拒绝支持无 MQTT 场景的方式。运行流程从 WiFi 上线到周期发布理解 Si7021_MQTT_HA.cpp 的四个生命周期回调就能掌握其完整行为链setup()仅在enabled为 true 时打印启动日志并调用si7021.begin()初始化 I²C 传感器L173-L180。此时并不触碰 MQTT。onMqttConnect()MQTT 连接建立后回调若mqttDeviceTopic非空则执行_initializeMqtt()——拼接五个完整主题、立即执行一次「读数 发布」并在开启 HA 发现时发布 discovery 配置L168-L171。connected()每次 WiFi重新连接后将首次测量安排在 5 秒后nextMeasure millis() 5000保证 WiFi 就绪后很快就有第一份数据。loop()主循环中的看门狗逻辑L188-L217调用yield()让出并在!enabled或灯带正在刷新strip.isUpdating()时直接返回避免在效果渲染高峰期占用 CPU到达nextMeasure后将下一轮安排在 60 秒后若传感器此前未初始化成功会在 loop 中重试初始化打印错误并等待下一轮提供了启动时 I²C 总线尚未就绪的容错只有WLED_MQTT_CONNECTED为真时才发布MQTT 断开时会复位mqttInitialized并打印提示重连后自动重新初始化主题与 discovery。这种「MQTT 未连接就不发布、重连后自愈」的设计使该 usermod 在断网重连场景下不需要人工干预。Home Assistant Auto-Discovery 配置详解开启Home Assistant MQTT Auto-Discovery后_publishHAMqttSensor()L71-L104会向标准 discovery 主题homeassistant/sensor/{mqttClientID}/{name}/config发布传感器配置其中mqttClientID是 WLED 的 MQTT 客户端 ID。配置载荷的字段如下字段取值说明name{serverDescription} {友好名}如 WLED Temperaturestate_topic对应数据主题与上文$mqttDeviceTopic/si7021_*一致unique_id{mqttClientID}{name}HA 实体唯一标识unit_of_measurement°C/%/g/m³绝对湿度单位为 g/m³device_classtemperature/humidity仅温度类传感器携带expire_after180030 分钟无更新则 HA 标记离线device.name/model/manufacturer/identifiers/sw_versionWLED 相关信息将传感器挂到同一 WLED 设备下几个值得注意的实现细节dew_point与absolute_humidity的device_class传空字符串源码中对空device_class/unit_of_measurement会跳过对应字段if (deviceClass ! )判断因此 HA 中它们仍会显示单位只是不被归类为标准温度传感器发布使用mqtt-publish(topic, 0, true, ...)的retained保留消息而数据消息使用非保留发布_publishSensorData()中 retain 参数为 false——discovery 配置需要保留以便 HA 重启后仍能读到温度、湿度两个基础传感器始终发布 discoveryheat_index、dew_point、absolute_humidity三个附加传感器受sendAdditionalSensors开关控制见 L58-L66。硬件接线与 I²C 引脚配置将 Si7021 传感器接到 I²C 总线即可。README 给出的默认引脚为// ESP32 SCL_PIN 22; SDA_PIN 21; // ESP8266 SCL_PIN 5; SDA_PIN 4;如果你的硬件使用其他 GPIO可以通过 WLED 的构建宏I2CSCLPIN/I2CSDAPIN初始化 I²C 接口。wled00/wled.h 中可以看到全局 I²C 引脚变量由这两个宏驱动// global I2C SDA pin (used for usermods) WLED_GLOBAL int8_t i2c_sda _INIT(I2CSDAPIN); // global I2C SCL pin (used for usermods) WLED_GLOBAL int8_t i2c_scl _INIT(I2CSCLPIN);platformio_override.sample.ini 中也给出了用法示例; -D I2CSDAPIN33 # initialise interface ; -D I2CSCLPIN35 # initialise interface在build_flags中加上-D I2CSDAPINxx -D I2CSCLPINxx即可切换到自定义引脚而HW_PIN_SCL/HW_PIN_SDA仅用于告知 WebUI 默认引脚提示不会真正初始化接口。Usermod 设置项编译烧录后三个运行时设置项会出现在 WLED 的 usermod 配置区对应源码中以PROGMEM常量定义的键名见 Si7021_MQTT_HA.cppusermod 显示名为 Si7021 MQTT (Home Assistant)ID 为USERMOD_ID_SI7021_MQTT_HA 29定义于 wled00/const.h配置键作用源码默认值enabled使能该 usermod关闭后loop()直接返回不读传感器也不发布falseSend Dew Point, Abs. Humidity and Heat Index是否同时发布露点、绝对湿度、热指数三个衍生传感器含其 discovery 配置与计算开销trueHome Assistant MQTT Auto-Discovery是否在 MQTT 连接时发布 HA discovery 配置true这三个布尔值同时通过addToConfig()/readFromConfig()持久化到 WLED 的 JSON 配置中断电重启后保留。安装步骤接线按上文将 Si7021 接到 I²CSDA/SCL 各加 4.7kΩ 上拉电阻是常规做法具体视模块而定编译配置在platformio_override.ini复制自 platformio_override.sample.ini的目标环境段中加入Si7021_MQTT_HAcustom_usermods ${env:esp32dev.custom_usermods} Si7021_MQTT_HA注意custom_usermods是环境段的独立键多个 usermod 用空格分隔sample 文件注释中有专门说明。仓库自带的 platformio.ini 中的[env:usermods]环境则使用custom_usermods *一次性展开usermods/目录下全部 usermod适合想整体体验的场景但会占用更多 flash确认 MQTT 可用确保构建未启用-D WLED_DISABLE_MQTT并在 WLED 的同步设置中配置好 MQTT broker 与设备主题运行时启用烧录后在 WLED 的 usermod 设置中打开enabled按需保留或关闭另外两个开关验证观察串口输出初始化日志、MQTT 缺失告警或在 MQTT 客户端订阅$mqttDeviceTopic/si7021_temperature与homeassistant/sensor/主题树确认数据与 discovery 配置均已到达。边界与限制数据只走 MQTTWLED UI 不显示传感器读数这是该 usermod 的设计定位发布节奏固定为 60 秒且首次读数安排在 WiFi 连接后 5 秒均写死在源码中不提供运行时调节每轮测量会阻塞式执行 I²C 读数与浮点计算源码特意在strip.isUpdating()期间跳过本轮以保护灯光效果流畅度——如果你的灯光负载重可留意这一避让逻辑带来的测量时间抖动该 usermod 属于社区贡献代码位于usermods/目录按 usermods 总说明 的约定其维护责任在各自作者随 WLED 主版本升级可能需要同步调整。小结Si7021_MQTT_HA 用不到 240 行源码Si7021_MQTT_HA.cpp展示了一个 WLED usermod 处理「外设 网络服务」的完整范式library.json声明依赖、编译期宏检查硬性前提、setup/connected/onMqttConnect/loop四个回调各司其职、retained discovery 消息 非 retained 数据消息区分对待、PROGMEM字符串与F()宏控制 flash 占用。如果你想给 WLED 增加其他传感器并接入 Home Assistant这个 usermod 连同 sensors_to_mqtt 都值得一读。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考