跳到主要内容

ESP32-S3-RGB-Matrix WLED 使用教程

本教程介绍如何为 ESP32-S3-RGB-Matrix 在线烧录 WLED 固件、连接 Wi-Fi、配置 HUB75 LED 点阵屏，以及排查常见的显示问题。

目录​

一、准备材料​

材料数量说明
ESP32-S3-RGB-Matrix1主控开发板
RGB-Matrix-P2.5-64×32 点阵屏及配件1 套HUB75 接口 LED 点阵屏
电源转接头1用于连接外部 5 V 电源
USB 数据线1用于连接开发板与电脑，请勿使用仅支持充电的线材

开始前，请确保电脑能够正常联网，并使用支持 Web Serial 的浏览器（推荐最新版 Chrome 或 Edge）。

二、安全注意事项​

供电与接线要求

显示屏的工作电压为 5 V，必须使用外部 5 V 电源供电。请勿接入其他电压，否则可能损坏设备。

连接或调整 HUB75 排线及电源线之前，请先断开开发板和显示屏的电源，避免带电插拔。

连接显示屏前，请按照下图所示方法测量电源端子的输出电压：

  • 测量结果应为 +5 V。
  • 如果测得 -5 V，表示端子极性可能接反。请停止接线，并及时联系客服更换对应端子。

测量电源端子输出电压

三、在线烧录 WLED 固件​

1. 选择固件与开发板​

使用支持 Web Serial 的浏览器访问 WLED 在线安装页面。

按照以下顺序选择安装选项：

  1. 将安装模式切换为 "Advanced"。
  2. 选择 "HUB75 Matrix"。
  3. 在 "Layout" 中选择 "Waveshare ESP32-S3-RGB-Matrix"。
  4. 确认选择无误后，点击页面中的 "Install"。

选择 Advanced、HUB75 Matrix 和 Waveshare ESP32-S3-RGB-Matrix

2. 连接开发板​

使用 USB 线将开发板连接到电脑。在弹出的端口列表中选择开发板对应的串口，然后点击 连接。

选择开发板串口

3. 开始安装​

选择 "Install WLED"。

选择 Install WLED

勾选 "Erase device" 会擦除开发板中原有的数据和配置。

勾选 "Erase device"，然后点击 "Next"。

勾选 Erase device

确认无误后，点击 "Install"。

确认安装 WLED

4. 等待烧录完成​

安装程序将自动擦除设备并烧录固件。该过程可能需要几分钟，请保持 USB 连接稳定，不要拔出开发板。

正在擦除并烧录固件

WLED 固件烧录进度

烧录完成后，点击 "Next"。

烧录完成后点击 Next

四、配置开发板网络​

1. 连接 Wi-Fi​

  1. 烧录完成后重启开发板。
  2. 返回安装页面，点击 "Install"，重新连接开发板。
  3. 点击 "Connect to Wi-Fi"。

点击 Connect to Wi-Fi

输入 2.4 GHz Wi-Fi 名称和密码，然后点击 "Connect"。

WLED 配网需要使用 2.4 GHz Wi-Fi，请确认网络名称和密码输入正确。

输入 Wi-Fi 名称和密码

2. 等待连接完成​

等待开发板完成网络配置并接入 Wi-Fi。

等待开发板连接 Wi-Fi

连接成功后，点击 "Skip"，跳过后续步骤。

Wi-Fi 连接成功后点击 Skip

五、配置 LED 屏幕​

1. 进入 WLED 配置页面​

点击 "Visit Device"，打开 WLED 设备页面。

点击 Visit Device

没有出现 Visit Device 怎么办？​

如果页面中没有出现 "Visit Device"，可以尝试重新配置 Wi-Fi：

  1. 打开 WLED 设备菜单。
  2. 点击 "Change Wi-Fi"，重新输入并连接 2.4 GHz Wi-Fi。
  3. 出现 "Device connected to the network!" 提示后，点击 Continue。
  4. 返回安装页面，再点击 "Visit Device"。

打开 WLED 设备菜单

点击 Change Wi-Fi 重新配置网络

设备成功联网后点击 Continue

如果出现数据上报提示，点击 "Skip reporting"。

点击 Skip reporting

2. 打开 LED 与硬件设置​

在 WLED 主页顶部点击 "Config"。

点击 WLED 主页顶部的 Config

然后进入 "LED & Hardware"。

进入 Config 中的 LED 与硬件设置

3. 添加并配置 LED 屏幕​

设置亮度上限，然后点击 + 添加 LED 输出。

此处设置的是设备允许使用的最大亮度。建议先设置较低的亮度，确认供电与显示正常后再逐步调高。

调整最大亮度并添加 LED 屏幕

对于本教程使用的单块 P2.5 64×32 点阵屏，请按照下表和截图设置参数：

配置项设置值
LED 输出类型HUB75 (Half Scan)
Start0
Panel（width × height）64 × 32
No. of Panels1
rows × cols1 × 1
Make a segment for each output勾选

如果使用的屏幕尺寸或拼接数量不同，请根据实际硬件调整 Panel、rows 和 cols，不要直接照抄上述数值。

配置 HUB75 LED 屏幕参数

完成配置后，点击页面上方的 "Save" 保存设置，并在提示框中点击"确定"。

保存 LED 屏幕配置

4. 配置屏幕 2D 属性​

进入 "Config" 页面，然后选择 "2D Configuration"。

进入后选择 "2D Matrix"。

按照屏幕的实际尺寸设置矩阵参数。

确认参数无误后，点击 "Save" 保存。

5. 接线并重启设备​

  1. 点击 Back 返回 WLED 主页。
  2. 断开开发板和 LED 点阵屏的电源。
  3. 连接开发板、HUB75 排线以及 LED 点阵屏的外部 5 V 电源线。
  4. 检查电源极性、排线方向和接口是否正确、牢固。
  5. 确认接线无误后重新上电，启动开发板和 LED 点阵屏。
