WLED 怎么把 Temperature usermod 加进固件？在 platformio_override.ini 里配置 custom_usermods
【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED
WLED 的源码仓库自带一个 Temperature usermod，它读取外接的 DS18B20 温度传感器，把温度显示在 Web UI 的 Info 区域，并在启用时发布到/temperatureMQTT 主题。但它没有包含在现成的 OTA 固件里，必须自己从源码编译。本文以 ESP32 的esp32dev环境为例，说明如何在platformio_override.ini里通过custom_usermods把 Temperature usermod 编译进固件，以及怎么确认它真的链接进去了。
前提条件
- 已克隆 WLED 源码仓库，后续所有路径都相对仓库根目录。
- 安装好 PlatformIO（
pio命令可用）和 Node.js（Web UI 构建需要）。 - 硬件上有一个接线好的 DS18B20 传感器。注意 usermods/Temperature/readme.md 中的说明：如果启动时检测不到传感器，这个 usermod 会自动禁用，固件仍然正常编译运行。
Temperature usermod 的库名和依赖定义在 usermods/Temperature/library.json 中，name字段为Temperature，并依赖paulstoffregen/OneWire ~2.3.8。这个name就是后面写进custom_usermods的值，两者必须一致。
关键机制：custom_usermods 是 env 级别的键，不是 build_flag
platformio.ini通过extra_configs加载platformio_override.ini（该文件仓库默认不带，需要用样例文件复制生成）：
extra_configs = platformio_override.ini platformio_release.iniplatformio_override.sample.ini 中的注释明确了配置规则：
custom_usermods是 env 小节里的一个独立键，不能写进build_flags；- 多个 usermod 之间用空格分隔；
- 名称来自各 usermod 的
library.json的name字段。
编译时 pio-scripts/load_usermods.py 会解析custom_usermods的每一项：纯名称会在usermods/目录下查找对应文件夹（_v2后缀和usermod_v2_前缀可以省略），找不到就报Couldn't locate module <名称> in usermods directory!使构建失败；然后把该目录以symlink://形式注入lib_deps参与编译。Temperature 的目录实际叫usermods/Temperature，写Temperature即可。
配置 platformio_override.ini
在仓库根目录把样例文件复制为实际生效的文件：
cp platformio_override.sample.ini platformio_override.ini然后在platformio_override.ini里新增一个 env 小节。Temperature 文档给出的示例是继承esp32dev环境、保留其原有 usermods 并追加Temperature：
[env:usermod_temperature_esp32dev] extends = env:esp32dev custom_usermods = ${env:esp32dev.custom_usermods} Temperature写法说明：
extends = env:esp32dev继承 platformio.ini 中esp32dev环境的平台、分区表、库依赖等，只定义差异项。esp32dev环境自身的custom_usermods是audioreactive，所以用${env:esp32dev.custom_usermods}先把它带上，再追加Temperature。如果你不需要 audioreactive，把这一项去掉、只保留Temperature即可。custom_usermods的值可以写在同一行，也可以像上面那样换行续写（每行一个名称，空行和;/#开头的注释行会被跳过）。- 如果你构建的是其他目标环境（例如 platformio_override.sample.ini 里自带的
esp32dev_dio80，或 ESP8266 的esp01_1m_full），把extends和变量引用换成对应环境即可，写法不变。 - 样例文件注释中还有为 DS18B20 指定 GPIO 的示例，可选：在
build_flags中加-D TEMPERATURE_PIN=13，数字换成你实际接线的 GPIO。不配置时引脚在运行时设置页指定。
platformio_override.sample.ini 中还有现成的完整参考，如wemos_shield_esp32环境：
custom_usermods = ${env:esp32dev.custom_usermods} Temperature four_line_display_ALT ... -D TEMPERATURE_PIN=23想同时加多个 usermod，在同一行继续用空格追加名称即可，例如Temperature four_line_display_ALT。
构建固件
AGENTS.md 规定：构建固件前必须先构建 Web UI，因为它会生成固件编译所需的 C 头文件：
npm ci && npm run build pio run -e usermod_temperature_esp32dev- 如果你把自定义环境名写进了文件顶部的
[platformio]段default_envs，也可以直接pio run而不带-e；用-e指定环境名更明确，避免误编译默认环境。 - 构建耗时以分钟计（AGENTS.md 中标注
pio run约 5 分钟超时）。 - 清理构建产物的命令是
pio run --target clean。
验证 usermod 已编入固件
构建链里有两个内置检查，构建日志中都能直接看到：
- pio-scripts/load_usermods.py 会强制检查 usermod 的
library.json含"build": {"libArchive": false}，否则直接终止构建并报ERROR: libArchive=false is missing on usermod(s) ...。Temperature 的 library.json 已包含该字段，正常构建不会触发。 - pio-scripts/validate_modules.py 在链接完成后校验每个 usermod 的符号确实出现在最终 ELF 和 map 文件中，构建日志会出现如下形式的输出：
INFO: N libraries included as WLED optional/user modules INFO: N usermod object entries found INFO: Code from usermod libraries found in binary: Temperature如果某 usermod 的符号没进链接结果，脚本会报ERROR: No symbols from [...] found in linked output!并使构建失败。构建成功且日志中出现 Temperature，即说明该 usermod 已正确链接进固件；构建成功本身也说明usermods/目录下找到了对应文件夹且名称拼写正确。
把固件烧录到开发板并联网后，Temperature 的运行时效果是：温度出现在 Web UI 的 Info 区域；如果启用了 MQTT，则发布到/temperature主题。传感器未接入时不会报错，usermod 自身禁用，Info 页会显示距离首次读取还有多少秒（而非传感器错误）。
常见问题排查
| 现象 | 原因与处理 |
|---|---|
构建报Couldn't locate module Temperature in usermods directory! | custom_usermods里的名称在usermods/下找不到对应目录。检查拼写是否与 usermods/Temperature/library.json 的name一致（_v2后缀可省略，但Temperature本就没有后缀）。 |
| 加了配置但固件里没有 usermod 生效 | 确认custom_usermods写在 env 小节的独立键中，而不是混进build_flags；确认它属于你实际用-e编译的那个环境。 |
构建报ERROR: libArchive=false is missing on usermod(s) ... | 该 usermod 的library.json缺少"build": {"libArchive": false}，模块无法正确链接。用仓库内 usermod 时一般已具备，外部自写的 usermod 需自行补上。 |
板上 Info 页没有温度、MQTT 无/temperature | 优先检查 DS18B20 是否接好并上电：文档明确"传感器启动时未检测到则 usermod 自动禁用"。引脚可用-D TEMPERATURE_PIN=<GPIO>在构建时固定，或在运行时 Usermods 设置页配置。 |
运行时配置与限制
- 编译期可选宏：
USERMOD_DALLASTEMPERATURE_MEASUREMENT_INTERVAL，单位为毫秒，默认 60000 ms（60 秒），即两次测量之间的间隔。 - 引脚、摄氏/华氏、测量间隔等参数都可以在运行时的 Usermods 设置页修改，不必每次改 ini 重新编译。
- usermods/readme.md 提醒：WLED 版本更新后 usermods 可能失效，且仓库内 usermod 由各自作者维护，升级固件后如遇 Temperature 编译失败，需要以新版本为准调整该 usermod。
配置完成后的结果很明确：pio run成功且 validate_modules 日志列出 Temperature，固件烧录后 Info 页出现温度读数——这两点满足即代表 Temperature usermod 已成功加入你的 WLED 固件。
【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
