基于 LVGL 的 WLED 本地可视化控制终端

无需网页，一颗旋钮即可掌控所有灯效

 

项目背景

WLED 本身功能非常强大，但在日常使用中仍然存在一些不够“顺手”的地方：

• 每次调灯效都要打开网页
• 模式名称多，记忆成本高
• 无法直观看到不同模式的实际效果

因此这个项目的目标很明确：
做一个真正“本地化、可视化、即拿即用”的 WLED 控制终端。

项目简介

这是一个基于 LVGL 的 WLED 本地控制界面，
通过 ST7789 彩色屏幕 + 编码旋钮 + 麦克风模块，
实现对 WLED 灯效的完整控制与实时反馈。

无需手机、无需网页，
在设备端即可完成模式选择、参数调节与状态查看。

B站视频：https://www.bilibili.com/video/BV1gcvkBxEZ4

WLDE官方地址：https://kno.wled.ge/

已实现功能

1️⃣ 主页状态展示

• • 当前时间
  • 当前运行模式
  • 调色板（Palette）
  • 亮度、电流等运行状态

2️⃣ WLED 内置模式列表

• • 完整集成 WLED 原生模式
  • 支持参数调节：
    • 变换速度（Speed）
    • 亮度（Brightness）
    • 调色板（Palette）
  • 参数修改即时生效

3️⃣ 模式效果 GIF 预览

• • 为常见 WLED 模式内置效果动画
  • 选择模式时即可直观看到灯效表现
  • 不再依赖“猜名字选效果”

4️⃣ 收藏 / 自定义模式

• • 支持展示收藏的常用模式
  • 模式名称支持 常见 3500 个中文字符

5️⃣ 设置页面

• • AP 模式开关
  • 屏幕亮度设置
  • 恢复出厂设置

6️⃣ 音乐律动

• • 内置麦克风模块
  • 灯效可随环境声音或音乐变化

项目亮点

• 完全脱离 WLED Web 页面
• 本地 UI，响应速度快、稳定性高
• 模式效果可视化（GIF 预览）
• 优秀的中文显示支持

硬件与技术栈

• MCU：ESP32-S3-N16R8
• 显示屏：2.0 英寸 ST7789
• UI 框架：LVGL
• 输入设备：编码旋钮按键
• 音频输入：麦克风模块

材料清单(除BOM表以外的)

• 屏幕：https://item.taobao.com/item.htm?id=908017501076&mi_id=00009gUeGnRg0miZQwMSkImv1_V8_iDBawTK7xtk_IPLExo&spm=tbpc.boughtlist.suborder_itemtitle.1.1d1a2e8dQcLuAp
• 编码旋钮按键：https://item.taobao.com/item.htm?id=950058669876&mi_id=0000PNinGXehCjU98OMz3f08HbOxR76y4hA0FQDko8Ul6EQ&spm=tbpc.boughtlist.suborder_itemtitle.1.1d1a2e8dQcLuAp
• 磁吸接口（3Pin公母座2.54PH-线长100mm）：https://item.taobao.com/item.htm?id=956103119158&mi_id=0000zKnSmSpBPVBWh6AvAnHso7mhI_40ph-m7CT9qJ-J4SE&spm=tbpc.boughtlist.suborder_itemtitle.1.1d1a2e8dQcLuAp
• 连接线（1.25mm 端子线5P和8P，长度8cm左右，可以长不能短 ）：https://detail.tmall.com/item.htm?id=624732974819&mi_id=0000CkueLWSXuWg0gegsJFhjdeuqiIQ8SmSuo2ya9ZydjUw&spm=tbpc.boughtlist.suborder_itemtitle.1.1d1a2e8dQcLuAp
• 螺丝(M2*5 头3.5)：https://detail.tmall.com/item.htm?id=640551005750&mi_id=00002G5zHzPZlUSmggCx4uSm0kxkRvqfEcFIz6YjAMZWAGk&spm=tbpc.boughtlist.suborder_itemtitle.1.1d1a2e8dQcLuAp
• LED灯板（可选  65cm * 65cm  64位 WS2812 5050 RGB LED）：https://item.taobao.com/item.htm?id=584359388330&mi_id=0000pGAsnFr6r4Cmkqy0Ad0cDiL8mM3BjXetWUIMMTl4_58&spm=tbpc.boughtlist.suborder_itemtitle.1.1d1a2e8dQcLuAp
• 屏幕和按键端子接口(可选 XH2.54 8P和5P 立贴)：https://item.taobao.com/item.htm?id=553190289846&mi_id=0000orJzZlclI21IFva0Up8TO05aPofolCRGLgsbsa-kLBs&spm=tbpc.boughtlist.suborder_itemtitle.1.1d1a2e8dQcLuAp

烧录固件

• 源代码：https://gitee.com/Callwang/wled
• 固件烧录说明：
  • 从仓库拉取代码 git clone git@gitee.com:Callwang/wled.git
  • 切换到feature/custom-usermode-from-v0151 分支 git checkout feature/custom-usermode-from-v0151
  • 使用vscode打开(要安装好PlatformIO插件)
  • 将根目录下的platformio_override.bak.ini重命名为platformio_override.ini
  • 
  • 连接设备，使用带有USB TO TTL工具连接设备，同时短接IO0和GND,如下图所示
  • 
  • 连接好设备，开始构建和烧录
  • 如下图所示，烧录成功，目前由于没有烧录字体和GIF图片，还无法正常运行。
  • 烧录字体库和GIF图片分区，分区文件在项目下的usermods\usermod_v2_screen_knob\font_bin\中
  • 使用乐鑫的官方烧录工具烧录，Chip Type选择ESP32-S3，烧录工具下载地址：https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/production_stage/tools/flash_download_tool.html
  • 
  • 按照以下填写对应的参数，注意COM要选在自己的，不同的电脑会不一样。
  • 
  • 烧录spiffs.bin成功的图示
  • 
  • 完成后去除IO0和GND短接和串口线，使用USB口接通电源(至少5V，1A)，等待启动，启动比较慢，一分钟左右，如果时间较长可能是烧录有问题可以接串口日志看下。
  • 启动成功后可以通过手机搜索WLED的AP热点(WLED-AP)，密码为：wled1234
  • 连接成功后可以设置WIFi,然后配置麦克风引脚，并开启拾音功能(这些可以在代码中配置，目前还在研究。。。。。),设置后记得点击save
  • 设置时间，设置后记得点击save

已知问题

• 在切换模式时LED灯板偶尔会出现闪烁,在切换至较大的GIF图片时会出现。
• 收藏中的GIF不准确只会显示当前模式的不会随着选项的变更而切换。
• 收藏模式列表的遍历存在问题，现象是例如你有5个收藏，当切换到第5个后再继续往下切换会卡顿一段时间，因为目前做法是无论你有多少收藏都会遍历250个逐个看哪个有收藏数据

模型展示

第二盘建议使用透明的耗材打印，其余的用黑色的耗材打印。

实物展示

开机中

待机

正面

左侧面

右侧面

后面

内部结构

功能演示