update for esp32-S3 builds, and support for 32MB Flash #5107

softhack007 · 2025-11-22T19:39:49Z

removed obsolete "-D CONFIG_LITTLEFS_FOR_IDF_3_2" => this was only for the old "lorol/LITTLEFS" which is not used any more in WLED
commented out "-D ARDUINO_USB_MODE=1", because users have reported that it leads to boot "hanging" when no USB-CDC is connected (arduino-esp32 will pick a meaningful default when the flag is missing)
new buildenv for esp32s3-WROOM-2 with 32MB flash
new 32MB partitions file (3MB app +3MB OTA, 27MB (!) LittleFS filesystem)
added esp32S3_wroom2 to default builds
this board does not run with esp32s3dev_16MB_opi, because it needs "opi_opi" (not qio_opi) memory mode.
disabled "-mfix-esp32-psram-cache-issue" warning for -S2 and -S3
This flag is only necessary for classic esp32 "rev.1", but harmful on S3 or S2.
HUB75 boards: use the correct partition size for 8MB and 16MB flash respectively
example for "optimize for speed" (-O2) instead of "optimize for size" (-Os) - tested & works well in WLED-MM

Summary by CodeRabbit

New Features
- Added a 32MB ESP32‑S3 board variant and a PlatformIO board profile for Adafruit MatrixPortal ESP32‑S3 with matching flash/PSRAM/partition settings.
Bug Fixes
- Narrowed PSRAM warning so it only appears for the intended ESP32 architectures.
Chores
- Simplified USB boot flags and removed legacy LittleFS flags across ESP32‑S3 environments; added optional speed/partition override settings for HUB75/PSRAM builds.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

* removed obsolete "-D CONFIG_LITTLEFS_FOR_IDF_3_2" => this was only for the old "lorol/LITTLEFS" whic is not used any more in WLED * commented out "-D ARDUINO_USB_MODE=1", because users have reported that it leads to boot "hanging" when no USB-CDC is connected * Added buildenv and 32MB partition for esp32s3-WROOM-2 with 32MB flash * disabled "-mfix-esp32-psram-cache-issue" warning for -S2 and -S3 (only necessary for classic esp32 "rev.1", but harmful on S3 or S2)

coderabbitai · 2025-11-22T19:39:59Z

Walkthrough

Adds new esp32S3_wroom2 and esp32S3_wroom2_32MB PlatformIO environments, a new Adafruit MatrixPortal ESP32-S3 board manifest, simplifies several ESP32-S3 build flags/partitions (USB/PSRAM-related), and narrows a PSRAM warning in wled00/util.cpp with architecture-specific preprocessor guards.

Changes

Cohort / File(s)	Summary
PlatformIO environments `platformio.ini`	Added `esp32S3_wroom2` to `default_envs` and introduced `esp32S3_wroom2_32MB` extending `esp32S3_wroom2`; removed `CONFIG_LITTLEFS_FOR_IDF_3_2` from S3 envs; simplified USB boot flags (dropped explicit `ARDUINO_USB_MODE`, kept/commented `ARDUINO_USB_CDC_ON_BOOT`); set `WLED_WATCHDOG_TIMEOUT` and `WLED_RELEASE_NAME` for variants; added `BOARD_HAS_PSRAM`/PSRAM pin defs and 32MB-specific partition/flash sizing and board_upload limits.
PlatformIO override sample `platformio_override.sample.ini`	Added optional `[Speed_Flags]` block for speed-oriented build flags; updated `adafruit_matrixportal_esp32s3` and HUB75/PSRAM env comments and build_flags to prefer `ARDUINO_USB_CDC_ON_BOOT`; moved certain S3 envs to larger/extreme partition references and integrated Speed_Flags and HUB75/PSRAM pin/define adjustments.
Board manifest `boards/adafruit_matrixportal_esp32s3.json`	New PlatformIO board JSON for Adafruit MatrixPortal ESP32-S3: ldscript, partitions (tinyUF2/8MB), core/mcu/variant, hwids, wifi/bluetooth connectivity, openocd target, frameworks (arduino, espidf), upload settings (flash_size, maximum_size, speed) and tinyUF2 extra image entry.
PSRAM warning conditional `wled00/util.cpp`	Narrowed PSRAM warning emission by adding architecture-specific guards so the `BOARD_HAS_PSRAM` warning about `-mfix-esp32-psram-cache-issue` is shown only when `ARDUINO_ARCH_ESP32` is defined (excluding S2/S3 targets); added matching `#endif` to balance preprocessor conditionals.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Verify new partition CSV references and board_upload flash_size/maximum_size for the 32MB env and tinyUF2 image offsets.
Confirm USB behavior where ARDUINO_USB_MODE was removed and ARDUINO_USB_CDC_ON_BOOT remains/commented as intended.
Check PSRAM guard in wled00/util.cpp for correct conditional balance and target semantics.

