WLED Usermods 实战指南v2 用户扩展模块的编写、注册与 PlatformIO 构建集成【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLEDWLED 的 usermods/readme.md 定义了官方仓库中usermods/目录的定位它是所有社区用户扩展模块customusermod.cpp的集中存放地并给出了贡献规范与维护责任约定。本文以该文档为骨架结合仓库中的 v2 示例模块、模块管理器源码 和 PlatformIO 构建脚本完整讲清如何按官方规范贡献一个 usermod、v2 API 的回调生命周期与配置持久化机制、REGISTER_USERMOD的底层注册原理以及如何通过custom_usermods选项把模块编译进固件。读完本文你可以独立开发、构建并验证一个可复用的 WLED v2 usermod。一、usermods 目录定位、贡献规范与维护责任usermods/readme.md的核心内容可以归纳为三条约定目录结构约定。每个 usermod 放在usermods/下一个具有描述性名称的独立文件夹中例如usermod_ds18b20_temp_sensor_mqtt并包含该模块的全部自定义文件。改动主代码必须写说明文档。如果你的 usermod 需要修改 WLED 其他文件必须在模块内附一份readme.md逐条列出让使用者复现所需步骤。通过 Pull Request 贡献。仓库明确欢迎贡献如果你的功能对大多数 WLED 用户普遍有用维护者会考虑将其并入基础代码base code。维护责任方面文档特别强调两点使用方必须理解随版本更新可能失效WLED 主代码持续演进usermods 可能在新版本上编译失败或行为异常——“While I do my best to not break too much, keep in mind that as WLED is updated, usermods might break.”维护者是模块作者本人WLED 官方并不主动维护usermods/目录下的任何模块兼容性修复责任在创建者。从当前仓库的实际结构可以印证这一生态usermods/下已有数十个模块涵盖传感器usermods/Temperature、BME68X_v2、BH1750_v2、显示usermods/Analog_Clock、TetrisAI_v2、电源usermods/Battery、显示外设ST7789_display等类别命名上可清晰区分 v1多为usermod.cpp与 v2目录名带_v2后缀或usermod_v2_前缀两代 API。二、为什么推荐 v2 API多模块共存与类继承设计readme 给出了一条明确建议新写的 usermod 应尽量采用 v2 usermod API因为它支持“一次编译安装多个 usermod”并提供了新的回调函数。官方指向两个参考usermods/EXAMPLE带完整注释的 v2 示例文档中写作EXAMPLE_v2当前仓库中的实际目录名为EXAMPLEusermods/Temperature一个功能完整的 v2 成品模块适合作为传感器类 usermod 的模板。v2 usermod 的本质是继承自Usermod基类的类。usermods/EXAMPLE/usermod_v2_example.cpp 展示了完整的骨架// 类名应有描述性并保留 : public Usermod 部分 class MyExampleUsermod : public Usermod { private: bool enabled false; bool initDone false; // 配置变量建议在这里或 readFromConfig()、构造函数中设默认值 bool testBool false; float testFloat 42.42; String testString Forty-Two; // 多次使用的字符串用 static const char[] 存放节省 flash static const char _name[]; static const char _enabled[]; public: // 下面各方法由 WLED 在特定时机调用详见下一节 void setup() override { ... } void loop() override { ... } // ... }; // 实现类的静态字符串与成员方法 const char MyExampleUsermod::_name[] PROGMEM ExampleUsermod; // 实例化并注册 static MyExampleUsermod example_usermod; REGISTER_USERMOD(example_usermod);关键设计点可选实现无需实现基类的所有方法“Your usermod will remain compatible as it does not need to implement all methods from the Usermod base class!”——后续 WLED 新增回调时旧模块仍可编译多文件组织示例注释说明一个 usermod 可以拆分为多个.h/.cpp文件如 usermods/EXAMPLE 与Battery模块的types/子目录结构唯一 IDgetId()可返回在const.h中定义的唯一 ID示例使用USERMOD_ID_EXAMPLE系统可据此判断模块是否安装其他模块也可通过UsermodManager::lookup(USERMOD_ID_EXAMPLE)跨模块交互见 wled00/um_manager.cpp#L80-L87。三、v2 生命周期回调全解析以下回调及语义均来自 usermods/EXAMPLE/usermod_v2_example.cpp 的注释与实现并按调用时机分组。3.1 启动与网络事件回调调用时机典型用途readFromConfig(JsonObject)配置加载时启动时必定调用且早于setup()读取持久化设置返回bool指示配置完整性setup()启动时调用一次此时 WiFi 尚未连接初始化变量、传感器、外设connected()每次 WiFi重新连接时初始化网络相关接口loop()主循环中持续调用事件检查、读取传感器onMqttConnect(bool sessionPresent)MQTT 连接建立时MQTT 相关初始化#ifndef WLED_DISABLE_MQTTonUpdateBegin(bool init)固件 OTA 更新开始前由 wled00/um_manager.cpp#L74 转发loop()中官方给了两条重要实践建议同样来自示例注释void loop() override { // 若 usermod 未启用或正处于灯带更新期间则直接退出 if (!enabled || (strip.isUpdating() (millis() - lastTime 200))) return; // 避免 delay()尤其禁止超过 10ms 的延迟应使用 millis() 定时器判断 if (millis() - lastTime 1000) { lastTime millis(); } }3.2 JSON API 与 Web UI 集成addToJsonInfo(JsonObject root)向/json/info注入自定义键值。官方惯例是创建u对象存放自定义数据例如传感器读数{ExampleUsermod:[20, lux]}传感器类模块还可向sensor对象发布数据。addToJsonState(JsonObject root)/readFromJsonState(JsonObject root)分别向/json/state写入和读取客户端可修改的状态。示例中用if (!initDone) return;防止启动阶段applyPreset()引发崩溃。appendConfigData()进入“Usermod Settings”设置页时被调用可输出 JS 片段为字段添加提示文字或下拉框。注意oappend()缓冲区上限仅3KB不可写入过多内容。3.3 渲染与输入覆盖handleOverlayDraw()在每次show()灯带刷新帧之前、特效着色完成后调用常用于把某些像素强制刷成指定颜色——示例注释指出它“Commonly used for custom clocks (Cronixie, 7 segment)”仓库中 usermods/Cronixie 即典型应用。handleButton(uint8_t b)可覆盖默认按钮行为返回true则阻止默认处理。示例复刻了 wled00/button.cpp 中的保护逻辑对BTN_TYPE_NONE、BTN_TYPE_RESERVED、BTN_TYPE_PIR_SENSOR、模拟按键类型直接放行。3.4 持久化配置addToConfig 与 readFromConfig这是 v2 API 最实用的能力之一——配置项会自动出现在 Usermod Settings 设置页无需手写 HTML。示例中的写法void addToConfig(JsonObject root) override { JsonObject top root.createNestedObject(FPSTR(_name)); top[FPSTR(_enabled)] enabled; top[testInt] testInt; top[testFloat] testFloat; top[testString] testString; JsonArray pinArray top.createNestedArray(pin); pinArray.add(testPins[0]); pinArray.add(testPins[1]); } bool readFromConfig(JsonObject root) override { JsonObject top root[FPSTR(_name)]; bool configComplete !top.isNull(); configComplete getJsonValue(top[testBool], testBool); // 三参数 getJsonValue()第三个参数作为缺失时的默认值 configComplete getJsonValue(top[testInt], testInt, 42); // pin 字段在设置页有特殊处理支持 some_pin 形式 configComplete getJsonValue(top[pin][0], testPins[0], -1); return configComplete; }从示例的长段注释中可以提炼出官方给出的规则细节写配置类 usermod 时务必注意调用时机addToConfig()在设置真正被保存如 LED 设置保存时调用若要在loop()中强制保存当前状态需手动调用serializeConfig()——但该函数触发文件系统写操作可能导致 LED 抖动并加速 flash 磨损只在 loop 中谨慎调用绝不在网络回调中调用。返回值语义readFromConfig()返回true表示设置页配置完整返回false则 WLED 会把默认值落盘使缺失项也在设置页可编辑。数值解析规则由设置页浏览器端行为决定含小数点的数字按 Cfloat解析6~7 位有效精度不支持 double不含小数点的数字按int32_t-2147483648 ~ 2147483647解析溢出截断后再次截断到你声明的 C 类型键名pin的字段单个整数或整数数组在设置页享受特殊处理引脚冲突标红、特殊引脚如仅输入引脚标黄告警官方建议使用int8_t存引脚值-1表示未配置。Flash 优化技巧官方提示参考usermod_v2_auto_save仓库中为 usermods/usermod_v2_auto_save通过复用 ArduinoJson 键名字符串节省 Flash。如需完全自定义布局的独立设置页则必须手动修改 HTML、xml.cpp与set.cpp——示例注释明确建议参考 WLED Soundreactive 分支的做法工作量大得多非必要不采用。四、注册机制REGISTER_USERMOD 与 UsermodManagerv2 模块如何被 WLED 主循环统一调度答案在 wled00/um_manager.cpp文件顶部通过DECLARE_DYNARRAY(Usermod*, usermods)声明一个动态数组零长度哨兵段 链接脚本排序机制由 pio-scripts/dynarray.py 支持。每个模块文件末尾的REGISTER_USERMOD(instance)宏把实例指针插入该数组因此多个 v2 模块可以在一次编译中共存——这正是 readme 推荐 v2 的核心理由。UsermodManager的每个静态方法都是对数组的线性遍历转发例如void UsermodManager::setup() { for (auto mod DYNARRAY_BEGIN(usermods); mod DYNARRAY_END(usermods); mod) (*mod)-setup(); } void UsermodManager::loop() { for (auto mod DYNARRAY_BEGIN(usermods); mod DYNARRAY_END(usermods); mod) (*mod)-loop(); }见 wled00/um_manager.cpp#L21-L75其中几个方法带有“首个处理者获胜”语义onMqttMessage()、onEspNowMessage()、onUdpPacket()一旦有模块返回true即停止分发handleButton()则聚合所有模块的返回值。lookup(uint16_t mod_id)按getId()查找模块支撑模块间协作示例第 65~78 行注释演示了如何用#ifdef USERMOD_EXAMPLElookup在两个 usermod 间交换状态。文件末尾还有一个精巧细节wled00/um_manager.cpp#L91-L99Usermod::oappend_shim静态指针实现了appendConfigData()无参重载到appendConfigData(Print dest)的桥接使模块代码里可以直接调用oappend(F(...))而无需显式传递输出流。五、构建集成custom_usermods 与编译校验README 级文档只说“把模块加入custom_usermods并编译”仓库源码则揭示了完整的解析与校验链路。5.1 声明方式在platformio.ini或自己的platformio_override.ini的目标环境里添加custom_usermods选项。仓库自身的用法示例platformio.ini[env:nodemcuv2] extends esp8266 board nodemcuv2 build_flags ${common.build_flags} ${esp8266.build_flags} -D WLED_RELEASE_NAME\ESP8266\ custom_usermods audioreactiveplatformio.ini#L108 处还定义了default_usermods audioreactive供各 ESP32 环境引用。批量测试 usermod 的开发者可以直接使用仓库提供的 usermods/platformio_override.usermods.ini它定义了usermods_esp32、usermods_esp32c3、usermods_esp32s2、usermods_esp32s3四个 16MB 大分区环境并把模块清单集中在[usermods]段的custom_usermods变量中注释标明该清单在 CI 中填充。5.2 解析规则pio-scripts/load_usermods.py该 pre 脚本把custom_usermods的每一行转成lib_deps条目支持三类写法裸模块名如audioreactive一行可写多个空格分隔find_usermod()按“原名 →原名_v2→usermod_v2_原名”三种目录命名依次匹配usermods/下的子目录命中后生成symlink://绝对路径依赖load_usermods.py#L13-L28。这解释了 usermods 目录中三种命名并存的由来。通配符*展开为usermods/下所有带library.json的子目录load_usermods.py#L128-L137。外部依赖URL、owner/Name 版本、Name spec等形式按lib_deps语法原样透传脚本还会尽力预测库名以便后续识别为 WLED 模块。对每个被识别为 usermod 的库脚本还会把wled00/源码目录加入其CPPPATH使模块能直接#include wled.h、为其追加-g调试信息供链接后校验使用并强制检查libArchive未被设置——缺失时直接报错退出ERROR: libArchivefalse is missing on usermod(s) name -- modules will not compile in correctly. Add build: {libArchive: false} to their library.json.这就是为什么每个 usermod 的library.json都必须形如 usermods/EXAMPLE/library.json{ name: EXAMPLE, build: { libArchive: false }, dependencies: {} }libArchive: false保证模块代码被直接链入最终可执行文件而非静态库否则REGISTER_USERMOD产生的注册符号可能被未引用而丢弃。5.3 链接后校验pio-scripts/validate_modules.pypost 脚本在 ELF 生成后做双重验证一是解析 map 文件中.dynarray.usermods.00000与.dynarray.usermods.99999哨兵段之间的地址跨度除以 4 字节指针大小得到实际注册的 usermod 实例数与DYNARRAY_LENGTH宏的语义一致二是用readelf --debug-dumpinfo读取顶层编译单元 DIE将各模块的源码路径与DW_AT_comp_dir/DW_AT_name匹配确认每个声明的 usermod 都真实编译进了二进制——有缺失即Exit(1)使构建失败。从源码结构看该校验专门针对 LTO 场景设计LTO 下 map 文件路径被 ltrans 分区替换直接数 section 出现次数不可靠。六、从示例到贡献一份可操作的检查清单结合 readme 约定与源码实现一个新 v2 usermod 的完整交付物应为usermods/描述性名称/目录内含library.jsonname与目录一致build: {libArchive: false}、readme.md功能说明、安装方式、依赖与引脚说明若改动了 WLED 主代码文件则必须写明改动步骤以及模块的.cpp/.h源码源码中类继承自Usermod只实现所需回调末尾以static 实例 REGISTER_USERMOD(实例)注册getId()对应const.h中申请的 ID在本地platformio_override.ini的对应环境中把目录名加入custom_usermods编译验证构建日志中应看到INFO: N libraries included as WLED optional/user modules与INFO: Code from usermod libraries found in binary: ...两行校验输出提交 Pull Request作为作者自行跟踪 WLED 版本升级并修复兼容性——这是 readme 明确的维护责任。此外官方对“普遍有用”的功能保留了并入基础代码的通道因此模块设计时应尽量保持依赖最小化library.json的dependencies精确声明第三方库、配置项走 v2 持久化接口这样才能被大多数用户环境直接采纳。【免费下载链接】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 Usermods 实战指南：v2 用户扩展模块的编写、注册与 PlatformIO 构建集成
WLED Usermods 实战指南v2 用户扩展模块的编写、注册与 PlatformIO 构建集成【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLEDWLED 的 usermods/readme.md 定义了官方仓库中usermods/目录的定位它是所有社区用户扩展模块customusermod.cpp的集中存放地并给出了贡献规范与维护责任约定。本文以该文档为骨架结合仓库中的 v2 示例模块、模块管理器源码 和 PlatformIO 构建脚本完整讲清如何按官方规范贡献一个 usermod、v2 API 的回调生命周期与配置持久化机制、REGISTER_USERMOD的底层注册原理以及如何通过custom_usermods选项把模块编译进固件。读完本文你可以独立开发、构建并验证一个可复用的 WLED v2 usermod。一、usermods 目录定位、贡献规范与维护责任usermods/readme.md的核心内容可以归纳为三条约定目录结构约定。每个 usermod 放在usermods/下一个具有描述性名称的独立文件夹中例如usermod_ds18b20_temp_sensor_mqtt并包含该模块的全部自定义文件。改动主代码必须写说明文档。如果你的 usermod 需要修改 WLED 其他文件必须在模块内附一份readme.md逐条列出让使用者复现所需步骤。通过 Pull Request 贡献。仓库明确欢迎贡献如果你的功能对大多数 WLED 用户普遍有用维护者会考虑将其并入基础代码base code。维护责任方面文档特别强调两点使用方必须理解随版本更新可能失效WLED 主代码持续演进usermods 可能在新版本上编译失败或行为异常——“While I do my best to not break too much, keep in mind that as WLED is updated, usermods might break.”维护者是模块作者本人WLED 官方并不主动维护usermods/目录下的任何模块兼容性修复责任在创建者。从当前仓库的实际结构可以印证这一生态usermods/下已有数十个模块涵盖传感器usermods/Temperature、BME68X_v2、BH1750_v2、显示usermods/Analog_Clock、TetrisAI_v2、电源usermods/Battery、显示外设ST7789_display等类别命名上可清晰区分 v1多为usermod.cpp与 v2目录名带_v2后缀或usermod_v2_前缀两代 API。二、为什么推荐 v2 API多模块共存与类继承设计readme 给出了一条明确建议新写的 usermod 应尽量采用 v2 usermod API因为它支持“一次编译安装多个 usermod”并提供了新的回调函数。官方指向两个参考usermods/EXAMPLE带完整注释的 v2 示例文档中写作EXAMPLE_v2当前仓库中的实际目录名为EXAMPLEusermods/Temperature一个功能完整的 v2 成品模块适合作为传感器类 usermod 的模板。v2 usermod 的本质是继承自Usermod基类的类。usermods/EXAMPLE/usermod_v2_example.cpp 展示了完整的骨架// 类名应有描述性并保留 : public Usermod 部分 class MyExampleUsermod : public Usermod { private: bool enabled false; bool initDone false; // 配置变量建议在这里或 readFromConfig()、构造函数中设默认值 bool testBool false; float testFloat 42.42; String testString Forty-Two; // 多次使用的字符串用 static const char[] 存放节省 flash static const char _name[]; static const char _enabled[]; public: // 下面各方法由 WLED 在特定时机调用详见下一节 void setup() override { ... } void loop() override { ... } // ... }; // 实现类的静态字符串与成员方法 const char MyExampleUsermod::_name[] PROGMEM ExampleUsermod; // 实例化并注册 static MyExampleUsermod example_usermod; REGISTER_USERMOD(example_usermod);关键设计点可选实现无需实现基类的所有方法“Your usermod will remain compatible as it does not need to implement all methods from the Usermod base class!”——后续 WLED 新增回调时旧模块仍可编译多文件组织示例注释说明一个 usermod 可以拆分为多个.h/.cpp文件如 usermods/EXAMPLE 与Battery模块的types/子目录结构唯一 IDgetId()可返回在const.h中定义的唯一 ID示例使用USERMOD_ID_EXAMPLE系统可据此判断模块是否安装其他模块也可通过UsermodManager::lookup(USERMOD_ID_EXAMPLE)跨模块交互见 wled00/um_manager.cpp#L80-L87。三、v2 生命周期回调全解析以下回调及语义均来自 usermods/EXAMPLE/usermod_v2_example.cpp 的注释与实现并按调用时机分组。3.1 启动与网络事件回调调用时机典型用途readFromConfig(JsonObject)配置加载时启动时必定调用且早于setup()读取持久化设置返回bool指示配置完整性setup()启动时调用一次此时 WiFi 尚未连接初始化变量、传感器、外设connected()每次 WiFi重新连接时初始化网络相关接口loop()主循环中持续调用事件检查、读取传感器onMqttConnect(bool sessionPresent)MQTT 连接建立时MQTT 相关初始化#ifndef WLED_DISABLE_MQTTonUpdateBegin(bool init)固件 OTA 更新开始前由 wled00/um_manager.cpp#L74 转发loop()中官方给了两条重要实践建议同样来自示例注释void loop() override { // 若 usermod 未启用或正处于灯带更新期间则直接退出 if (!enabled || (strip.isUpdating() (millis() - lastTime 200))) return; // 避免 delay()尤其禁止超过 10ms 的延迟应使用 millis() 定时器判断 if (millis() - lastTime 1000) { lastTime millis(); } }3.2 JSON API 与 Web UI 集成addToJsonInfo(JsonObject root)向/json/info注入自定义键值。官方惯例是创建u对象存放自定义数据例如传感器读数{ExampleUsermod:[20, lux]}传感器类模块还可向sensor对象发布数据。addToJsonState(JsonObject root)/readFromJsonState(JsonObject root)分别向/json/state写入和读取客户端可修改的状态。示例中用if (!initDone) return;防止启动阶段applyPreset()引发崩溃。appendConfigData()进入“Usermod Settings”设置页时被调用可输出 JS 片段为字段添加提示文字或下拉框。注意oappend()缓冲区上限仅3KB不可写入过多内容。3.3 渲染与输入覆盖handleOverlayDraw()在每次show()灯带刷新帧之前、特效着色完成后调用常用于把某些像素强制刷成指定颜色——示例注释指出它“Commonly used for custom clocks (Cronixie, 7 segment)”仓库中 usermods/Cronixie 即典型应用。handleButton(uint8_t b)可覆盖默认按钮行为返回true则阻止默认处理。示例复刻了 wled00/button.cpp 中的保护逻辑对BTN_TYPE_NONE、BTN_TYPE_RESERVED、BTN_TYPE_PIR_SENSOR、模拟按键类型直接放行。3.4 持久化配置addToConfig 与 readFromConfig这是 v2 API 最实用的能力之一——配置项会自动出现在 Usermod Settings 设置页无需手写 HTML。示例中的写法void addToConfig(JsonObject root) override { JsonObject top root.createNestedObject(FPSTR(_name)); top[FPSTR(_enabled)] enabled; top[testInt] testInt; top[testFloat] testFloat; top[testString] testString; JsonArray pinArray top.createNestedArray(pin); pinArray.add(testPins[0]); pinArray.add(testPins[1]); } bool readFromConfig(JsonObject root) override { JsonObject top root[FPSTR(_name)]; bool configComplete !top.isNull(); configComplete getJsonValue(top[testBool], testBool); // 三参数 getJsonValue()第三个参数作为缺失时的默认值 configComplete getJsonValue(top[testInt], testInt, 42); // pin 字段在设置页有特殊处理支持 some_pin 形式 configComplete getJsonValue(top[pin][0], testPins[0], -1); return configComplete; }从示例的长段注释中可以提炼出官方给出的规则细节写配置类 usermod 时务必注意调用时机addToConfig()在设置真正被保存如 LED 设置保存时调用若要在loop()中强制保存当前状态需手动调用serializeConfig()——但该函数触发文件系统写操作可能导致 LED 抖动并加速 flash 磨损只在 loop 中谨慎调用绝不在网络回调中调用。返回值语义readFromConfig()返回true表示设置页配置完整返回false则 WLED 会把默认值落盘使缺失项也在设置页可编辑。数值解析规则由设置页浏览器端行为决定含小数点的数字按 Cfloat解析6~7 位有效精度不支持 double不含小数点的数字按int32_t-2147483648 ~ 2147483647解析溢出截断后再次截断到你声明的 C 类型键名pin的字段单个整数或整数数组在设置页享受特殊处理引脚冲突标红、特殊引脚如仅输入引脚标黄告警官方建议使用int8_t存引脚值-1表示未配置。Flash 优化技巧官方提示参考usermod_v2_auto_save仓库中为 usermods/usermod_v2_auto_save通过复用 ArduinoJson 键名字符串节省 Flash。如需完全自定义布局的独立设置页则必须手动修改 HTML、xml.cpp与set.cpp——示例注释明确建议参考 WLED Soundreactive 分支的做法工作量大得多非必要不采用。四、注册机制REGISTER_USERMOD 与 UsermodManagerv2 模块如何被 WLED 主循环统一调度答案在 wled00/um_manager.cpp文件顶部通过DECLARE_DYNARRAY(Usermod*, usermods)声明一个动态数组零长度哨兵段 链接脚本排序机制由 pio-scripts/dynarray.py 支持。每个模块文件末尾的REGISTER_USERMOD(instance)宏把实例指针插入该数组因此多个 v2 模块可以在一次编译中共存——这正是 readme 推荐 v2 的核心理由。UsermodManager的每个静态方法都是对数组的线性遍历转发例如void UsermodManager::setup() { for (auto mod DYNARRAY_BEGIN(usermods); mod DYNARRAY_END(usermods); mod) (*mod)-setup(); } void UsermodManager::loop() { for (auto mod DYNARRAY_BEGIN(usermods); mod DYNARRAY_END(usermods); mod) (*mod)-loop(); }见 wled00/um_manager.cpp#L21-L75其中几个方法带有“首个处理者获胜”语义onMqttMessage()、onEspNowMessage()、onUdpPacket()一旦有模块返回true即停止分发handleButton()则聚合所有模块的返回值。lookup(uint16_t mod_id)按getId()查找模块支撑模块间协作示例第 65~78 行注释演示了如何用#ifdef USERMOD_EXAMPLElookup在两个 usermod 间交换状态。文件末尾还有一个精巧细节wled00/um_manager.cpp#L91-L99Usermod::oappend_shim静态指针实现了appendConfigData()无参重载到appendConfigData(Print dest)的桥接使模块代码里可以直接调用oappend(F(...))而无需显式传递输出流。五、构建集成custom_usermods 与编译校验README 级文档只说“把模块加入custom_usermods并编译”仓库源码则揭示了完整的解析与校验链路。5.1 声明方式在platformio.ini或自己的platformio_override.ini的目标环境里添加custom_usermods选项。仓库自身的用法示例platformio.ini[env:nodemcuv2] extends esp8266 board nodemcuv2 build_flags ${common.build_flags} ${esp8266.build_flags} -D WLED_RELEASE_NAME\ESP8266\ custom_usermods audioreactiveplatformio.ini#L108 处还定义了default_usermods audioreactive供各 ESP32 环境引用。批量测试 usermod 的开发者可以直接使用仓库提供的 usermods/platformio_override.usermods.ini它定义了usermods_esp32、usermods_esp32c3、usermods_esp32s2、usermods_esp32s3四个 16MB 大分区环境并把模块清单集中在[usermods]段的custom_usermods变量中注释标明该清单在 CI 中填充。5.2 解析规则pio-scripts/load_usermods.py该 pre 脚本把custom_usermods的每一行转成lib_deps条目支持三类写法裸模块名如audioreactive一行可写多个空格分隔find_usermod()按“原名 →原名_v2→usermod_v2_原名”三种目录命名依次匹配usermods/下的子目录命中后生成symlink://绝对路径依赖load_usermods.py#L13-L28。这解释了 usermods 目录中三种命名并存的由来。通配符*展开为usermods/下所有带library.json的子目录load_usermods.py#L128-L137。外部依赖URL、owner/Name 版本、Name spec等形式按lib_deps语法原样透传脚本还会尽力预测库名以便后续识别为 WLED 模块。对每个被识别为 usermod 的库脚本还会把wled00/源码目录加入其CPPPATH使模块能直接#include wled.h、为其追加-g调试信息供链接后校验使用并强制检查libArchive未被设置——缺失时直接报错退出ERROR: libArchivefalse is missing on usermod(s) name -- modules will not compile in correctly. Add build: {libArchive: false} to their library.json.这就是为什么每个 usermod 的library.json都必须形如 usermods/EXAMPLE/library.json{ name: EXAMPLE, build: { libArchive: false }, dependencies: {} }libArchive: false保证模块代码被直接链入最终可执行文件而非静态库否则REGISTER_USERMOD产生的注册符号可能被未引用而丢弃。5.3 链接后校验pio-scripts/validate_modules.pypost 脚本在 ELF 生成后做双重验证一是解析 map 文件中.dynarray.usermods.00000与.dynarray.usermods.99999哨兵段之间的地址跨度除以 4 字节指针大小得到实际注册的 usermod 实例数与DYNARRAY_LENGTH宏的语义一致二是用readelf --debug-dumpinfo读取顶层编译单元 DIE将各模块的源码路径与DW_AT_comp_dir/DW_AT_name匹配确认每个声明的 usermod 都真实编译进了二进制——有缺失即Exit(1)使构建失败。从源码结构看该校验专门针对 LTO 场景设计LTO 下 map 文件路径被 ltrans 分区替换直接数 section 出现次数不可靠。六、从示例到贡献一份可操作的检查清单结合 readme 约定与源码实现一个新 v2 usermod 的完整交付物应为usermods/描述性名称/目录内含library.jsonname与目录一致build: {libArchive: false}、readme.md功能说明、安装方式、依赖与引脚说明若改动了 WLED 主代码文件则必须写明改动步骤以及模块的.cpp/.h源码源码中类继承自Usermod只实现所需回调末尾以static 实例 REGISTER_USERMOD(实例)注册getId()对应const.h中申请的 ID在本地platformio_override.ini的对应环境中把目录名加入custom_usermods编译验证构建日志中应看到INFO: N libraries included as WLED optional/user modules与INFO: Code from usermod libraries found in binary: ...两行校验输出提交 Pull Request作为作者自行跟踪 WLED 版本升级并修复兼容性——这是 readme 明确的维护责任。此外官方对“普遍有用”的功能保留了并入基础代码的通道因此模块设计时应尽量保持依赖最小化library.json的dependencies精确声明第三方库、配置项走 v2 持久化接口这样才能被大多数用户环境直接采纳。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考