Adding support for Waveshare ESP32-S3-RGB-Matrix by Will-wastelander · Pull Request #5657 · wled/WLED

Will-wastelander · 2026-05-30T04:04:29Z

Adding basic support for Waveshare ESP32-S3-RGB-Matrix
https://www.waveshare.com/esp32-s3-rgb-matrix.htm
https://docs.waveshare.com/ESP32-S3-RGB-Matrix

Matrix Panel is working. Microphone(s), SD card, and SHTC3 still need work.

Summary by CodeRabbit

New Features
- Adds support for Waveshare ESP32‑S3 (32MB) boards driving HUB75 LED matrices.
- New build/profile enabling PSRAM and HUB75 matrix support with a Waveshare-specific pinout to prevent hardware conflicts.
- Dedicated release name for this board and improved startup/serial diagnostics for clearer troubleshooting.

https://www.waveshare.com/esp32-s3-rgb-matrix.htm https://docs.waveshare.com/ESP32-S3-RGB-Matrix

coderabbitai · 2026-05-30T04:04:42Z

Walkthrough

Adds a PlatformIO environment waveshare_esp32s3_32MB_hub75 enabling WAVESHARE_S3_PINOUT and HUB75 build flags, and adds a #elif defined(WAVESHARE_S3_PINOUT) branch in wled00/bus_manager.cpp that sets Waveshare-specific HUB75 GPIO mappings.

Changes

Waveshare ESP32-S3 HUB75 Support

Layer / File(s)	Summary
Waveshare S3 HUB75 build environment and pin mapping `platformio.ini`, `wled00/bus_manager.cpp`	New `waveshare_esp32s3_32MB_hub75` PlatformIO environment wires HUB75 and ESP32-S3 build flags, `WAVESHARE_S3_PINOUT`, monitor filters, and lib deps; `bus_manager.cpp` adds a `#elif defined(WAVESHARE_S3_PINOUT)` branch setting Waveshare-specific `mxconfig.gpio` values and logging the selection.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

wled/WLED#5558: Modifies wled00/bus_manager.cpp HUB75 ESP32-S3 pinout handling; related pinout branches.
wled/WLED#5107: Updates ESP32-S3 32MB build environment/flags that this PR extends.
wled/WLED#3777: Prior HUB75/BusHub75Matrix work in wled00/bus_manager.cpp related to driver/pin mappings.

Suggested reviewers