Possibly related PRs

Remove old V3 IDF #4836 — Modifies PlatformIO ESP32 environment configuration; overlaps with env/flag changes here.
Usermod libs matrix #4592 — Adjusts ESP32-S3 PlatformIO environments and partitioning; directly related to partition/env edits.
Add HUB75 support #3777 — Adds board/env support for Adafruit MatrixPortal ESP32-S3 and HUB75/PSRAM flags; intersects with the new board manifest and PSRAM/HUB75 changes.

Suggested reviewers

DedeHai
willmmiles
blazoncek

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main changes: updates to ESP32-S3 build configurations and support for 32MB flash variants.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch s3_wroom2_32MB

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.}

this board does not run with esp32s3dev_16MB_opi, because it needs "opi_opi" (not qio_opi) memory mode.

DedeHai · 2025-11-22T20:03:29Z

nice addition. since we just had the request about the matrix portal: can that json definition be added to wled or does that need to be included in the pio platform for the compiler to find it?
edit: I see you just had the same idea ;)

softhack007 · 2025-11-22T20:05:14Z

nice addition. since we just had the request about the matrix portal: can that json definition be added to wled or does that need to be included in the pio platform for the compiler to find it?

@DedeHai its enough to add the matrixportal board.json to our boads/ folder. I'll add that one 👍

* board.json added to WLED/boards * use partitions file that supports adafruit UF2 bootloader

coderabbitai

Actionable comments posted: 3

🧹 Nitpick comments (1)

platformio_override.sample.ini (1)

567-569: Document the recommended platform configuration more clearly.

Lines 567-569 provide commented examples of the arduino-esp32 2.0.14 recommendation. Consider adding a brief note explaining when/why users should uncomment these lines (e.g., "Uncomment if experiencing build compatibility issues").

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7dfed58 and d8e2cee.

📒 Files selected for processing (2)

boards/adafruit_matrixportal_esp32s3.json (1 hunks)
platformio_override.sample.ini (2 hunks)

🧰 Additional context used

🧠 Learnings (6)

📓 Common learnings

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:11.994Z
Learning: In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with appropriate defined constants when those constants are meaningful in the context of the PR. For example, the hardcoded value 32 should be replaced with WLED_MAX_SEGNAME_LEN when it represents a segment name length limit. This improves code maintainability and reduces the risk of inconsistencies.

Learnt from: blazoncek
Repo: wled/WLED PR: 4482
File: wled00/udp.cpp:147-149
Timestamp: 2025-02-19T12:43:34.199Z
Learning: ESP8266 and ESP32 platforms have different maximum segment name lengths in WLED, which can cause truncation when syncing segment names between devices. This platform difference affects the user experience when using the segment name sync feature.

Learnt from: netmindz
Repo: wled/WLED PR: 5093
File: wled00/util.cpp:1159-1182
Timestamp: 2025-11-20T00:04:04.829Z
Learning: In WLED PR #5093, the deviceId feature is designed for opt-in usage reporting that tracks only version/upgrade information (non-behavioral data), not user activity patterns. The deterministic salt approach (MAC + "WLED" + chip model/revision) is acceptable for this limited use case, as correlating MAC addresses to version history represents minimal privacy risk compared to behavioral tracking.

