WLED usermod_v2_auto_save 实战自动保存 LED 设置并开机恢复预设【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLEDWLED 的usermod_v2_auto_save是一个轻量级 Usermod当亮度、效果速度、强度、模式或调色板发生变化后它会在一段静置延迟后将当前状态自动写入指定编号的预设并可选择在开机时恢复该预设从而把 LED 状态持久化到 Flash 中。读完本文你将理解它的触发机制与防抖逻辑、编译期宏与运行时配置两套参数体系以及如何在 PlatformIO 构建中正确启用并验证该模块。核心行为变化检测、静置窗口与预设写入Auto Save 监控主灯段main segment的五个状态量任意一项发生变化都会重置计时器亮度bri效果速度effectSpeed效果强度effectIntensity效果模式strip.getMainSegment().mode调色板strip.getMainSegment().palette关键语义在于settle静置机制任何一次新的变化都会把保存时间点向后推延AUTOSAVE_AFTER_SEC秒只有当连续这么久没有任何受监控的变化发生时才会真正执行一次保存。从源码 usermod_v2_auto_save.cpp 的loop()可以看到实现方式每个 tick 用knownBrightness/knownEffectSpeed/knownEffectIntensity/knownMode/knownPalette五个缓存值与全局状态比对任一不同则更新缓存并令autoSaveAfter now autoSaveAfterSec*1000当now autoSaveAfter时调用saveSettings()并清零计时。保存动作本身由saveSettings()完成L79-L88包含三步通过updateLocalTime()获取本地时间按~ MM-DD HH:MM:SS ~格式生成预设名称cacheInvalidate强制 WLED 重载预设缓存因为预设文件已变更调用savePreset(autoSavePreset, presetNameBuffer)把当前状态写入指定预设编号。两个容易忽略的实现细节预设编号范围被钳制在 100250readFromConfig()中对autoSavePreset执行了min(250, max(100, ...))边界检查L261因此即使误配 99 或 251 也不会越界而是被静默钳到边界值。这也是为什么编译宏AUTOSAVE_PRESET_NUM未定义时默认取 250最后一个合法预设号。效果正在刷新时有 240ms 的节流loop()首行返回条件中包含(strip.isUpdating() now - lastRun 240)即灯带正在执行效果刷新时两次状态采样之间至少间隔 240ms避免在动画密集刷新期间做无意义的重复比对。另一个默认行为是autoSaveIgnorePresets true当你原封不动地应用了某个现有预设currentPreset 0时不会触发自动保存避免把同一个预设重复复制一份到自动保存槽位将该项设为false可关闭该逻辑。开机恢复预设setup() 中的 applyPreset若启用了开机恢复Usermod 在setup()中直接执行applyPreset(autoSavePreset)L107-L120随后立即用当前bri、effectSpeed等值初始化五个known*基准值——这一步保证了开机恢复本身不会被误判为一次用户变更。readme 中有一条重要的行为说明WLED 本身在开机自动应用预设时并不尊重预设中保存的亮度值。因此 Auto Save 选择在启动阶段显式地applyPreset()以确保亮度也被真正恢复。副作用是安装了该 Usermod并开启开机应用后WLED 的默认亮度和开机应用预设 N两项原生启动行为实际上会被它接管/覆盖——这是设计预期而非缺陷。开机恢复由编译宏USERMOD_AUTO_SAVE_ON_BOOT控制默认值未定义时默认false并可通过运行时配置applyAutoSaveOnBoot覆盖见下文。两套参数体系编译宏 vs 运行时配置该 Usermod 同时支持编译期默认值C 宏和运行时持久配置cfg.json 中的um对象二者叠加的优先级是cfg.json 中已保存的值 编译宏 代码内置默认。编译期宏build flags宏作用未定义时的代码默认值USERMOD_AUTO_SAVE使本 Usermod 纳入构建配合custom_usermods auto_save模块不参与构建AUTOSAVE_AFTER_SEC静置秒数即最后一次变化后多久执行保存15L38-L42AUTOSAVE_PRESET_NUM自动保存所用的预设编号250USERMOD_AUTO_SAVE_ON_BOOT是否在开机时应用自动保存的预设falseUSERMOD_FOUR_LINE_DISPLAY若同时安装 Four Line Display则保存成功后在其屏幕上弹出 Settings / Auto Saved 提示无提示注意 readme 提到AUTOSAVE_AFTER_SEC设为0的语义loop()的首个短路条件!autoSaveAfterSec表明0 秒表示彻底禁用自动保存而不是立即保存。运行时配置Usermods 设置页 / cfg.jsonaddToConfig()与readFromConfig()L227-L269把一组参数持久化到cfg.json的umusermod对象下键名为Autosave{ um: { Autosave: { enabled: true, autoSaveAfterSec: 10, autoSavePreset: 250, applyAutoSaveOnBoot: true, autoSaveIgnorePresets: true } } }这些字段可以通过 Web UI 的 Usermods 设置页修改并持久化。读取时带有边界钳制autoSaveAfterSec被限制在[10, 3600]秒autoSavePreset被限制在[100, 250]。也就是说即便通过 JSON API 强行写入越界值设备端也会自动纠正到合法区间。JSON API 集成信息区开关按钮与状态回读该 Usermod 还接入了 WLED 的 JSON API/json/infoaddToJsonInfo()L168-L185在 info 的u对象下注入一个名为Autosave的条目其值是一段内联 HTML 按钮。点击按钮会发出requestJson({Autosave:{enabled:false}})当前启用时点击即禁用按钮上的图标随之在on/off间切换。这意味着无需进入设置页即可从 UI 信息面板快速开关自动保存。/json/statereadFromJsonState()L198-L211回读Autosave.enabled字段兼容布尔与off/on字符串两种表示。函数首行if (!initDone) return;是一个防护在setup()完成前收到 JSON 状态包时直接忽略避免启动阶段调用applyPreset()造成崩溃。与 Four Line Display 的联动AutoSaveUsermod本身是独立模块但源码在setup()中通过UsermodManager::lookup(USERMOD_ID_FOUR_LINE_DISP)探测 Four Line DisplayL108-L112。若能找到displayOverlay()会在每次成功保存后唤醒屏幕并显示 1.5 秒的 Settings / Auto Saved 提示。此联动仅在定义了USERMOD_FOUR_LINE_DISPLAY时编译进固件对应的展示模块可参考 usermod_v2_four_line_display_ALT。安装与构建配置步骤复制并修改platformio_override.inireadme 建议从 Rotary Encoder UI 的 usermod 目录复制 platformio_override.ini.sample 作为起点放在与 platformio.ini 相同的目录仓库根目录。该文件中的环境定义板型、分区表等可按自己的硬件裁剪。注册模块并添加宏。在 override 文件的build_flags中追加platformio_override.sample.ini 第 108-110 行给出了官方示例写法custom_usermods ${env:esp32dev.custom_usermods} auto_save ; build_flags 追加: ; -D AUTOSAVE_AFTER_SEC90 ; -D AUTOSAVE_PRESET_NUM100 ; -D USERMOD_AUTO_SAVE_ON_BOOTtrue注意仓库的构建脚本 load_usermods.py 会解析custom_usermods字段把auto_save解析为usermods/usermod_v2_auto_save目录脚本支持去掉usermod_v2_前缀匹配并以symlink://方式注入lib_deps。因此模块目录名与注册名不需要完全一致。确保libArchive: falselibrary.json 已声明build: { libArchive: false }这是 WLED 构建系统强制的要求Usermod 必须直接链接进可执行文件构建脚本会检测并报错退出。无需额外第三方库本模块自身没有特殊 PlatformIO 依赖只有当同时安装 Four Line Display 时才需要U8g2和Wire。模块标识getId()返回USERMOD_ID_AUTO_SAVE其值为9定义于 const.h。该 ID 供其他模块如 Four Line Display通过UsermodManager::lookup()反查本模块是否安装也是 pin_manager.h 中注释Does not allocate pins的来源——Auto Save 是纯逻辑模块不占用任何 GPIO。验证与行为检查清单安装并刷入固件后可按以下路径验证Web UI 信息面板info 页应出现 Autosave 条目及开关按钮连续调整亮度/模式/调色板停止操作超过autoSaveAfterSec秒注意任何一次新调整都会重新计时后预设autoSavePreset应更新为~ MM-DD HH:MM:SS ~命名的条目若安装了 Four Line Display保存瞬间屏幕应有 Auto Saved 提示重启设备后若applyAutoSaveOnBoot为真LED 应呈现自动保存的亮度、效果与调色板应用一个未修改过的现有预设不应触发保存autoSaveIgnorePresets默认行为。变更历史与适用前提readme 记录的演进为2021-02 首次公开发布2021-04 适配运行时配置即本文所述的 cfg.json/Usermods 设置页机制对应源码中readFromConfig/addToConfig/readFromJsonState的完整实现。适用前提说明本文所有结论基于当前仓库源码usermod_v2_auto_save.cpp与 readmereadme 中开机时于第一次loop()加载预设的表述在现行源码中实际由setup()阶段完成二者行为等价均在主循环驱动前生效。预设编号 100250、静置时间 103600 秒为当前源码中的硬边界若未来版本放宽范围以届时readFromConfig()中的钳制逻辑为准。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考