From 50a2d770bb7d8a1ab0fbbeb2570d5862954d62fc Mon Sep 17 00:00:00 2001
From: Brandon <parkghost@gmail.com>
Date: Mon, 10 Aug 2026 17:06:34 +0800
Subject: [PATCH] feat(esp32): add esp32-s3-N4R2 build environment

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.
---
 .github/firmware-targets.json |  9 +++++++++
 platformio.ini                | 23 +++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/.github/firmware-targets.json b/.github/firmware-targets.json
index 1db52be..76678ad 100644
--- a/.github/firmware-targets.json
+++ b/.github/firmware-targets.json
@@ -48,6 +48,15 @@
       "flash_freq": "80m",
       "bootloader_offset": "0x0000"
     },
+    {
+      "env": "esp32-s3-N4R2",
+      "family": "esp32",
+      "chip": "esp32-s3",
+      "flash_size": "4MB",
+      "flash_mode": "dio",
+      "flash_freq": "80m",
+      "bootloader_offset": "0x0000"
+    },
     {
       "env": "esp32-s3-N32R8",
       "family": "esp32",
diff --git a/platformio.ini b/platformio.ini
index bb77f4f..effae4e 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -48,6 +48,7 @@ default_envs =
 	esp32-c3-N16
 	esp32-c6-N4
 	esp32-N4
+	esp32-s3-N4R2
 
 [env]
 lib_deps =
@@ -249,6 +250,28 @@ board_upload.maximum_ram_size = 327680
 board_upload.flash_size = 8MB
 monitor_speed = 115200
 
+; ESP32-S3 N4R2 -- 4 MB flash + 2 MB quad PSRAM (Waveshare ESP32-S3-Zero and the
+; other S3 mini boards built on ESP32-S3FH4R2).
+[env:esp32-s3-N4R2]
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.39/platform-espressif32.zip
+framework = arduino
+build_flags =
+  -DTARGET_ESP32
+  -DOPENDISPLAY_ENABLE_WIFI  ; LAN transport + ROM tinfl. Set ONLY on -DBOARD_HAS_PSRAM envs (src/wifi_service.h)
+  -DOPENDISPLAY_ZLIB_USE_HEAP_WINDOW=1
+  -DBOARD_HAS_PSRAM
+  -DARDUINO_USB_MODE=1
+  -DARDUINO_USB_CDC_ON_BOOT=1
+  -DCONFIG_FREERTOS_WATCHDOG_TIMEOUT_S=120
+board_build.filesystem = littlefs
+board = esp32-s3-devkitc-1
+board_build.partitions = huge_app.csv
+board_build.arduino.memory_type = qio_qspi
+board_build.psram_type = qspi
+board_build.usb_mode = hardware
+board_upload.flash_size = 4MB
+monitor_speed = 115200
+
 [env:esp32-s3-N32R8]
 platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.39/platform-espressif32.zip
 framework = arduino