Learnt from: DedeHai
Repo: wled/WLED PR: 4798
File: wled00/FX.cpp:7531-7533
Timestamp: 2025-08-26T11:51:21.817Z
Learning: In WLED PR #4798, DedeHai confirmed that certain gamma-related calls in FX.cpp/FX_fcn.cpp/particle systems are intentional for effect-level shaping (e.g., brightness curves, TV sim, Pride 2015 pre-mix), distinct from final output gamma. Do not flag or remove these in future reviews; add comments when feasible to clarify intent.

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:30.955Z
Learning: In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with defined constants when meaningful constants exist in the codebase. For example, suggest replacing hardcoded "32" with WLED_MAX_SEGNAME_LEN if the context relates to segment name length limits.

Learnt from: blazoncek
Repo: wled/WLED PR: 4995
File: wled00/FX.cpp:5223-5226
Timestamp: 2025-10-20T09:38:51.997Z
Learning: WLED matrices: each dimension (SEG_W, SEG_H) is limited to ≤255; 256 or larger per side is not supported/feasible on ESP32, so effects should assume per-dimension max 255.

Learnt from: mval-sg
Repo: wled/WLED PR: 4876
File: wled00/wled_eeprom.cpp:0-0
Timestamp: 2025-09-01T10:26:17.959Z
Learning: In WLED PR #4876, the DMXStartLED EEPROM backward compatibility issue was partially addressed by keeping it at address 2550 and reading it as a 16-bit value, with DMXChannelsValue array moved to addresses 2552-2566. This maintains compatibility with pre-0.11 EEPROM layouts for DMXStartLED, though legacy "Set to 255" (code 6) configurations may still need migration logic.

Learnt from: willmmiles
Repo: wled/WLED PR: 4890
File: lib/NeoESP32RmtHI/src/NeoEsp32RmtHI.S:8-16
Timestamp: 2025-09-02T02:27:39.220Z
Learning: The ESP32 macro is defined when compiling code on all ESP32 variants (ESP32, ESP32-S2, ESP32-S3, ESP32-C3, etc.) in the Arduino framework, providing consistent library compatibility across the entire ESP32 family. For target-specific detection, CONFIG_IDF_TARGET_* macros should be used instead.

Learnt from: CR
Repo: wled/WLED PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-10-05T15:24:05.545Z
Learning: Build at least one hardware environment locally (e.g., `pio run -e esp32dev`) before marking work complete

Learnt from: willmmiles
Repo: wled/WLED PR: 4890
File: lib/NeoESP32RmtHI/include/NeoEsp32RmtHIMethod.h:31-36
Timestamp: 2025-09-02T01:45:58.047Z
Learning: For the NeoEsp32RmtHI driver, RISC-V ESP32-C3 support is currently disabled via bus_wrapper.h rather than compile-time guards, as the maintainer willmmiles is working on resolving underlying nested interrupt issues and prefers to centralize the workaround in one location.

📚 Learning: 2025-10-05T15:24:05.545Z

Learnt from: CR
Repo: wled/WLED PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-10-05T15:24:05.545Z
Learning: Applies to platformio.ini : Use platformio.ini as the single source of truth for hardware build targets and settings

Applied to files:

platformio_override.sample.ini

📚 Learning: 2025-09-02T02:27:39.220Z

Learnt from: willmmiles
Repo: wled/WLED PR: 4890
File: lib/NeoESP32RmtHI/src/NeoEsp32RmtHI.S:8-16
Timestamp: 2025-09-02T02:27:39.220Z
Learning: The ESP32 macro is defined when compiling code on all ESP32 variants (ESP32, ESP32-S2, ESP32-S3, ESP32-C3, etc.) in the Arduino framework, providing consistent library compatibility across the entire ESP32 family. For target-specific detection, CONFIG_IDF_TARGET_* macros should be used instead.

Applied to files:

platformio_override.sample.ini
boards/adafruit_matrixportal_esp32s3.json

📚 Learning: 2025-02-19T12:43:34.199Z

Learnt from: blazoncek
Repo: wled/WLED PR: 4482
File: wled00/udp.cpp:147-149
Timestamp: 2025-02-19T12:43:34.199Z
Learning: ESP8266 and ESP32 platforms have different maximum segment name lengths in WLED, which can cause truncation when syncing segment names between devices. This platform difference affects the user experience when using the segment name sync feature.

