Skip to content

feat(esp32): add esp32-s3-N4R2 build environment - #150

Merged
jonasniesner merged 1 commit into
OpenDisplay:mainfrom
parkghost:feat/esp32-s3-n4r2-env
Aug 10, 2026
Merged

feat(esp32): add esp32-s3-N4R2 build environment#150
jonasniesner merged 1 commit into
OpenDisplay:mainfrom
parkghost:feat/esp32-s3-n4r2-env

Conversation

@parkghost

@parkghost parkghost commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

Why

The Waveshare ESP32-S3-Zero and the other S3 mini boards built on the
ESP32-S3FH4R2 have no environment they can use. Every existing S3 env is an R8
part with 8 MB or more of flash, and two of those settings are fatal on an R2:

  • PSRAM is quad, not octal. The R8 envs set memory_type = qio_opi /
    psram_type = qspi_opi. An R2 part needs qio_qspi / qspi or PSRAM never
    comes up.
  • 4 MB flash. default_4MB's paired 1.25 MB app slots are too small — this
    firmware is ~1.5 MB with WiFi + BLE. huge_app gives a single 3 MB slot, at
    the cost of OTA.

What

New [env:esp32-s3-N4R2], modelled on esp32-s3-N8R8 with those two changes,
plus:

  • FastEPD left out. It serves only the four large panels on the
    parallel/IT8951 path (ED103TC2 10.3", Inkplate 5 V2, Inkplate 10). Their
    2.6 MB framebuffer does not fit in 2 MB of PSRAM, and the Inkplate ones also
    want a parallel bus this class of board has no pins for. SPI panels go
    through bb_epaper. Worth being precise that this is a PSRAM limit and not a
    flash one: linking FastEPD in builds fine and costs only ~51 KB, 48.5% of the
    slot instead of 46.9%.
  • Registered in .github/firmware-targets.json and in default_envs, so
    neither CI nor a bare pio run silently skips it.

Testing

Built and flashed on a Waveshare ESP32-S3-Zero. The image is 1.47 MB of the
3 MB slot (46.9%), RAM 29.8%. PSRAM comes up and is used — the PIPE reorder
queue and the 16 KB LAN RX buffer both allocate there — and BLE and the
WiFi/LAN transport both work.

@parkghost
parkghost marked this pull request as draft August 10, 2026 13:46
@parkghost
parkghost force-pushed the feat/esp32-s3-n4r2-env branch 3 times, most recently from 998992b to 0cda87e Compare August 10, 2026 13:51
Waveshare ESP32-S3-Zero and the other ESP32-S3FH4R2 mini boards need their
own environment on two counts:

  - PSRAM is quad, not octal. Every other S3 env here is an R8 part and sets
    memory_type = qio_opi / psram_type = qspi_opi; an R2 part must use
    qio_qspi / qspi or PSRAM never comes up.
  - 4 MB flash. huge_app gives one 3 MB app slot (no OTA); default_4MB's
    paired 1.25 MB slots are too small for this firmware.

FastEPD is deliberately omitted: it only serves the parallel/IT8951 panel
path, SPI panels go through bb_epaper, and leaving it out keeps the image
inside 4 MB (1.48 MB / 3 MB used).

Registered in the release matrix and in default_envs, so neither CI nor a
bare `pio run` silently skips it.
@parkghost
parkghost force-pushed the feat/esp32-s3-n4r2-env branch from 0cda87e to 50a2d77 Compare August 10, 2026 13:55
@parkghost
parkghost marked this pull request as ready for review August 10, 2026 13:58
@jonasniesner

Copy link
Copy Markdown
Member

Thank you for you contribution. I will merge the PR after the tests pass. Is this profile for a commercially avaliable board or something custom built?

@jonasniesner
jonasniesner merged commit a1a165e into OpenDisplay:main Aug 10, 2026
13 checks passed
@parkghost

Copy link
Copy Markdown
Contributor Author

Custom built — it is a DIY device, not a commercial product.

The profile is not specific to my one unit, though. The MCU board is an
off-the-shelf Waveshare ESP32-S3-Zero, and the same ESP32-S3FH4R2 part (4 MB
flash + 2 MB quad PSRAM) is what the cheap "S3 Zero" / "S3 Super Mini" boards
are all built on. Only the carrier and the panel wiring are mine — a DEPG0420
4.2" B/W/R over SPI, with panel and pins coming from the runtime device config
as usual.

What pushed me to add an env at all is that none of the existing ones will run
on that part: every S3 profile in the tree is an R8 with 8 MB or more of flash,
so the octal-PSRAM setting leaves PSRAM dead and the partition table does not
fit in 4 MB. Right now there is no firmware in the tree that anyone holding one
of these boards can flash.

@parkghost

Copy link
Copy Markdown
Contributor Author
IMG_20260810_220348 (1) IMG_20260810_220341 (1)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants