尧图网站建设 
WLED Temperature Usermod基于 DS18B20 的温度传感器集成与 MQTT 上报实战指南【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本篇指南围绕 WLED 官方 usermods 目录下的 Temperature usermodusermods/Temperature/readme.md展开它将 OneWire 总线的 Dallas 温度传感器DS18B20 等接入 ESP32/ESP8266 灯光控制器实现 Web UI Info 页显示、MQTT/temperature主题上报含 Home Assistant 自动发现并额外提供一个用灯带渲染温度的内置特效。读完后你将掌握该 usermod 的 PlatformIO 编译安装方式、编译期与运行期全部配置项、底层非阻塞测温的实现原理以及传感器缺失时的容错行为。一、功能概览这个 usermod 做什么Temperature usermod 脱胎于社区中优秀的QuinLED_Dig_Uno_Temp_MQTTusermodsrg74 和 400killer 作品由 blazoncek 维护。其核心能力包括传感器读取通过 OneWire 协议读取外接 DS18B20 温度传感器该传感器常见于 QuinLED Dig-Uno 主板源码中还兼容 DS18S20、DS1822、DS1825、DS28EA00 等家族器件UsermodTemperature.h、Temperature.cppWeb UI 展示温度值写入/json/info的u.Temperature与sensor.temperature字段显示在 WLED 网页 Info 区MQTT 发布若启用 MQTT则发布到mqttDeviceTopic/temperature摄氏度和mqttDeviceTopic/temperature_f华氏度并推送 Home Assistant 传感器自动发现配置以及可选的 Domoticz 虚拟传感器消息自动禁用机制启动时若检测不到传感器该 usermod 将自动禁用避免在没接传感器的板子上持续做无效读取附加特效传感器就绪后自动注册TemperatureMin,Max特效effect ID 255用灯带颜色渲染当前温度。从源码结构看该 usermod 被官方文档 usermods/readme.md 作为 v2 usermod API 的完整范例推荐“You can take a look atTemperaturefor a completed v2 usermod!”是学习编写 WLED 自定义插件的良好参考。二、安装在 platformio_override.ini 中启用2.1 编译期启用将Temperature加入custom_usermods列表即可。官方 readme 给出的示例platformio_override.ini如下[env:usermod_temperature_esp32dev] extends env:esp32dev custom_usermods ${env:esp32dev.custom_usermods} Temperature其工作机制可由仓库源码印证platformio.ini 中每个构建环境都有custom_usermods键构建脚本 pio-scripts/load_usermods.py 解析该键raw_usermods env.GetProjectOption(custom_usermods, )把名字对应到usermods/下的各插件文件夹并作为本地库参与编译platformio_override.sample.ini 中也有现成注释样例custom_usermods ${env:esp32dev.custom_usermods} Temperature并可通过-D TEMPERATURE_PIN13覆盖编译期默认引脚仓库内 platformio_override.sample.ini 的wemos_shield_esp32环境-D TEMPERATURE_PIN23就是 srg74 Wemos 扩展板上实际启用该 usermod 的配置。插件的依赖声明在 usermods/Temperature/library.json{ name: Temperature, build: { libArchive: false }, dependencies: { paulstoffregen/OneWire: ~2.3.8 } }即自动拉取 paulstoffregen 的 OneWire 库 ~2.3.8 版本。custom_usermods中多个 usermod 之间用空格分隔名字取自各插件library.json的name字段。2.2 硬件接线要点数据线DS18B20 的 DQ 接到某 GPIOESP32 默认GPIO18ESP8266 默认GPIO14见 UsermodTemperature.h 中TEMPERATURE_PIN定义可通过-D TEMPERATURE_PINx修改寄生供电parasitic power若传感器未接 Vcc仅 3 线接法需在 Usermods 设置页开启parasite-pwr并指定驱动外部 MOSFET 的parasite-pwr-pin。源码中requestTemperatures()发起转换时会将该引脚拉高转换完成后readTemperature()再拉低Temperature.cpp对应 DS18B20 寄生供电时序要求。三、配置项详解编译期宏 运行期设置页3.1 编译期选项选项说明默认值USERMOD_DALLASTEMPERATURE_MEASUREMENT_INTERVAL两次测量之间的间隔毫秒6000060 秒见 UsermodTemperature.hTEMPERATURE_PIN传感器 OneWire 数据引脚ESP32: 18ESP8266: 14注意 readme 特别强调所有参数包括引脚、摄氏/华氏、测量间隔都可以在运行时的 Usermods 设置页配置编译期宏只是兜底默认值。3.2 运行期设置页字段cfg.json 持久化由addToConfig()/readFromConfig()实现Temperature.cppcfg.json 中对应结构为{Temperature: {pin: 18, degC: true, enabled: true, read-interval-s: 60, parasite-pwr: false, parasite-pwr-pin: -1, domoticz-idx: -1, resolution: 3}}字段类型说明enabledbool是否启用该 usermodpinint8OneWire 数据 GPIOdegCbooltrue为摄氏度false为华氏度read-interval-sint读取间隔秒源码中限定在10120 秒min(120,max(10,...)) * 1000Temperature.cppparasite-pwrbool传感器是否寄生供电parasite-pwr-pinint8寄生供电 MOSFET 驱动引脚domoticz-idxintDomoticz 虚拟传感器 idx-1 表示不发送 Domoticz 消息resolution0–3转换分辨率09-bit(0.5°C)、110-bit(0.25°C)、211-bit(0.125°C)、312-bit(0.0625°C)设置页选项文案由appendConfigData()生成且对 DS18S20 无效引脚变更时的热重初始化的实现细节readFromConfig()检测到新引脚与旧值不同时会delete oneWire、通过PinManager::deallocatePin()释放旧引脚占用者标识为PinOwner::UM_Temperature见 pin_manager.h然后重新调用setup()——即换引脚无需重启设备。四、底层实现非阻塞测温与容错4.1 启动检测setupsetup()的执行链Temperature.cpp通过PinManager::allocatePin()申请 OneWire 引脚调用oneWire-reset()探测总线成功则进入findSensor()先reset_search()再search()遍历器件校验 8 字节 ROM 地址的 CRC并按家族码识别 DS18S20(0x10)/DS1822(0x22)/DS18B20(0x28)/DS1825(0x3B)/DS28EA00(0x42)找不到传感器时最多重试 10 次每次delay(25)sensorFound保持为 0loop()会因此直接返回usermod 事实上被禁用传感器找到且initDone未置位时注册TemperatureMin,Max特效strip.addEffect(255, mode_temperature, ...)。4.2 非阻塞测量状态机loop2020-09-12 版本起改为异步非阻塞实现。loop()Temperature.cpp是一个两段式状态机未到采样时刻now - lastMeasurement readingInterval直接返回发起转换waitingForConversion为假时调用requestTemperatures()——OneWire reset → skip ROM → 写0x44转换命令第 2 字节携带寄生供电标志置位waitingForConversion等待转换完成DS18B20 数据手册标称转换时间 93.75 ms12-bit实际可达 750 ms代码以750 ms作为安全阈值到期后调用readTemperature()读出结果并更新时间戳。lastMeasurement只在实际读取完成后才更新因此间隔计时天然包含了转换耗时。4.3 快速读取与数值解码readDallasreadDallas()是 Peter Scargill 的快速读法reset → skip ROM → 写0xBE读暂存器→ 一次read_bytes取 9 字节前两字节即温度第 9 字节为 CRCTemperature.cpp。解码规则DS18S209-bit 精度temp raw × 0.5DS18B20/DS1822/DS1825/DS28EA0012-bit 精度temp raw × 0.06252^-4并按resolution对低位做截断以匹配 9/10/11-bit 精度错误判定readDallas()末尾对 9 字节做 AND 折叠全 0xFF线浮空典型表现或读值-127°C均视为无效读。-127恰好在 DS18B20 量程最低 -50°C之外被用作“传感器错误”哨兵值。WLED_DEBUG 构建下还会逐字节打印 CRC 校验失败的原始数据便于排查接线问题。4.4 异常处理与自动恢复单次读到 -100°C的值不发布 MQTT防止曲线图被异常尖刺污染并立即安排 300 ms 后的重测连续 10 次错误读后sensorFound清零usermod 进入“未找到传感器”状态Web UI Info 页对temperature -100显示0 / Sensor Error!addToJsonInfo()。4.5 版本演进readme Change Log 完整继承2020-09-12改为异步非阻塞实现不向 MQTT 上报错误低温传感器未检测到时禁用插件Info 屏在未读到时显示“距首次读取还有多少秒”而非传感器错误2021-04适配运行时配置2023-05按新版 usermod 规范重写曾推荐 blazoncek 的 OneWire for ESP32 fork 以规避 Sensor error2024-09OneWire 升级到 2.3.8含 stickbreaker 与 garyd9 的 ESP32 修复不再需要 fork——与 library.json 中~2.3.8声明一致。五、MQTT 接口与 Home Assistant 集成5.1 发布主题当WLED_MQTT_CONNECTED且读值有效 -100°C时Temperature.cppmqttDeviceTopic/temperature摄氏度retained falsemqttDeviceTopic/temperature_f华氏度retained false若domoticz-idx 0另向domoticz/in发布{idx: x, RSSI: ..., nvalue: 0, svalue: xx.x}。5.2 Home Assistant 自动发现每次 MQTT重连接后onMqttConnect()发布一条 retained 配置到homeassistant/sensor/escapedMac/config{ name: serverDescription Temperature, state_topic: mqttDeviceTopic/temperature, device_class: temperature, unique_id: MAC, unit_of_measurement: °C }即 Home Assistant 会零配置地出现一个温度传感器实体。注意 HA 配置的单位固定为 °C见publishHomeAssistantAutodiscovery()中unit_of_measurement摄氏/华氏切换只影响 WLED 自身显示与temperature_f主题。六、附加特效TemperatureMin,Max传感器就绪后自动注册的特效effect ID 255Temperature.cpp把整个片段填充为按温度映射的调色板颜色速度speed映射下限0–255 → -150°C ~ 150°C默认 15°C强度intensity映射上限0–255 → 300°C ~ 600°C默认 30°C当前摄氏温度 ×10 提升精度后夹在 [low, high] 区间线性映射到调色板索引 0–248。效果数据串TemperatureMin,Max;;!;01;pal54,sx255,ix0指定默认调色板等参数实际使用时可在 WLED 中把 Speed 拉到目标下限、Intensity 拉到目标上限来设定自己关心的量程。七、与其他 usermod 的协作PWM_fan 插件可直接复用本 usermod 的温度读数usermods/PWM_fan/PWM_fan.cpp中通过UsermodManager::lookup(USERMOD_ID_TEMPERATURE)拿到UsermodTemperature实例USERMOD_ID_TEMPERATURE 3定义于 wled00/const.h实现“按温度调速风扇”的组合方案——这正是 readme 所述“可能在未来扩展支持更多传感器类型”思路的实例化。八、故障排查清单现象排查点Info 显示 Sensor Error!接线/DQ 引脚/上拉电阻开启parasite-pwr MOSFET 引脚3 线接法时必须WLED_DEBUG 构建下查看串口 CRC 打印MQTT 无数据确认 MQTT 已连接检查read-interval-s是否在 10–120 范围读值 -100°C 会被刻意丢弃换引脚不生效设置页保存后会自动重建 OneWirereadFromConfig()检测到 pin 变化即重初始化确认保存的配置值确实改变编译找不到插件custom_usermods名字须与 library.json 的nameTemperature完全一致且每行独立书写适用前提与限制本 usermod 目前仅支持 OneWire/Dallas 家族温度传感器readme 明确“可能在未来扩展支持其他类型”读取间隔被限制在 10–120 秒resolution选项对 DS18S20 无效MQTT/HA/Domoticz 相关功能仅在未以-D WLED_DISABLE_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），仅供参考 WLED Temperature Usermod：基于 DS18B20 的温度传感器集成与 MQTT 上报实战指南
WLED Temperature Usermod基于 DS18B20 的温度传感器集成与 MQTT 上报实战指南【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本篇指南围绕 WLED 官方 usermods 目录下的 Temperature usermodusermods/Temperature/readme.md展开它将 OneWire 总线的 Dallas 温度传感器DS18B20 等接入 ESP32/ESP8266 灯光控制器实现 Web UI Info 页显示、MQTT/temperature主题上报含 Home Assistant 自动发现并额外提供一个用灯带渲染温度的内置特效。读完后你将掌握该 usermod 的 PlatformIO 编译安装方式、编译期与运行期全部配置项、底层非阻塞测温的实现原理以及传感器缺失时的容错行为。一、功能概览这个 usermod 做什么Temperature usermod 脱胎于社区中优秀的QuinLED_Dig_Uno_Temp_MQTTusermodsrg74 和 400killer 作品由 blazoncek 维护。其核心能力包括传感器读取通过 OneWire 协议读取外接 DS18B20 温度传感器该传感器常见于 QuinLED Dig-Uno 主板源码中还兼容 DS18S20、DS1822、DS1825、DS28EA00 等家族器件UsermodTemperature.h、Temperature.cppWeb UI 展示温度值写入/json/info的u.Temperature与sensor.temperature字段显示在 WLED 网页 Info 区MQTT 发布若启用 MQTT则发布到mqttDeviceTopic/temperature摄氏度和mqttDeviceTopic/temperature_f华氏度并推送 Home Assistant 传感器自动发现配置以及可选的 Domoticz 虚拟传感器消息自动禁用机制启动时若检测不到传感器该 usermod 将自动禁用避免在没接传感器的板子上持续做无效读取附加特效传感器就绪后自动注册TemperatureMin,Max特效effect ID 255用灯带颜色渲染当前温度。从源码结构看该 usermod 被官方文档 usermods/readme.md 作为 v2 usermod API 的完整范例推荐“You can take a look atTemperaturefor a completed v2 usermod!”是学习编写 WLED 自定义插件的良好参考。二、安装在 platformio_override.ini 中启用2.1 编译期启用将Temperature加入custom_usermods列表即可。官方 readme 给出的示例platformio_override.ini如下[env:usermod_temperature_esp32dev] extends env:esp32dev custom_usermods ${env:esp32dev.custom_usermods} Temperature其工作机制可由仓库源码印证platformio.ini 中每个构建环境都有custom_usermods键构建脚本 pio-scripts/load_usermods.py 解析该键raw_usermods env.GetProjectOption(custom_usermods, )把名字对应到usermods/下的各插件文件夹并作为本地库参与编译platformio_override.sample.ini 中也有现成注释样例custom_usermods ${env:esp32dev.custom_usermods} Temperature并可通过-D TEMPERATURE_PIN13覆盖编译期默认引脚仓库内 platformio_override.sample.ini 的wemos_shield_esp32环境-D TEMPERATURE_PIN23就是 srg74 Wemos 扩展板上实际启用该 usermod 的配置。插件的依赖声明在 usermods/Temperature/library.json{ name: Temperature, build: { libArchive: false }, dependencies: { paulstoffregen/OneWire: ~2.3.8 } }即自动拉取 paulstoffregen 的 OneWire 库 ~2.3.8 版本。custom_usermods中多个 usermod 之间用空格分隔名字取自各插件library.json的name字段。2.2 硬件接线要点数据线DS18B20 的 DQ 接到某 GPIOESP32 默认GPIO18ESP8266 默认GPIO14见 UsermodTemperature.h 中TEMPERATURE_PIN定义可通过-D TEMPERATURE_PINx修改寄生供电parasitic power若传感器未接 Vcc仅 3 线接法需在 Usermods 设置页开启parasite-pwr并指定驱动外部 MOSFET 的parasite-pwr-pin。源码中requestTemperatures()发起转换时会将该引脚拉高转换完成后readTemperature()再拉低Temperature.cpp对应 DS18B20 寄生供电时序要求。三、配置项详解编译期宏 运行期设置页3.1 编译期选项选项说明默认值USERMOD_DALLASTEMPERATURE_MEASUREMENT_INTERVAL两次测量之间的间隔毫秒6000060 秒见 UsermodTemperature.hTEMPERATURE_PIN传感器 OneWire 数据引脚ESP32: 18ESP8266: 14注意 readme 特别强调所有参数包括引脚、摄氏/华氏、测量间隔都可以在运行时的 Usermods 设置页配置编译期宏只是兜底默认值。3.2 运行期设置页字段cfg.json 持久化由addToConfig()/readFromConfig()实现Temperature.cppcfg.json 中对应结构为{Temperature: {pin: 18, degC: true, enabled: true, read-interval-s: 60, parasite-pwr: false, parasite-pwr-pin: -1, domoticz-idx: -1, resolution: 3}}字段类型说明enabledbool是否启用该 usermodpinint8OneWire 数据 GPIOdegCbooltrue为摄氏度false为华氏度read-interval-sint读取间隔秒源码中限定在10120 秒min(120,max(10,...)) * 1000Temperature.cppparasite-pwrbool传感器是否寄生供电parasite-pwr-pinint8寄生供电 MOSFET 驱动引脚domoticz-idxintDomoticz 虚拟传感器 idx-1 表示不发送 Domoticz 消息resolution0–3转换分辨率09-bit(0.5°C)、110-bit(0.25°C)、211-bit(0.125°C)、312-bit(0.0625°C)设置页选项文案由appendConfigData()生成且对 DS18S20 无效引脚变更时的热重初始化的实现细节readFromConfig()检测到新引脚与旧值不同时会delete oneWire、通过PinManager::deallocatePin()释放旧引脚占用者标识为PinOwner::UM_Temperature见 pin_manager.h然后重新调用setup()——即换引脚无需重启设备。四、底层实现非阻塞测温与容错4.1 启动检测setupsetup()的执行链Temperature.cpp通过PinManager::allocatePin()申请 OneWire 引脚调用oneWire-reset()探测总线成功则进入findSensor()先reset_search()再search()遍历器件校验 8 字节 ROM 地址的 CRC并按家族码识别 DS18S20(0x10)/DS1822(0x22)/DS18B20(0x28)/DS1825(0x3B)/DS28EA00(0x42)找不到传感器时最多重试 10 次每次delay(25)sensorFound保持为 0loop()会因此直接返回usermod 事实上被禁用传感器找到且initDone未置位时注册TemperatureMin,Max特效strip.addEffect(255, mode_temperature, ...)。4.2 非阻塞测量状态机loop2020-09-12 版本起改为异步非阻塞实现。loop()Temperature.cpp是一个两段式状态机未到采样时刻now - lastMeasurement readingInterval直接返回发起转换waitingForConversion为假时调用requestTemperatures()——OneWire reset → skip ROM → 写0x44转换命令第 2 字节携带寄生供电标志置位waitingForConversion等待转换完成DS18B20 数据手册标称转换时间 93.75 ms12-bit实际可达 750 ms代码以750 ms作为安全阈值到期后调用readTemperature()读出结果并更新时间戳。lastMeasurement只在实际读取完成后才更新因此间隔计时天然包含了转换耗时。4.3 快速读取与数值解码readDallasreadDallas()是 Peter Scargill 的快速读法reset → skip ROM → 写0xBE读暂存器→ 一次read_bytes取 9 字节前两字节即温度第 9 字节为 CRCTemperature.cpp。解码规则DS18S209-bit 精度temp raw × 0.5DS18B20/DS1822/DS1825/DS28EA0012-bit 精度temp raw × 0.06252^-4并按resolution对低位做截断以匹配 9/10/11-bit 精度错误判定readDallas()末尾对 9 字节做 AND 折叠全 0xFF线浮空典型表现或读值-127°C均视为无效读。-127恰好在 DS18B20 量程最低 -50°C之外被用作“传感器错误”哨兵值。WLED_DEBUG 构建下还会逐字节打印 CRC 校验失败的原始数据便于排查接线问题。4.4 异常处理与自动恢复单次读到 -100°C的值不发布 MQTT防止曲线图被异常尖刺污染并立即安排 300 ms 后的重测连续 10 次错误读后sensorFound清零usermod 进入“未找到传感器”状态Web UI Info 页对temperature -100显示0 / Sensor Error!addToJsonInfo()。4.5 版本演进readme Change Log 完整继承2020-09-12改为异步非阻塞实现不向 MQTT 上报错误低温传感器未检测到时禁用插件Info 屏在未读到时显示“距首次读取还有多少秒”而非传感器错误2021-04适配运行时配置2023-05按新版 usermod 规范重写曾推荐 blazoncek 的 OneWire for ESP32 fork 以规避 Sensor error2024-09OneWire 升级到 2.3.8含 stickbreaker 与 garyd9 的 ESP32 修复不再需要 fork——与 library.json 中~2.3.8声明一致。五、MQTT 接口与 Home Assistant 集成5.1 发布主题当WLED_MQTT_CONNECTED且读值有效 -100°C时Temperature.cppmqttDeviceTopic/temperature摄氏度retained falsemqttDeviceTopic/temperature_f华氏度retained false若domoticz-idx 0另向domoticz/in发布{idx: x, RSSI: ..., nvalue: 0, svalue: xx.x}。5.2 Home Assistant 自动发现每次 MQTT重连接后onMqttConnect()发布一条 retained 配置到homeassistant/sensor/escapedMac/config{ name: serverDescription Temperature, state_topic: mqttDeviceTopic/temperature, device_class: temperature, unique_id: MAC, unit_of_measurement: °C }即 Home Assistant 会零配置地出现一个温度传感器实体。注意 HA 配置的单位固定为 °C见publishHomeAssistantAutodiscovery()中unit_of_measurement摄氏/华氏切换只影响 WLED 自身显示与temperature_f主题。六、附加特效TemperatureMin,Max传感器就绪后自动注册的特效effect ID 255Temperature.cpp把整个片段填充为按温度映射的调色板颜色速度speed映射下限0–255 → -150°C ~ 150°C默认 15°C强度intensity映射上限0–255 → 300°C ~ 600°C默认 30°C当前摄氏温度 ×10 提升精度后夹在 [low, high] 区间线性映射到调色板索引 0–248。效果数据串TemperatureMin,Max;;!;01;pal54,sx255,ix0指定默认调色板等参数实际使用时可在 WLED 中把 Speed 拉到目标下限、Intensity 拉到目标上限来设定自己关心的量程。七、与其他 usermod 的协作PWM_fan 插件可直接复用本 usermod 的温度读数usermods/PWM_fan/PWM_fan.cpp中通过UsermodManager::lookup(USERMOD_ID_TEMPERATURE)拿到UsermodTemperature实例USERMOD_ID_TEMPERATURE 3定义于 wled00/const.h实现“按温度调速风扇”的组合方案——这正是 readme 所述“可能在未来扩展支持更多传感器类型”思路的实例化。八、故障排查清单现象排查点Info 显示 Sensor Error!接线/DQ 引脚/上拉电阻开启parasite-pwr MOSFET 引脚3 线接法时必须WLED_DEBUG 构建下查看串口 CRC 打印MQTT 无数据确认 MQTT 已连接检查read-interval-s是否在 10–120 范围读值 -100°C 会被刻意丢弃换引脚不生效设置页保存后会自动重建 OneWirereadFromConfig()检测到 pin 变化即重初始化确认保存的配置值确实改变编译找不到插件custom_usermods名字须与 library.json 的nameTemperature完全一致且每行独立书写适用前提与限制本 usermod 目前仅支持 OneWire/Dallas 家族温度传感器readme 明确“可能在未来扩展支持其他类型”读取间隔被限制在 10–120 秒resolution选项对 DS18S20 无效MQTT/HA/Domoticz 相关功能仅在未以-D WLED_DISABLE_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），仅供参考