Applied to files:

platformio_override.sample.ini

📚 Learning: 2025-09-02T01:45:58.047Z

Learnt from: willmmiles
Repo: wled/WLED PR: 4890
File: lib/NeoESP32RmtHI/include/NeoEsp32RmtHIMethod.h:31-36
Timestamp: 2025-09-02T01:45:58.047Z
Learning: For the NeoEsp32RmtHI driver, RISC-V ESP32-C3 support is currently disabled via bus_wrapper.h rather than compile-time guards, as the maintainer willmmiles is working on resolving underlying nested interrupt issues and prefers to centralize the workaround in one location.

Applied to files:

platformio_override.sample.ini

📚 Learning: 2025-10-20T09:38:51.997Z

Learnt from: blazoncek
Repo: wled/WLED PR: 4995
File: wled00/FX.cpp:5223-5226
Timestamp: 2025-10-20T09:38:51.997Z
Learning: WLED matrices: each dimension (SEG_W, SEG_H) is limited to ≤255; 256 or larger per side is not supported/feasible on ESP32, so effects should assume per-dimension max 255.

Applied to files:

platformio_override.sample.ini

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (20)

GitHub Check: wled_build / Build Environments (usermods)
GitHub Check: wled_build / Build Environments (esp32S3_wroom2)
GitHub Check: wled_build / Build Environments (esp32c3dev)
GitHub Check: wled_build / Build Environments (esp01_1m_full_compat)
GitHub Check: wled_build / Build Environments (esp32dev_debug)
GitHub Check: wled_build / Build Environments (esp32dev)
GitHub Check: wled_build / Build Environments (esp32_eth)
GitHub Check: wled_build / Build Environments (esp8266_2m_160)
GitHub Check: wled_build / Build Environments (esp01_1m_full_160)
GitHub Check: wled_build / Build Environments (esp01_1m_full)
GitHub Check: wled_build / Build Environments (esp8266_2m)
GitHub Check: wled_build / Build Environments (nodemcuv2)
GitHub Check: wled_build / Build Environments (esp32dev_debug)
GitHub Check: wled_build / Build Environments (esp32c3dev)
GitHub Check: wled_build / Build Environments (esp32s3_4M_qspi)
GitHub Check: wled_build / Build Environments (lolin_s2_mini)
GitHub Check: wled_build / Build Environments (usermods)
GitHub Check: wled_build / Build Environments (esp32s3dev_16MB_opi)
GitHub Check: wled_build / Build Environments (esp32_eth)
GitHub Check: wled_build / Build Environments (esp01_1m_full_160)

🔇 Additional comments (2)

platformio_override.sample.ini (1)

576-576: USB_MODE flag correctly commented out per PR objectives.

The removal of ARDUINO_USB_MODE=1 aligns with the PR goal to prevent boot hangs when no USB-CDC is connected. Keeping ARDUINO_USB_CDC_ON_BOOT=1 while omitting the mode flag allows arduino-esp32 to choose a safe default.

boards/adafruit_matrixportal_esp32s3.json (1)

2-34: Build configuration looks appropriate for ESP32-S3 with PSRAM.

Clock speeds (f_cpu=240MHz, f_flash=80MHz), flash mode (qio), and PSRAM support are correctly configured for the Adafruit MatrixPortal ESP32-S3.

boards/adafruit_matrixportal_esp32s3.json

platformio_override.sample.ini

boards/adafruit_matrixportal_esp32s3.json

platformio_override.sample.ini

esp32S3_PSRAM_HUB75: * use 16MB partinion.csv (board has 16MB flash, lets use that) * example how to switch from "compile for small size" to "compile for speed" adafruit_matrixportal_esp32s3: * small reordering of lines * commented out partition for adafruit bootloader, reverted to standard 8MB partitions

SR_DMTYPE=-1 will lead to undefined behavior in AR, because for S3 there is no "default" case in the usermod setup(). It should be sufficient to set pins to "-1" if you want to avoid "pin stealing".

softhack007 · 2025-11-25T13:15:22Z

