LVGL Starter Kit for VS Code
一键点亮你的 ESP32 + LVGL 屏幕
Make ESP32 + LVGL development feel like a desktop IDE.
English | 中文
English
LVGL Starter Kit is a VS Code extension for ESP32 + MicroPython firmware (with LVGL built-in) + displays.
It combines “install tools, pick port, flash firmware, run demos, sync files, open REPL” into one control-panel flow, making first light-up and iteration feel like a desktop IDE.
Windows is the primary supported platform at the moment.
Features
- Onboarding guide: step-by-step setup to connect and light up the screen in minutes
- Tool download & repair: auto-prepare
esptool and mpremote, verify package hashes (mirrors + SHA256), auto-retry or switch mirror on failure
- Port scan & pick: find the device port automatically and connect in one click
- Firmware flashing: flash the default firmware or use a custom bin
- Demo run: launch built-in demos to verify screen and drivers
- REPL terminal: interactive debug output and quick checks
- File ops: upload/run local files and run/delete remote files
- Workspace sync: sync a whole project or folder to the device
- File tree views: manage local/remote files with drag-and-drop
- Control panel: a single Webview to access common actions
- Feedback entry: request more demos or display support
Getting Started
Shortest Path (2–3 min)
Open the control panel → start the onboarding guide → select the port → flash default firmware → run a demo
If the screen shows the demo, your environment and wiring are basically OK.
Wiring
Please refer to the wiring diagrams in the docs/ directory for your specific chip and display model.
Troubleshooting
If nothing appears on the screen after running a demo:
- Check that the USB serial port is visible on your system
- Re-flash the default firmware from the control panel (MicroPython firmware with LVGL included)
If flashing fails, confirm the board is in download mode; then check port occupancy or permission issues
- Verify file synchronization logs in the output console
- Double-check wiring against the documentation
- In the REPL, run:
import lvgl
lvgl.init()
If lvgl is missing, the firmware is incorrect.
FAQ
Serial port not detected
Install the correct USB-to-serial driver and verify the cable.
Flash timeout or failure
Ensure the board is in download mode and retry.
Control panel does not open
Update VS Code to version 1.90 or later.
White screen with no errors
Usually caused by mismatched display model or pin configuration.
Feedback & Roadmap
We welcome feedback and feature requests such as:
- Support for additional displays (ILI9341, GC9A01, SSD1306, ST7735, etc.)
- Different LVGL versions (8.x, 9.x)
- More demos (animations, touch, UI widgets, images)
Please open an issue:
中文说明
LVGL Starter Kit 是一款面向 ESP32 +（内置 LVGL 的 MicroPython 固件）+ 显示屏 的 VS Code 扩展。
它把“装工具、找串口、刷固件、跑 demo、传文件、开 REPL”合成一个控制面板流程，让第一次点亮屏幕和后续迭代都更像在用桌面 IDE。
当前版本 优先支持 Windows。
功能概述
- 上手向导：按步骤把设备连上并点亮屏幕，几分钟完成验证
- 工具下载与修复：自动准备
esptool、mpremote，校验下载包哈希（支持镜像与 SHA256），失败可自动重试/切换镜像
- 串口扫描与选择：自动找到设备端口并一键连接
- 固件烧录：一键刷入可用固件，或选择自定义 bin
- 示例运行：直接跑内置示例，快速确认屏幕与驱动正常
- REPL 终端：即时交互与输出查看，便于调试
- 文件操作：上传并运行本地文件；运行/删除远端文件
- 工作区同步：把整个项目或文件夹同步到设备
- 文件树视图：像文件管理器一样拖拽上传与管理
- 控制面板：常用操作集中在一个 Webview 面板
- 反馈入口：一键提交更多示例或屏幕支持需求
使用步骤
最短路径（2–3 分钟点亮）
打开控制面板 → 进入上手向导 → 选择串口 → 烧录默认固件 → 运行 demo
屏幕出现对应 demo 效果，即表示环境与接线基本正常。
接线说明
请查看 docs/ 目录中对应 芯片型号 + 屏幕型号 的接线图。
未点亮排查指南
如果运行示例后屏幕没有显示，请按以下顺序检查：
- 设备连接
重新插拔 USB 数据线，确认系统中出现串口设备。
若未出现，请安装对应驱动（CH340 / CP210x）。
- 固件状态
默认固件为内置 LVGL 的 MicroPython 发行物（由扩展提供）。
在控制面板中点击“烧录默认固件”，等待完成。
若失败，请先确认是否已进入下载模式；仍失败再检查串口是否被占用/权限不足。
- 文件同步
查看输出日志中是否有 fs cp 成功记录。
如提示空间不足，可先清理设备文件系统。
- 屏幕接线
对照文档核对引脚定义是否与示例匹配，并确认供电电压正确。
- LVGL 初始化
在 REPL 中执行：
import lvgl
lvgl.init()
若提示找不到 lvgl，说明固件不匹配，需要重新烧录内置固件。
常见问题
串口未识别
通常是驱动未安装或数据线问题。
烧录失败或超时
确认已进入下载模式，必要时按住 BOOT 键重试或替换 USB 线。
控制面板无法打开
请升级 VS Code 至 1.90 及以上，并执行命令：
LVGL Starter Kit: 打开控制面板
白屏但无报错
多为屏幕型号/引脚定义不匹配或固件不正确导致。
反馈与路线图
我们欢迎以下方向的需求与建议：
- 更多显示屏支持（ILI9341、GC9A01、SSD1306、ST7735 等）
- 不同 LVGL 版本支持（8.x、9.x）
- 更多示例（动画、触摸、UI 组件、图片等）
请通过 Issue 提交：