softhack007
netmindz
DedeHai

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically summarizes the main change: adding support for a new hardware board (Waveshare ESP32-S3-RGB-Matrix). It is clear, concise, and directly reflects the primary objective of the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@platformio.ini`:
- Line 661: Replace the misspelled release name value for the WLED_RELEASE_NAME
build flag: locate the build_flags line that defines -D WLED_RELEASE_NAME and
change the string literal from "ESP32-S3_Waveshave_Matrix" to the correct
"ESP32-S3_Waveshare_Matrix" so the release name spelling is fixed wherever
WLED_RELEASE_NAME is used.
- Line 659: The shared platformio.ini contains a machine-specific setting
upload_port = COM12 which should be removed from the shared config; delete or
comment out the upload_port entry in platformio.ini and place that setting into
platformio_override.ini (or instruct contributors to set their own upload_port
in a local override) so each developer/OS can define their own COM/serial port;
ensure you reference the upload_port key (and keep other shared settings
unchanged) and add a brief comment in platformio_override.ini indicating it is
for machine-specific overrides.
- Around line 652-680: The platformio.ini change touches the protected env
section "env:waveshare_esp32s3_32MB_hub75" and must not be merged without
explicit maintainer approval; before merging, request and record approval from a
WLED maintainer/org member for the platformio.ini modifications (or revert the
changes in the "env:waveshare_esp32s3_32MB_hub75" block until approval is
granted), and ensure the PR description or commit message includes the
approver's GitHub username and a short justification referencing the modified
symbols (e.g., build_flags and lib_deps entries) so reviewers can verify
approval.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9295dff2-bd04-4656-b31f-8af9f01bf741

📥 Commits

Reviewing files that changed from the base of the PR and between 1825ce7 and 73898dd.

📒 Files selected for processing (2)

platformio.ini
wled00/bus_manager.cpp

coderabbitai · 2026-05-30T04:07:20Z

+[env:waveshare_esp32s3_32MB_hub75]
+extends = env:esp32S3_wroom2_32MB
+board_build.partitions = ${esp32.extreme_partitions}
+board_build.f_flash = 80000000L
+board_upload.flash_size = 32MB
+monitor_filters = esp32_exception_decoder
+upload_speed = 115200
+upload_port = COM12
+build_unflags = ${common.build_unflags}
+build_flags = ${common.build_flags} ${esp32s3.build_flags} -D WLED_RELEASE_NAME=\"ESP32-S3_Waveshave_Matrix\"
+  -D WLED_ENABLE_HUB75MATRIX
+  -D NO_GFX
+  -D NO_FAST_FUNCTIONS
+  -D NO_CIE1931
+  -D S3_LCD_DIV_NUM=20
+  -DARDUINO_USB_CDC_ON_BOOT=1
+  -DBOARD_HAS_PSRAM
+  -DLOLIN_WIFI_FIX ; seems to work much better with this
+  -D WLED_WATCHDOG_TIMEOUT=0
+  -D WAVESHARE_S3_PINOUT
+;  -D WLED_USE_SD_SPI
+;  -D SD_PRINT_HOME_DIR
+;  -D WLED_DEBUG
+  -D USERMOD_AUDIOREACTIVE
+  -D SR_DMTYPE=0 -D I2S_SDPIN=-1 -D I2S_CKPIN=-1 -D I2S_WSPIN=-1 -D MCLK_PIN=-1  ;; Disable to prevent pin clash
+lib_deps = ${esp32s3.lib_deps}
+  ${esp32.AR_lib_deps}
+  ${hub75.lib_deps}
+


⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Maintainer approval is required for this platformio.ini change.

This file is explicitly protected; please ensure a maintainer/WLED org member approves this PR before merge.

As per coding guidelines: “platformio.ini: Modifications to platformio.ini MUST be approved explicitly by a maintainer or WLED organisation Member; always flag such modifications”.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@platformio.ini` around lines 652 - 680, The platformio.ini change touches the protected env section "env:waveshare_esp32s3_32MB_hub75" and must not be merged without explicit maintainer approval; before merging, request and record approval from a WLED maintainer/org member for the platformio.ini modifications (or revert the changes in the "env:waveshare_esp32s3_32MB_hub75" block until approval is granted), and ensure the PR description or commit message includes the approver's GitHub username and a short justification referencing the modified symbols (e.g., build_flags and lib_deps entries) so reviewers can verify approval.

@netmindz the platformio buildenv basicially consists of extends = env:esp32S3_wroom2_32MB and -D WAVESHARE_S3_PINOUT.

I'm not sure if this should be in the main platformio.ini, or we move it into platformio_override.ini.sample? The board has a new HUB75 pinout and it seems to be based on a "wroom-2" S3, so it's somewhat special.

We've just managed to clean up the platformio.ini file, not sure if we should continue to populate it with whatever board comes along 🤔 . What do you think?

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

netmindz · 2026-05-30T07:25:27Z

Thanks for the PR and this new pinout. That platformio env is a mess however, it's overriding values unnecessarily, setting flags that are for previous versions of WLED etc. Please strip that back to only what is actually required

Updated build flags for the waveshare_esp32s3_32MB_hub75 environment, removing some flags and adding new ones.

Removed flags for fast functions and CIE1931 from build configuration.

Removed upload speed and port settings for the waveshare_esp32s3_32MB_hub75 environment.

Removed unused build unflags.

* un-set previous RELEASE_NAME before setting a new one * align REALEASE_NAME with naming scheme used by other HUB75 builds

softhack007 · 2026-05-30T20:09:50Z

@Will-wastelander i've moved your new buildenv into the HUB75 section, and corrected a few problems - was faster to do it, rather than describing what I want.

@netmindz we should still decide if we want the new buildenv in the main platformio.ini, or in platformio_override.sample.ini?

Will-wastelander · 2026-05-30T20:16:10Z

@softhack007 Thanks for the assistance!

netmindz · 2026-06-02T18:01:18Z