@DedeHai can you quickly check if your matrixportal still works with the changes from my PR ?
Everything else is tested & works on the boards I have (including 32MB flash partitions) - ready to merge once you give me your "OK".

DedeHai · 2025-11-25T15:19:47Z

works!

DedeHai · 2025-11-25T15:53:31Z

@softhack007 there is one pitfall:
"arduino": { "flash_extra_images": [ [ "0x410000", "variants/adafruit_matrixportal_esp32s3/tinyuf2.bin" ] ] },

this part in the board manager causes an additional flash section to be erased when uploading, wiping the whole FS on every upload. if I remove these lines, config persists.

I am also not sure we should not remove the
"arduino":{ "ldscript": "esp32s3_out.ld", "partitions": "partitions-8MB-tinyuf2.csv" },

part from the board definition. or override them both.

add esp32S3_wroom2 to default build

7dfed58

this board does not run with esp32s3dev_16MB_opi, because it needs "opi_opi" (not qio_opi) memory mode.

buildenv updates for adafruit MatrixPortal S3

d8e2cee

* board.json added to WLED/boards * use partitions file that supports adafruit UF2 bootloader

coderabbitai bot reviewed Nov 22, 2025

View reviewed changes

boards/adafruit_matrixportal_esp32s3.json Show resolved Hide resolved

boards/adafruit_matrixportal_esp32s3.json Show resolved Hide resolved

platformio_override.sample.ini Outdated Show resolved Hide resolved

softhack007 commented Nov 22, 2025

View reviewed changes

boards/adafruit_matrixportal_esp32s3.json Show resolved Hide resolved

softhack007 requested a review from DedeHai November 22, 2025 20:38

softhack007 commented Nov 22, 2025

View reviewed changes

platformio_override.sample.ini Outdated Show resolved Hide resolved

softhack007 added 2 commits November 22, 2025 23:07

fix wrong -D SR_DMTYPE=-1 in platformio_override.sample.ini

d7fd49c

SR_DMTYPE=-1 will lead to undefined behavior in AR, because for S3 there is no "default" case in the usermod setup(). It should be sufficient to set pins to "-1" if you want to avoid "pin stealing".

softhack007 linked an issue Nov 23, 2025 that may be closed by this pull request

[WLED custom build for Adafruit MatrixPortal S3] Unknown board ID adafruit_matrixportal_esp32s3 #5106

Closed

1 task

softhack007 added this to the 0.16.0 candidate milestone Nov 24, 2025

softhack007 merged commit d1c4de2 into main Nov 25, 2025
51 checks passed

softhack007 deleted the s3_wroom2_32MB branch November 25, 2025 15:24

This was referenced Nov 26, 2025

FIX for adafruit portal S3: remove extra flash section #5113

Open

Merge branch 'main' of https://github.com/wled/WLED #5132

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

update for esp32-S3 builds, and support for 32MB Flash #5107

update for esp32-S3 builds, and support for 32MB Flash #5107

Uh oh!

softhack007 commented Nov 22, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Nov 22, 2025 •

edited

Loading

Uh oh!

DedeHai commented Nov 22, 2025 •

edited

Loading

Uh oh!

softhack007 commented Nov 22, 2025

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

softhack007 commented Nov 25, 2025

Uh oh!

DedeHai commented Nov 25, 2025

Uh oh!

Uh oh!

DedeHai commented Nov 25, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

update for esp32-S3 builds, and support for 32MB Flash #5107

update for esp32-S3 builds, and support for 32MB Flash #5107

Uh oh!

Conversation

softhack007 commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Nov 22, 2025 • 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

Pre-merge checks and finishing touches

Uh oh!

DedeHai commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

softhack007 commented Nov 22, 2025

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

softhack007 commented Nov 25, 2025

Uh oh!

DedeHai commented Nov 25, 2025

Uh oh!

Uh oh!

DedeHai commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

softhack007 commented Nov 22, 2025 •

edited

Loading

coderabbitai bot commented Nov 22, 2025 •

edited

Loading

DedeHai commented Nov 22, 2025 •

edited

Loading

DedeHai commented Nov 25, 2025 •

edited

Loading