WLED Animated Staircase Usermod 实战指南基于 PIR / 超声波传感器的楼梯感应动画灯控【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本文以 WLED 官方仓库中的Animated_Staircase用户模块Usermod为核心系统讲解如何通过 PIR 人体红外或 HC-SR04 超声波传感器实现人走灯亮、灯随人行的楼梯动画效果灯光沿行走方向逐级点亮并沿最后一次运动方向逐级熄灭即使多人同时上下楼梯也能优雅处理。读完本文你将掌握该 Usermod 的编译集成、硬件接线、WLED 段Segment配置、JSON API 与 MQTT 远程控制以及核心源码的工作原理可直接复现一套可运行的智能楼梯灯方案。一、功能概览楼梯灯光如何跟着人走该 Usermod 的核心实现在 usermods/Animated_Staircase/Animated_Staircase.cpp它通过在楼梯顶端与底端各安装一个传感器PIR 红外传感器或超声波传感器实现方向识别检测到楼梯下方有人时动画自下而上逐级点亮检测到上方有人时动画自上而下点亮智能熄灭熄灭时沿最后一次检测到运动的方向逐级关闭让灯光始终在人身后熄灭多人在梯即使在动画运行期间传感器再次触发也会立即切换方向重新点亮可平滑处理楼梯上同时有多人的情况可配置性点亮速度每级台阶的切换间隔、亮灯持续时间、传感器检测距离等均可在运行时调整并通过 WLED JSON API 远程控制。从源码结构看动画引擎由三个核心成员变量驱动Animated_Staircase.cpponIndex/offIndex一对游标标记当前点亮的段范围二者之间的所有 Segment 处于点亮状态swipe当前扫描方向SWIPE_UP 自下而上SWIPE_DOWN 自上而下lastSensor最后一次触发的是哪个传感器LOWER 底部UPPER 顶部用于决定熄灭时的方向。每次点亮/熄灭其实就是把这对游标按segment_delay_ms间隔逐步移动从而形成波浪式扫过的视觉效果。二、编译集成把 Usermod 编译进固件要使用本 Usermod需要具备从源码编译 WLED 的能力。仓库中已内置该模块usermods/Animated_Staircase/library.json模块名为Animated_Staircase因此只需在构建配置中声明启用即可。复制仓库根目录的 platformio_override.sample.ini 为platformio_override.ini若已存在则直接编辑在你使用的构建环境[env:xxx]中加入一行custom_usermods ${env:esp32dev.custom_usermods} Animated_Staircasecustom_usermods是独立的配置键不属于build_flags多个模块用空格分隔模块名对应其library.json中的name字段参见 platformio_override.sample.ini 中的注释说明重新编译并烧录固件。编译过程由 pio-scripts/load_usermods.py 驱动它会解析custom_usermods中的模块名在usermods/目录下定位同名文件夹并以symlink://方式将其加入lib_deps同时校验每个模块的library.json必须声明build: {libArchive: false}防止模块被静态归档而导致链接失败。仓库还提供了专门的构建环境[env:usermods]platformio.ini使用custom_usermods *通配符一次性编译usermods/目录下所有模块适合快速验证。三、硬件安装接线与供电官方 READMEusermods/Animated_Staircase/README.md给出了如下硬件安装步骤在每级台阶上粘贴一条 LED 灯带将 ESP8266 的D4引脚或 ESP32 的D2引脚接到最底层台阶第一条灯带的数据输入端将每一级台阶灯带的>{ state: { staircase: { enabled: true, bottom-sensor: false, top-sensor: false } } }设置项说明默认值enabled启用或停用本 Usermodtruebottom-sensor通过 API 手动触发一次自下而上动画falsetop-sensor通过 API 手动触发一次自上而下动画false以下示例使用curl向 WLED JSON API 发送 HTTP POST若在 Windows 下使用 curl请把续行符\替换为^或直接写成一行启用/停用 Usermod停用后灯光将不再受传感器活动影响可自由把玩灯光而不被 Usermod 自动开关打断curl -X POST -H Content-Type: application/json \ -d {staircase:{enabled:false}} \ xxx.xxx.xxx.xxx/json/state恢复启用时将enabled改回true即可。通过 API 手动触发动画模拟底部传感器触发自下而上点亮curl -X POST -H Content-Type: application/json \ -d {staircase:{bottom-sensor:true}} \ xxx.xxx.xxx.xxx/json/state模拟顶部传感器触发自上而下点亮curl -X POST -H Content-Type: application/json \ -d {staircase:{top-sensor:true}} \ xxx.xxx.xxx.xxx/json/state这两个字段同时承担读与写两种角色writeSensorsToJson()把传感器实时状态写入staircase对象暴露给 APIreadSensorsFromJson()则把 API 写入的true合并进传感器状态源码 Animated_Staircase.cpp从而在无实体传感器时也可用于演示和测试。Mqtt 订阅主题的处理也复用了同一机制收到up/down时分别置位bottomSensorWrite/topSensorWriteAnimated_Staircase.cpp。六、MQTT 控制与状态上报除 JSON API 外Usermod 还支持通过 MQTT 控制前提是固件未定义WLED_DISABLE_MQTT在设备主题默认形如wled/MAC后6位见 wled.cpp下订阅/swipe主题发布up触发自下而上的点亮动画发布down触发自上而下的点亮动画发布on/off启用 / 停用 Usermod。订阅动作在onMqttConnect()中完成Animated_Staircase.cpp收到消息后由onMqttMessage()处理。传感器状态变化时会发布到设备主题/motion/0|1其中0代表底部bottom传感器、1代表顶部top传感器载荷为on/offAnimated_Staircase.cpp。这与 WLED 内置的 PIR 按钮类型BTN_TYPE_PIR_SENSOR发布.../motion/buttonId的约定一致见 button.cpp便于在 MQTT 平台如 Home Assistant中统一订阅/motion/通配符获取楼梯占用状态。七、Usermod 设置页参数详解编译并烧录后进入 WLED 界面的Config → Usermod设置页对应 wled00/data/settings_um.htm。该页面会读取/json/cfg中的um配置为每个已安装 Usermod 自动生成表单字段——因此本节参数无需手写配置文件直接在页面上填写保存即可之后可再次从 API 的配置区读取验证。结合源码addToConfig()/readFromConfig()中的字段定义与取值范围约束Animated_Staircase.cpp各参数说明如下设置字段含义默认值源码约束enabled启用本 Usermodfalse源码默认README 表中 API 显示为true以实际保存值为准布尔segment-delay-ms相邻两级台阶点亮的间隔时间150ms10 ~ 10000 ms即最快 10ms、最慢 10son-time-s最后一次触发后灯光保持点亮的时间30s10 ~ 900 s10 秒到 15 分钟保存时自动换算为毫秒useTopUltrasoundSensor/useBottomUltrasoundSensor顶部 / 底部使用超声波传感器关 使用 PIRfalse布尔topPIRorTrigger_pin/bottomPIRorTrigger_pinPIR 信号脚或超声波 trigger 脚-1禁用GPIO 编号-1 表示禁用topEcho_pin/bottomEcho_pin超声波 echo 脚PIR 模式填-1-1GPIO 编号topPIRorTrigger_pin_invert/bottomPIRorTrigger_pin_invert传感器电平取反适配低电平触发的传感器false布尔top-dist-cm/bottom-dist-cm顶部 / 底部超声波最大检测距离50cm30 ~ 150 cmPIR 模式下无需填写toggle-on-off动画启动/结束时同时联动 WLED 主电源开关false布尔适合配合继电器/主电源控制其中几个参数的底层逻辑距离 → 回波时间的换算源码将厘米数乘以系数59得到微秒超时bottomMaxDist*59Animated_Staircase.cpp。这来自超声波往返测距公式按 20°C 声速 343 m/s距离(cm) (0.0343 × 超时µs) / 2反推可得 5cm ≈ 292µs、50cm ≈ 2915µs、100cm ≈ 5831µs源码注释中附有完整对照表Animated_Staircase.cpp。检测到回波即判定有人超时则判定无人。HC-SR04 的时序代价pulseIn()是阻塞等待特别是检测远距离回波时会在 WLED 主循环中造成延迟可能让动画出现轻微顿挫、或网页界面响应变慢。因此检测距离尽量设短源码上限 150cm只覆盖传感器正前方一小段即可。引脚冲突防护四个引脚顶部 trigger/echo、底部 trigger/echo通过PinManager::allocateMultiplePins()统一分配所有者标识为UM_AnimatedStaircase对应USERMOD_ID_ANIMATED_STAIRCASE 14见 const.h 与 pin_manager.h若分配失败例如与其他模块冲突Usermod 会回退为禁用状态并在设置页中通过下拉框把已被占用的 GPIO 置灰避免重复占用。八、源码核心流程解析理解以下三个函数即可掌握整个模块的运行逻辑均在 Animated_Staircase.cpp 内1. 传感器轮询checkSensors()以scanDelay 100ms为周期轮询两路传感器PIR 直接读电平、超声波走ultrasoundRead()。当检测到任一传感器状态翻转时记录lastSwitchTime若当前处于熄灭状态则按触发来源设置swipe方向并令on true开始点亮若已点亮则只更新lastSensor用于决定稍后熄灭的方向Animated_Staircase.cpp。2. 自动熄灭autoPowerOff()若距离最后一次传感器触发已超过on_time_ms且两路传感器当前都无触发防止人仍在楼梯上时熄灯则以lastSensor作为熄灭方向启动沿原路熄灭流程Animated_Staircase.cpp。3. 扫光推进updateSwipe()每经过segment_delay_ms移动一次onIndex/offIndex点亮阶段两者向两侧扩张onIndex向段首、offIndex向段尾熄灭阶段按方向收缩每次变化只更新必要的段随后调用updateSegments()设置各段SEG_OPTION_ON并触发strip.trigger()刷新Animated_Staircase.cpp。启用时还会把全局过渡时间transitionDelay同步为segment_delay_ms保证段间渐变平滑衔接Animated_Staircase.cpp。此外模块在addToJsonInfo()中会向 WLED Web UI 的 Info 页注入一个开关按钮staircase区块点击即可通过 JSON API 快速启用/停用无需进入设置页。九、注意事项与使用建议HC-SR04 阻塞延迟正如 README 与源码注释反复强调超声波回波等待会占用主循环距离越长延迟越明显150cm 上限约 9ms 量级。若动画出现顿挫或 Web 响应变慢优先缩短检测距离或改用 PIR 传感器。供电设计每级台阶独立供电并用粗线≥AWG14 / 2.5mm²接入避免串接供电导致的压降数据线仍按级间串联接法组成一条虚拟灯带。引脚复用选择传感器 GPIO 时避开 WLED 已用引脚如默认数据脚、按钮、继电器等Usermod 设置页的引脚下拉框会标记占用情况也可参考PinManager的所有者记录。开机自启务必把保存好的 Segment 预设设为开机应用预设否则重启后段划分丢失动画可能作用于整条灯带而非逐级台阶。至此从编译集成、硬件安装、Segment 划分到 JSON API / MQTT 控制与源码原理一条基于 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），仅供参考