+[env:waveshare_esp32s3_32MB_hub75]
+;; Waveshare ESP32-S3-RGB-Matrix (memory_type: opi_opi); see https://docs.waveshare.com/ESP32-S3-RGB-Matrix
+extends = env:esp32S3_wroom2_32MB
+monitor_filters = esp32_exception_decoder


netmindz · 2026-06-02T18:04:07Z

To actually be included in a release it should also be referenced in platformio_release.ini.template

If we are going to add support, that should really be for all features, not just the pinout. I think @troyhacks has support for audio

Happy to merge as hub75 support only, then we have new issue for proper support of the board, which is when it would get added to the release bins

Will-wastelander · 2026-06-02T18:11:08Z

To actually be included in a release it should also be referenced in platformio_release.ini.template

If we are going to add support, that should really be for all features, not just the pinout. I think @troyhacks has support for audio

Happy to merge as hub75 support only, then we have new issue for proper support of the board, which is when it would get added to the release bins

@netmindz This was just initial support, to get the ball rolling for it. I'm trying to research getting the MICs working, along w/ SHTC3, IMU, RTC, and SD Card. The Build ENV I did has the build flags needed for the SD Card, just need to add the UM to the build flags for SD Card support. I plan on testing this soon, but not exactly sure what the SD Card would be used for when it comes to WLED.

Will-wastelander added 2 commits May 29, 2026 20:55

Add support for Waveshare S3 Matrix Driver board

cdf1f80

https://www.waveshare.com/esp32-s3-rgb-matrix.htm https://docs.waveshare.com/ESP32-S3-RGB-Matrix

Add new environment for Waveshare ESP32-S3 hub75

73898dd

https://www.waveshare.com/esp32-s3-rgb-matrix.htm https://docs.waveshare.com/ESP32-S3-RGB-Matrix

coderabbitai Bot added enhancement hardware (Likely) Setup-specific issue, e.g. flickering LEDs labels May 30, 2026

coderabbitai Bot reviewed May 30, 2026

View reviewed changes

Update upload port and build flags in platformio.ini

bd8a16a

coderabbitai Bot added the Awaiting testing label May 30, 2026

Modify build flags in platformio.ini for ESP32-S3

fd162ce

Updated build flags for the waveshare_esp32s3_32MB_hub75 environment, removing some flags and adding new ones.

softhack007 reviewed May 30, 2026

View reviewed changes

Comment thread platformio.ini Outdated

softhack007 reviewed May 30, 2026

View reviewed changes

Comment thread platformio.ini Outdated

softhack007 reviewed May 30, 2026

View reviewed changes

Comment thread platformio.ini Outdated

Will-wastelander added 2 commits May 30, 2026 12:19

Remove unused build flags from platformio.ini

c399d71

Removed flags for fast functions and CIE1931 from build configuration.

Remove upload settings from waveshare_esp32s3_32MB_hub75

d6482e9

Removed upload speed and port settings for the waveshare_esp32s3_32MB_hub75 environment.

softhack007 reviewed May 30, 2026

View reviewed changes

Comment thread platformio.ini Outdated

Clean up build flags in platformio.ini

6bd90ab

Removed unused build unflags.

coderabbitai Bot added the good job label May 30, 2026

softhack007 added 2 commits May 30, 2026 22:02

buildenv bugfix, better release_name

bb495f7

* un-set previous RELEASE_NAME before setting a new one * align REALEASE_NAME with naming scheme used by other HUB75 builds

move new buildenv into HUB75 section

82c4ce5

netmindz reviewed Jun 2, 2026

View reviewed changes

netmindz merged commit bd0ebf9 into wled:main Jun 2, 2026
26 checks passed

Uh oh!

Conversation

Will-wastelander commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

softhack007 May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot May 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

netmindz commented May 30, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

softhack007 commented May 30, 2026

Uh oh!

Will-wastelander commented May 30, 2026

Uh oh!

netmindz Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

netmindz commented Jun 2, 2026

Uh oh!

Will-wastelander commented Jun 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Will-wastelander commented May 30, 2026 •

edited

Loading

coderabbitai Bot commented May 30, 2026 •

edited

Loading

coderabbitai Bot May 30, 2026 •

edited

Loading

softhack007 May 30, 2026 •

edited

Loading