ESP32-S3 + Windows 虚拟 LED 灯板模拟器：安装、烧录、串口通信与常见问题

前言

做 WS2812B 灯带或矩阵灯板时，如果硬件还没到、灯板暂时不在手边，或者只想先验证动画和像素映射，可以让 ESP32-S3 把 RGB 帧通过 USB 串口发送到电脑，再由桌面程序模拟实体灯板。

本文分享一个已经打包成 Windows 安装程序的 LED 灯板模拟器，并完整说明：

• 软件功能和安装方法；
• ESP32-S3 PlatformIO 示例工程的烧录；
• USB 串口连接步骤；
• GPIO13 按键切换灯效；
• 自定义灯效代码入口；
• COM 口占用、映射错误、颜色错误、CRC 错误等常见问题。

1. 软件功能

当前版本支持：

• 串口选择、常用波特率、断线自动重连；
• RGB888 与 RGB565；
• CRC32 校验、帧号、丢帧和带宽统计；
• 自定义宽度、高度、灯珠总数；
• 按行/按列、蛇形/同向、四角首灯；
• 旋转、水平镜像、垂直镜像；
• RGB、GRB、BRG、RBG、GBR、BGR；
• 亮度、Gamma、灯珠间距、网格、柔光、索引显示；
• 本地彩虹、定位、棋盘、跑马、渐变测试；
• 配置保存和灯板截图。

模拟器的重点是把“物理串联顺序”和“二维显示位置”分开。这样可以在没有实体灯板时验证索引映射，也能快速判断问题出在动画数据、颜色通道还是板子走线。

2. 安装软件

普通使用者直接运行：

LED灯板模拟器_Setup_v1.0.0.exe

安装时勾选桌面快捷方式。软件不要求用户单独安装 Python。

第一次启动后，先不要连接串口，在窗口下方选择内置测试图案，确认本地渲染和映射设置正常。

3. 准备 PlatformIO

1. 安装 VS Code；
2. 在扩展商店安装 PlatformIO IDE；
3. 打开一次 PlatformIO Home，等待 Core 初始化完成；
4. 在安装目录中找到 examples/ESP32_Frame_Sender。

工程配置如下：

[env:esp32-s3-devkitc-1]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
monitor_speed = 921600
upload_speed = 460800

4. 烧录 ESP32-S3

4.1 一键脚本

双击示例工程里的 upload.bat。脚本会列出串口，输入 ESP32-S3 对应的 COM 口；直接回车则使用 PlatformIO 自动检测。

4.2 VS Code 操作

用 VS Code 打开 ESP32_Frame_Sender 文件夹，在 PlatformIO 的 Project Tasks 中依次执行：

esp32-s3-devkitc-1 -> General -> Build
esp32-s3-devkitc-1 -> General -> Upload

如果开发板有两个 Type-C 口，应优先使用与 USB 转串口芯片相连的下载口。拔插开发板，观察设备管理器中哪个 COM 口出现或消失，是最直接的判断方法。

5. 连接模拟器

1. 关闭 PlatformIO Serial Monitor；
2. 打开 LED 灯板模拟器；
3. 刷新并选择 ESP32-S3 的 COM 口；
4. 波特率设为 921600；
5. 测试图案设为“关闭（显示串口）”；
6. 点击连接；
7. 检查右上角 FPS、数据格式、带宽、丢帧和 CRC。

6. 使用 GPIO13 按键切换灯效

接线：

GPIO13 ---- 按键 ---- GND

代码使用 INPUT_PULLUP，无需外部上拉。每次短按依次切换：彗星、彩虹、扫描、交替闪烁、RGB 色条、定位图案。

7. 修改自己的灯效

文件位置：

examples/ESP32_Frame_Sender/src/main.cpp

默认效果：

EffectMode currentEffect = EffectMode::COMET;

每颗像素在缓冲区中占用三个字节：

pixels[n * 3 + 0] = red;
pixels[n * 3 + 1] = green;
pixels[n * 3 + 2] = blue;

自定义效果建议单独写成：

void effectMyAnimation(uint32_t frame) {
    for (uint16_t n = 0; n < LED_COUNT; ++n) {
        // 根据 frame 和 n 计算 RGB
    }
}

然后在 EffectMode 和 makeAnimation() 的 switch 中注册即可。帧头、像素格式、CRC 和串口发送由现有代码统一完成。

8. 常见问题

upload.bat 乱码

旧脚本可能被 Windows CMD 错误解析。使用最新版纯 ASCII、CRLF 格式的 upload.bat。

PlatformIO Core was not found

安装 PlatformIO IDE，并等待 PlatformIO Home 初始化完成。

Could not open COMxx / PermissionError(13)

关闭灯板模拟器、Arduino/PlatformIO 串口监视器和其他占用串口的软件，再烧录。

Connecting 超时

核对板型和端口；必要时按住 BOOT，点按 RST，松开 BOOT 后重新 Upload。

软件连接后没有画面

将测试图案改成“关闭（显示串口）”，核对波特率 921600，并尝试另一个 USB 口。

颜色通道错误

在 RGB、GRB、BRG、RBG、GBR、BGR 中切换，不必先修改 MCU 算法。

方向或首灯错误

用定位图案，一次只改一个参数：首灯位置、行列、蛇形/同向、旋转、镜像。

CRC 错误不断增加

不要在同一个 Serial 输出 Serial.print() 调试文字，否则会污染二进制帧。

高分辨率丢帧

64×64 RGB888 @ 30 FPS 仅像素数据约需 3.69 Mbps。可降低帧率、使用 RGB565、降低分辨率，或改用 USB CDC/网络。

9. 使用边界

模拟器适合开发灯效、验证映射、检查串口帧和录制演示，但不能代替实体灯板的供电压降、逻辑电平和信号完整性测试。更合理的流程是：先在电脑上确认数据和映射，再连接实体灯板处理电气问题。

总结

这个工具把 LED 项目拆成了三个独立环节：ESP32-S3 生成像素、串口传输像素、电脑按配置显示像素。出现问题时，可以更快判断是动画算法、通信还是物理灯板的问题。

私信我领取安装包和ESP32S3示例代码。