WLED 本地可视化控制终端

这是一个面向 WLED 灯效控制的本地可视化终端。它基于 ESP32-S3 和 LVGL 构建，配合 ST7789 彩色屏、编码旋钮和麦克风模块，在不打开 WLED 网页的情况下完成灯效选择、参数调整、状态查看和音乐律动。

原始工程发布在立创开源平台：wled-control-panel。项目协议为 CC BY-NC-SA 4.0，本文根据原工程信息整理为站内文章，完整设计资料、附件和图片请以原工程页面为准。

项目背景

WLED 的功能很强，但日常调灯时依赖网页入口并不总是顺手。灯效名称很多，参数也不少，如果只是想快速切换模式、调亮度或查看当前状态，拿起手机打开网页会打断使用体验。

这个项目的目标就是做一个放在灯旁边的实体控制面板：屏幕负责展示状态和效果预览，旋钮负责选择和调节，设备端直接与 WLED 功能结合，让灯效控制更接近“随手一拧”的体验。

核心能力

  • 首页显示当前时间、运行模式、调色板、亮度和电流等状态
  • 集成 WLED 原生灯效模式列表
  • 支持调节速度、亮度和调色板等参数
  • 为常用灯效提供 GIF 预览，降低只看名称选模式的记忆成本
  • 支持收藏和自定义模式展示
  • 提供 AP 模式、屏幕亮度、恢复出厂设置等设置项
  • 通过麦克风模块支持音乐律动效果

这些能力让控制面板不只是一个外接按键，而是一个带反馈、可浏览、能调参的本地 UI。

硬件与技术栈

项目使用 ESP32-S3-N16R8 作为主控，屏幕为 2.0 英寸 ST7789 彩色屏，图形界面由 LVGL 实现。输入部分使用带按键的编码旋钮，适合菜单切换、数值调整和确认操作。音频输入由麦克风模块完成，用于让灯效响应环境声音或音乐。

主要组成包括：

  • MCU：ESP32-S3-N16R8
  • 显示屏：2.0 英寸 ST7789
  • UI 框架：LVGL
  • 输入：编码旋钮按键
  • 音频：麦克风模块
  • 灯效对象：WLED / WS2812 类灯板或灯带

固件与烧录流程

原工程的源码托管在 Gitee：https://gitee.com/Callwang/wled。复刻时需要拉取源码，切换到 feature/custom-usermode-from-v0151 分支，并使用 VS Code + PlatformIO 打开工程。

烧录流程可以拆成两部分：

  1. 编译并烧录 WLED 固件。
  2. 使用乐鑫 Flash Download Tool 烧录字体库和 GIF 图片分区。

由于屏幕 UI 依赖字体和 GIF 资源，只烧录主固件后设备可能还不能完整运行。原工程中说明字体和 GIF 分区文件位于 usermods\usermod_v2_screen_knob\font_bin\，需要按 ESP32-S3 对应参数写入。完成烧录后，移除 IO0 与 GND 的短接，重新上电等待启动。

设备启动后可以通过手机连接 WLED AP 热点，再进入 WLED 配置页面设置 Wi-Fi、麦克风引脚、拾音功能和时间等选项。

结构与模型

原工程提供了 STEP 和 3MF 模型文件，便于继续调整外壳结构或直接切片打印。模型说明中建议第二盘使用透明耗材打印，其余部分使用黑色耗材，这样能兼顾灯效透光和整体外观。

这类带屏幕和旋钮的控制终端，结构上需要同时考虑屏幕开窗、旋钮手感、内部线缆长度、接口固定和后盖维护。原工程的模型与实物图可以作为装配参考。

已知问题

原工程记录了几个仍待优化的点：

  • 切换部分模式时 LED 灯板可能偶发闪烁，尤其是切到较大的 GIF 资源时。
  • 收藏模式里的 GIF 预览还不够准确，可能不会随当前选项变化。
  • 收藏列表遍历逻辑仍有性能问题，收藏较少时也可能遍历较大范围，导致切换到末尾后短暂卡顿。

这些问题并不影响理解项目方向，但复刻或二次开发时可以把它们作为优先优化点。

原始资料

最近更新:
Contributors: wyh