重启后配置生效

修改 HUB75 参数并保存后，必须重启 WLED。参数刚修改完成时，屏幕可能暂时黑屏；重启后，新的驱动配置才会生效。

完成接线并重新上电后，即可在 WLED 主页中调整亮度、颜色和显示效果。

WLED LED 点阵屏显示效果

六、排查色彩异常​

如果屏幕可以点亮，但颜色与 WLED 页面中选择的颜色不一致，请先检查排线方向和屏幕参数。确认硬件连接及参数均正确后，可以尝试更新配套固件。

固件匹配要求

只能上传与 ESP32-S3-RGB-Matrix / HUB75 匹配的 .bin 固件。上传错误固件可能导致设备无法正常启动。

更新期间请保持设备供电和网络连接稳定，不要关闭页面、断电或重启设备。

1. 准备固件​

配套固件尚未发布

配套 WLED 固件的下载地址将在固件发布后补充。在下载地址更新前，请勿使用产品仓库 firmware 目录中的测试固件或小智固件执行本节操作。

WLED 手动更新页面只能选择固件文件，请勿直接上传 .zip 压缩包。如果收到的是压缩包，请先解压，并确认其中包含匹配板型的 .bin 文件。

V2 固件适用范围

仅 RGB-Matrix-Px-96x48 灯板需要烧录 V2 版本固件。

2. 打开软件更新页面​

在 WLED 主页顶部点击 "Config"。

点击 WLED 主页顶部的 Config

在配置菜单中点击 "Security & Updates"。

进入 Security & Updates

找到 "Software Update"，然后点击 "Update WLED"。

点击 Software Update 中的 Update WLED

3. 手动上传固件​

在 "Manual upload" 区域点击"选择文件"，选择解压得到的 .bin 固件。

选择匹配开发板的 BIN 固件

确认文件无误后，点击 "Upload" 开始更新。

通常不需要勾选 "Ignore firmware validation"。除非固件提供方明确要求，否则请保持该选项未勾选。

点击 Upload 上传固件

等待固件上传和设备重启完成。页面自动返回 WLED 主页后，请刷新网页，再测试屏幕颜色是否恢复正常。

七、配置音乐律动​

ESP32-S3-RGB-Matrix 板载 ES7210、ES8311 和双麦克风。音乐律动功能需要使用包含 AudioReactive usermod 的 Waveshare HUB75 专用固件。

1. 确认固件支持 AudioReactive​

打开 WLED 的 "Info"（信息）页面，确认固件名称为：

ESP32-S3_Waveshare_HUB75

然后进入 "Config" > "Usermods"。

如果页面中没有 "AudioReactive"，说明当前固件未包含音乐律动模块，需要先安装适用于本开发板的专用固件。

确认固件名称并进入 Usermods 设置

2. 设置板载麦克风​

在 "AudioReactive" 区域按照下表配置：

配置项设置值
Enabled勾选
Digitalmic TypeES8311
I2S SD39
I2S WS38
I2S SCK43
I2S MCLK12
I2C SDAunused
I2C SCLunused
Squelch10
Gain建议从 60 开始，响应较弱时逐步增加至 120
AGCNormal
Sync Mode单机使用选择 Off

配置 AudioReactive 的麦克风类型、引脚和音频参数 配置 AudioReactive 的音频同步参数

设置完成后，按照以下步骤保存并重新上电：

  1. 点击 "Save"。
  2. 拔掉开发板的 USB 和其他供电。
  3. 等待约 2 秒后重新供电。
完全断电后配置生效

修改麦克风类型或音频引脚后，应执行一次完全断电。ES8311/ES7210 有时会保留寄存器状态，只在网页中重启可能无法彻底复位音频芯片。

3. 检查音频模块状态​

重新上电后，打开 "Info"（信息）页面，检查 "Audio Source" 和 "Sound Processing"。正常情况下，音频源已初始化，声音处理处于运行状态。

如果看到下面的信息，表示音频驱动没有成功启动：

Audio Source: not initialized - check pin settings
Sound Processing: suspended

出现该状态时，请重新核对上表中的麦克风类型和引脚，然后再次保存并完全断电重启。

4. 测试音乐律动效果​

  1. 返回 WLED 主界面。
  2. 打开 "Effects mode"（效果）。
  3. 选择音频响应效果，例如 GEQ、Gravimeter、Freqwave 或 Waterfall。
  4. 对着板载麦克风拍手，或者在开发板附近播放音乐。
  5. 观察 LED 矩阵图案是否随声音强弱和频率变化。

如果响应较弱，请逐步提高 "Gain"；如果环境安静时图案仍不断跳动，请提高 "Squelch"。

选择音频响应效果并测试 LED 矩阵音乐律动

5. 音频同步​

单机使用时将 "Sync Mode" 设置为 Off。如果需要让两台 WLED 使用同一个音频源：

  • 带麦克风的设备设置为 Send；
  • 另一台设备设置为 Receive；
  • 两台设备连接到同一局域网；
  • 两台设备使用相同的音频同步端口，默认端口为 11988。

完成​

至此，WLED 固件烧录、网络连接和 LED 点阵屏配置均已完成。如果屏幕没有正常显示，请优先检查以下项目：

  • 外部电源是否为稳定的 5 V 输出；
  • 电源正负极是否连接正确；
  • HUB75 排线方向是否正确、接口是否插紧；
  • LED 屏幕参数是否与上图一致；
  • 保存 HUB75 参数后是否已重启开发板；
  • 重启开发板后是否已刷新 WLED 网页；
  • 出现色彩异常时，是否已确认固件与开发板型号匹配。