WLED stairway_wipe_basic 用户插件：用 U0/U1 接口驱动楼梯灯带 Wipe 效果

WLED stairway_wipe_basic 用户插件用 U0/U1 接口驱动楼梯灯带 Wipe 效果【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本文基于 WLED 仓库中 usermods/stairway_wipe_basic/readme.md 的原始说明结合 stairway_wipe_basic.cpp 源码逐段解析这个楼梯照明 v2 用户插件如何用 HTTP API 的U0/U1参数触发灯带逐段点亮Wipe、保持常亮或定时熄灭以及如何通过STAIRCASE_WIPE_OFF编译选项切换反向 Wipe 熄灭与渐隐熄灭两种关闭行为。读完后你将掌握该插件的完整行为状态机、编译启用方式build flag 与 PlatformIOcustom_usermods两种路径以及将其对接运动传感器等输入设备的改造思路。功能定位楼梯灯带照明该插件出自 usermods/stairway_wipe_basic 目录是一个基础的 v2 用户插件Usermod用于在楼梯侧面或台阶上安装灯带实现人走上楼时灯光逐级点亮的效果。原始 readme 的完整功能描述如下当userVar0变量被设置后LED 会以Wipe逐格扫过效果依次点亮通过把userVar0设为1或2分别控制两个方向对应 HTTP API 命令U01与U02Wipe 完成后灯要么以Solid常亮效果无限保持要么在userVar1秒后熄灭如果userVar0再次被更新例如第二个传感器被触发灯光会缓慢淡出直至熄灭readme 还指出这一行为可扩展为反向顺序的 Wipe 熄灭效果即STAIRCASE_WIPE_OFF选项见下文该版本是基础版通过 HTTP API 的U0、U1调用和/或宏macro实现readme 明确提示应该很容易改造该代码以对接运动传感器或其他输入设备。从源码结构看插件的类注释也说明了其用法前提把 usermod 拷贝到工程目录后注册当前仓库已改为REGISTER_USERMOD宏自动注册见后文。触发接口userVar0 / userVar1 与 HTTP APIreadme 给出的核心交互方式是两个用户变量其来源是 WLED 为 usermod 预留的全局变量。在 wled00/wled.h 中可以看到它们的声明WLED_GLOBAL uint16_t userVar0 _INIT(0), userVar1 _INIT(0); //available for use in usermod两个变量均为uint16_t取值范围 065535初始值为 0。WLED 的 v1 usermod 模板 wled00/usermod.cpp 中的注释也明确了对应关系Use userVar0 and userVar1 (API calls U0, U1, uint16_t)。各参数的语义与取值参数HTTP APIJSON 状态键语义userVar0U0user0触发方向与使能1 楼梯与控制器同侧检测到动作2 对侧检测到动作0 无动作userVar1U1user1常亮保持时长秒。为 0 时灯将保持常亮直到另一个 PIR 触发或外部命令HTTP 请求参数的解析路径在 wled00/set.cpp 中形如userVar0 getNumVal(req, pos)即 URL 中的U0查询参数直接写入该全局变量。插件自身则在readFromJsonState中同步 JSON 状态void readFromJsonState(JsonObject root) { userVar0 root[user0] | userVar0; //if user0 key exists in JSON, update, else keep old value }这意味着除了 HTTP GET 参数任何向/json发送{state: {user0: 1}}的客户端包括 MQTT 桥接、宏都能触发同样的逻辑。|运算符的语义是键存在则更新否则保留旧值保证非本插件的状态更新不会误清触发值。readme 强调这是basic 版本真实部署中典型做法是楼梯上下各装一个 PIR 运动传感器传感器触发时向 WLED 发U01/U02可由 HTTP 宏、MQTT 或第三方脚本完成人离开后灯按U1设定的秒数自动熄灭。行为状态机源码级逐段解析插件的核心是一个 5 态状态机wipeState0 空闲、1 点亮 Wipe 中、2 常亮保持、3 准备关闭、4 反向 Wipe 熄灭中全部逻辑位于 stairway_wipe_basic.cpp 的loop()中。触发与方向判断L34–L39if (userVar0 0) { if ((previousUserVar0 1 userVar0 2) || (previousUserVar0 2 userVar0 1)) wipeState 3; //turn off if other PIR triggered previousUserVar0 userVar0; if (wipeState 0) { startWipe(); wipeState 1; }要点只有当方向发生翻转1→2 或 2→1时才直接进入关闭流程wipeState 3。这正是 readme 所说userVar0 is updated (e.g. by triggering a second sensor) the light will fade slowly until its off 的实现首次触发wipeState 0调用startWipe()进入点亮流程。startWipe()切换到 Wipe 效果L93–L107void startWipe() { bri briLast; //turn on jsonTransitionOnce true; strip.setTransition(0); //no transition effectCurrent FX_MODE_COLOR_WIPE; strip.resetTimebase(); //make sure wipe starts from beginning //set wipe direction Segment seg strip.getSegment(0); bool doReverse (userVar0 2); seg.setOption(1, doReverse); colorUpdated(CALL_MODE_NOTIFICATION); }实现上有几个值得注意的细节亮度恢复bri briLast把亮度恢复为上次非零亮度避免用户之前手动调暗后触发失效禁用过渡strip.setTransition(0)配合jsonTransitionOnce让 Wipe 起始帧不受全局渐变fade干扰strip.resetTimebase()确保扫光从灯带起点开始而不是从中途开始方向控制把 WLED 内建的FX_MODE_COLOR_WIPE彩色 Wipe 效果作为载体并通过**段 0 的选项 1reverse 标志**决定扫描方向——userVar0 2时反向对应 readme 中Both directions are supported by setting userVar0 to 1 and 2colorUpdated(CALL_MODE_NOTIFICATION)通知核心刷新灯效CALL_MODE_NOTIFICATION表示这是插件发起的变更而非网络请求。点亮时长与完成判定L42–L49} else if (wipeState 1) { //wiping uint32_t cycleTime 360 (255 - effectSpeed)*75; //this is how long one wipe takes if (millis() strip.timebase (cycleTime - 25)) { //wipe complete effectCurrent FX_MODE_STATIC; timeStaticStart millis(); colorUpdated(CALL_MODE_NOTIFICATION); wipeState 2; } }Wipe 的总时长由效果速度effectSpeed0255决定cycleTime 360 (255 - effectSpeed) × 75 毫秒effectSpeedWipe 一次时长0最慢360 255×75 19485 ms约 19.5 秒255最快360 ms也就是说用户可以直接用 WLED 常规的状态设置speed参数来控制楼梯灯光扫完的速度。完成判定预留了 25 ms 余量源码注释minus 25 ms to make sure we switch in time保证在 Wipe 动画结束前就切到常亮完成后效果切换为FX_MODE_STATICreadme 所称的 Solid effect。常亮保持与定时熄灭L50–L54} else if (wipeState 2) { //static if (userVar1 0) //if U1 is not set, the light will stay on until second PIR or external command is triggered { if (millis() - timeStaticStart userVar1*1000) wipeState 3; } }与 readme 描述一致userVar1 0时灯在常亮userVar1秒后进入关闭流程userVar1 0则无限保持直到方向翻转或外部再次置位。关闭流程反向 Wipe 与渐隐两种模式L55–L78} else if (wipeState 3) { //switch to wipe off #ifdef STAIRCASE_WIPE_OFF effectCurrent FX_MODE_COLOR_WIPE; strip.timebase 360 (255 - effectSpeed)*75 - millis(); //make sure wipe starts fully lit colorUpdated(CALL_MODE_NOTIFICATION); wipeState 4; #else turnOff(); #endif } else { //wiping off if (millis() strip.timebase (725 (255 - effectSpeed)*150)) turnOff(); //wipe complete }这是 readme 中-D STAIRCASE_WIPE_OFF配置项Have the LEDs wipe off instead of fading out的完整实现定义该宏时进入wipeState 4复用FX_MODE_COLOR_WIPE做一次反向扫光熄灭并把strip.timebase人为回拨使扫光看起来从全亮状态开始即从尾端向头端逐格熄灭。该反向 Wipe 的时长公式为725 (255 - effectSpeed) × 150ms比点亮方向慢一倍系数未定义该宏时默认直接调用turnOff()走渐隐路径void turnOff() { jsonTransitionOnce true; #ifdef STAIRCASE_WIPE_OFF strip.setTransition(0); //turn off immediately after wipe completed #else strip.setTransition(4000); //fade out slowly #endif bri 0; stateUpdated(CALL_MODE_NOTIFICATION); wipeState 0; userVar0 0; previousUserVar0 0; }默认模式下熄灭走4000 ms 的渐变过渡readme 所称 fade slowly until its off。两种模式下turnOff()都会把bri清零、复位状态机并清空userVar0为下一次触发做好准备。另外loop()的else分支userVar0 0负责在触发值被外部清零时复位状态机并在曾亮灯的情况下执行同样的关闭逻辑——即外部系统直接发U00也能关灯。编译启用build flag 与当前构建系统readme 的 Install 章节原文是Add the buildflag-D USERMOD_STAIRCASE_WIPEto your environment to activate it.并给出唯一的配置项-D STAIRCASE_WIPE_OFF—— Have the LEDs wipe off instead of fading out在源码中可以看到STAIRCASE_WIPE_OFF的定义被有意移出了 .cpp 文件//moved to buildflag //comment this out if you want the turn off effect to be just fading out instead of reverse wipe //#define STAIRCASE_WIPE_OFF即默认渐隐如需反向 Wipe 熄灭在编译环境中添加-D STAIRCASE_WIPE_OFF。当前仓库的实际启用方式需要注意适用前提当前源码文件中并没有USERMOD_STAIRCASE_WIPE宏守卫说明 readme 中的 buildflag 写法对应的是早期usermods 按头文件手工包含的旧机制。当前仓库采用的是 PlatformIO custom_usermods的模块化构建platformio.ini 中提供了全局custom_usermods选项如common段的custom_usermods 各环境可用custom_usermods stairway_wipe_basic声明要编入的 usermod构建脚本 pio-scripts/load_usermods.py 在配置阶段解析该选项把每个 usermod 目录解析为symlink://本地库并追加到lib_deps*通配符则展开为 usermods 目录下所有含library.json的插件例如ESP32_USERMODS环境使用custom_usermods *插件 library.json 必须满足构建脚本的硬性检查{ name: stairway_wipe_basic, build: { libArchive: false } }libArchive: false是强制项——load_usermods.py 会检查每个 usermod 的库档案设置缺失即报错退出libArchivefalse is missing on usermod(s) ... modules will not compile in correctly。这是因为 v2 usermod 依赖链接器段REGISTER_USERMOD宏生成的动态数组注册必须以目标文件而非静态库的形式参与最终链接。注册机制插件末尾两行完成自我注册static StairwayWipeUsermod stairway_wipe_basic; REGISTER_USERMOD(stairway_wipe_basic);REGISTER_USERMOD是 wled00/dynarray.h 提供的宏把实例指针放入链接器排序的dtors段数组运行时由 wled00/um_manager.cpp 中的UsermodManager统一驱动setup()在开机时遍历调用、loop()在主循环中逐个调用每个 usermod 的loop()——楼梯插件全部逻辑就运行在这条每周期回调里。此外addToJsonState/readFromJsonState也由管理器在 JSON 状态收发时统一分发um_manager.cpp因此user0/user1才能进入/json与/json/state状态机。插件 ID 定义在 wled00/const.hUSERMOD_ID_STAIRWAY_WIPE 44会在/json/info的um数组中出现便于前端确认插件已编入固件。典型部署与传感器对接结合 readme 与源码一个完整的楼梯照明部署链路是灯带沿楼梯安装WLED 控制灯带建议使用第 0 段承载 Wipe方向由U0决定楼梯上下各一个 PIR 传感器通过任意方式HTTP 宏、MQTT、ESP-NOW 或脚本在检测到动作时发送U01/U02U1设置离人后保持常亮的秒数例如U115表示 15 秒人在对面 PIR 下出现方向翻转时灯立即进入渐隐或定义了STAIRCASE_WIPE_OFF时进入反向 Wipe熄灭流程用speed参数调节 Wipe 快慢effectSpeed越高扫得越快360 ms 约 19.5 s。readme 的最后一段提示了扩展方向It should be easy to adapt this code to interface with motion sensors or other input devices. 由于触发完全依赖全局的userVar0/userVar1扩展时只需在setup()中初始化 GPIO/传感器、在loop()中把传感器读数写入这两个变量状态机部分可以原样复用v2 用户插件基类还提供了handleButton、onStateChange等钩子见 wled00/um_manager.cpp 的分发逻辑可作为进一步集成的入口。小结stairway_wipe_basic 是 WLED 用户插件体系中一个麻雀虽小五脏俱全的范例它仅靠两个 usermod 全局变量U0/U1和 WLED 内建的 Color Wipe / Static 效果就实现了一个带方向判断、定时熄灭和双模式关闭行为的楼梯照明控制器。阅读 stairway_wipe_basic.cpp 约 130 行代码可以理解 WLED v2 usermod 的标准生命周期setup/loop/JSON 状态读写、REGISTER_USERMOD自动注册、custom_usermods构建集成以及插件与核心状态机亮度、过渡、效果切换协作的典型手法。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考