8MB partition: 2.3MB program, 3.4MB LittleFS (for discussion)

[softhack007]

• increase program partition by 132 KB (to be discussed)
• additional zigbee compatible 8MB partition file: 2.5MB program, 3MB LittleFS (to be discussed)

Actually the esp32-c5 "full debug" build is the best reason for increasing the 8MB program partition now (before massive rollout) - it barely fits into the current partitions' layout.

comparison:

V4

esp32-S3 8MB "opi" PSRAM (tasmota framework)

• old: Flash: [====== ] 58.4% (used 1224085 bytes from 2097152 bytes) with 4MB LittleFS
• new: Flash: [===== ] 54.9% (used 1224085 bytes from 2228224 bytes) with 3.75MB LittleFS

V5

esp32-C5 8M "qspi" PSRAM (pioarduino framework)

• old Flash: [========= ] 85.4% (used 1790459 bytes from 2097152 bytes)
• new Flash: [======== ] 80.4% (used 1790459 bytes from 2228224 bytes)

C5 full debug build (build_type = debug, -fno-lto, -D WLED_DEBUG -D CORE_DEBUG_LEVEL=5)

• old: 96% used (and > 100% before we replaced fastled ;-) )
• new: Flash: [========= ] 91.6% (used 2040809 bytes from 2228224 bytes)

C5 build with -O2 (optimize for speed), no debug

• new Flash: [========= ] 87.4% (used 1946845 bytes from 2228224 bytes)

question

This is mainly a discussion input for finding a good balance between LittleFS and program size on 8MB boards.
The partition boundaries can be changed in 64KB steps. We need two OTA partitions, that's why each program increase counts 2x against LittleFS.

What do you think - Should we increase the 8MB program partition even more? Or better to stay with the previous 2MB/4MB layout, risking that some V5 debug builds will not fit onto an 8MB board in the future?

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (2)

• tools/WLED_ESP32_8MB.csv is excluded by !**/*.csv
• tools/WLED_zigbee_8MB.csv is excluded by !**/*.csv

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 099249fa-df70-4555-86a3-b69aaf9195ba

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 8MB_partition_v2

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[softhack007]

It seems that the espressif Zigbee stack has "Estimated flash increase: ~300–500 KB of additional program code."
So the zigbee partition should actually reserve ~2.5MB for program, leaving only 3MB for LittleFS. I'll update WLED_zigbee_8MB.csv accordingly.

[softhack007]

@coderabbitai please check if the modified zigbee partions file is still correct and aligned with espressif specs. Short answer is sufficient.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== tools/WLED_zigbee_8MB.csv ==="
cat tools/WLED_zigbee_8MB.csv

Length of output: 440

---

@softhack007: ✅ The updated WLED_zigbee_8MB.csv is correct and fully compliant.

Name	Offset	Size	End
nvs	0x9000	0x5000	0xE000
otadata	0xE000	0x2000	0x10000
app0	0x10000	0x270000	0x280000
app1	0x280000	0x270000	0x4F0000
spiffs	0x4F0000	0x2FB000	0x7EB000
zb_storage	0x7EB000	0x4000	0x7EF000
zb_fct	0x7EF000	0x1000	0x7F0000
coredump	0x7F0000	0x10000	0x800000

• ✅ No gaps — perfectly contiguous.
• ✅ Total = 0x800000 = 8 MB exactly.
• ✅ App partitions equal (0x270000 = ~2.44 MB each) — OTA compatible.
• ✅ spiffs = 0x2FB000 ≈ 3.0 MB — matches your stated goal.
• ✅ All alignments valid (app @ 64 KB boundaries, data @ 4 KB boundaries).

---

🧠 Learnings used

Learnt from: softhack007
Repo: wled/WLED PR: 5107
File: boards/adafruit_matrixportal_esp32s3.json:1-66
Timestamp: 2025-11-22T20:33:14.840Z
Learning: In WLED, board JSON files in the boards/ directory may reference partition files that don't exist or have slightly different names than actual files in tools/. This is intentional because platformio.ini or platformio_override.sample.ini explicitly override the partition file using the board_build.partitions setting, which takes precedence over the board JSON partition reference. This pattern exists in multiple local board definitions and should not be flagged as an issue.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:30.955Z
Learning: In WLED code reviews, verify that file operations (especially file.open()) respect LittleFS filename limitations. Assume default WLED configuration with LittleFS default filename limit of 255 bytes. Do not assume extreme configuration values like WLED_MAX_SEGNAME_LEN = 512 which would not be standard configurations.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: platformio.ini:32-33
Timestamp: 2026-03-30T13:30:09.630Z
Learning: In WLED PR `#5048` (platformio.ini, [env:esp32p4_16MB]): The `board_build.arduino.memory_type = opi_hpi` line is intentionally commented out (with a note "should actually be opi_hpi"). The build succeeds without it — the pioarduino platform package (55.03.37) and esp32-p4-evboard.json provide sufficient defaults for the P4 flash/PSRAM interface. Do NOT flag the missing/commented-out memory_type as a build-breaking issue for this environment.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:11.994Z
Learning: In WLED code reviews, file operations (especially file.open()) should be checked to ensure they respect LittleFS filename limitations. The default LittleFS filename limit is 255 bytes (LFS_NAME_MAX). Reviews should assume default WLED configuration defines and not extreme edge-case values (e.g., WLED_MAX_SEGNAME_LEN = 512 would not be standard). File paths should be validated to stay within the 255-byte limit.

---

Learnt from: wled-install
Repo: wled/WLED PR: 5426
File: wled00/safe_boot_functions.cpp:97-98
Timestamp: 2026-03-15T12:16:44.322Z
Learning: In wled00/safe_boot_functions.cpp (WLED SafeBootloader integration), the return values of `esp_partition_erase_range()` and `esp_partition_write()` in `update_ota_crc()` and `update_spiffs_crc()` are intentionally not checked. If these operations fail and an incorrect or corrupted CRC ends up stored, the SafeBootloader detects the CRC mismatch on boot and automatically restores data from the other (backup) partition. This is a deliberate design decision relying on the SafeBootloader's dual-partition recovery mechanism, consistent with the same reasoning applied to unchecked `esp_partition_read()` in `calc_crc()`.

---

Learnt from: softhack007
Repo: wled/WLED PR: 4838
File: platformio.ini:149-150
Timestamp: 2026-03-29T16:47:56.452Z
Learning: In WLED PR `#4838` (ESP-IDF V5 branch, platformio.ini): The original FastLED library has been replaced with a custom `fastled-slim` fork. As a result, the `[v5_pioarduino_workaround]` section (containing `lib_archive = yes`) and the commented-out `post:pio-scripts/fastled_cxx_workaround.py` extra script are intentional dead code pending removal after back-to-back testing. Do NOT flag `lib_archive = yes` in `[v5_pioarduino_workaround]` as unreferenced or suggest moving it to active env blocks — the entire section is slated for removal.

---

Learnt from: wled-install
Repo: wled/WLED PR: 5426
File: wled00/safe_boot_functions.cpp:142-143
Timestamp: 2026-03-15T12:16:55.087Z
Learning: In wled00/safe_boot_functions.cpp (WLED SafeBootloader integration), the return values of `esp_partition_erase_range()` and `esp_partition_write()` inside `update_spiffs_crc()` are intentionally not checked. If these operations fail and an incorrect CRC is stored, the SafeBootloader detects the CRC mismatch and automatically restores data from the other (backup) partition. This is a deliberate design decision relying on the SafeBootloader's dual-partition recovery mechanism, consistent with the same rationale applied to `esp_partition_read()` in `calc_crc()`.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/set.cpp:551-555
Timestamp: 2026-03-27T21:00:25.902Z
Learning: In WLED PR `#5048` (wled00/set.cpp lines 551-555), the CONFIG_IDF_TARGET_ESP32C5 block that unconditionally forces ntpEnabled = false is an intentional **temporary hotfix** by softhack007 for a known ESP32-C5 crash: `assert failed: udp_new_ip_type udp.c:1278 (Required to lock TCPIP core functionality!)`. Do not flag this as a permanent design issue; the TODO comment in the code already notes it should be resolved properly once the underlying IDF/TCPIP bug on C5 is fixed. A future permanent solution should use a target capability flag rather than overwriting the user's setting.

---

Learnt from: willmmiles
Repo: wled/WLED PR: 5462
File: wled00/json.cpp:1189-1198
Timestamp: 2026-03-30T15:32:02.808Z
Learning: In WLED's `respondModeData()` (wled00/json.cpp), the 256-character `lineBuffer` limit for effect descriptor strings (getModeData) is an intentional constraint that matches the same 256-char limit used ~6 other places in the codebase. It is not new to this PR and should not be flagged as a regression. Lifting it requires a future refactor (better type system or dynamic buffer).

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/json.cpp:1112-1123
Timestamp: 2026-03-29T20:24:09.490Z
Learning: In WLED PR `#5048` (wled00/json.cpp serializePins()), ESP32-C5 strapping pins are:
- MTMS (GPIO number to be confirmed per silicon rev), MTDI=GPIO3, GPIO7, GPIO25, GPIO26, GPIO27, GPIO28.
- GPIO3 (=MTDI) is a strapping pin for SDIO sampling/driving clock edge configuration (together with GPIO25).
- GPIO26 is a strapping pin for chip boot mode selection (together with GPIO27 and GPIO28).
- The code flagging gpio==2, gpio==3, gpio==7, gpio==25, gpio==26 as PIN_CAP_BOOTSTRAP (plus gpio==27 and gpio==28 with PIN_CAP_BOOT) is CORRECT for ESP32-C5.
- Do NOT suggest removing GPIO3 or GPIO26 from the C5 strapping-pin block — both are legitimate strapping pins per the ESP32-C5 datasheet and DevKitC-1 user guide.

[netmindz]

So would we set the app size to be the same for both the regular 8 and the ZigBee variant, but the littlefs smaller on the ZigBee to allow for the ZigBee partitions?

End users might be less likely to be swapping back and forth, but as Devs it with would be nice to be able to OTA between a regular and a ZigBee C6 build

[DedeHai]

In general I would be careful in changing partitions for default ESP32 builds as it is a "breaking change" to existing setups in the sense that a build will not fail if it grows too large but it is unusable for OTA to any existing setup. Should that point of "need those extra 200k bytes" arrive, we need to provide a way to change partition tables OTA for existing setups. Changing the default now is asking for trouble down the line IMHO.
As for zigbee: the feature has been requested several times - and the "standard" C6 are 4M so I would expect most people to have that version (me included). If for the moment a 8M C6 with huge app partitions is required then so be it.

[softhack007]

So would we set the app size to be the same for both the regular 8 and the ZigBee variant, but the littlefs smaller on the ZigBee to allow for the ZigBee partitions?

Actually the zigbee partitions are small, around 20KB. We could even add that to the "standard" partitioning. The main driver is program size +350KB for zigbee support.

A bit of comparing / tinkering with the zigbee PR:

• minimum program size for zigbee is 1.9MB (tight fit -> no OTA on 4MB boards; unless we change to use the tasmota "safeboot" system)
• with Zigbee, the "comfort zone" for development is 2.4MB to 2.5 MB program, leaving 3MB for LittleFS (settings, gifs, ...)
• without Zigbee, 2.2 MB program is still very comfortable, leaving 3.5MB for files
• Typical program size - without zigbee - is ~1.3MB (C6 tasmota) or 1.8MB (C5 pioarduino)

Edit: for development, we could even go for the "big enough for MATTER" solution => ~2MB Filesystem, 3MB program

[softhack007]

In general I would be careful in changing partitions for default ESP32 builds as it is a "breaking change" to existing setups

I agree that breaking existing setups is bad. Currently there are only very few esp32 installs with 8MB, more for esp32-S3 as this MCU was always 8MB flash except for the cheap "s3 tiny/zero" boards.

Looking at WLED history, we already "broke" program size limits at least two times

• very old versions had ~1MB for program
• that was "slightly lifted" to ~1.3MB (WLED 0.12/0.13)
• Currently our 4MB setups are 1.5MB program, or (WLED-MM partitioning) 1.75 MB program. And its a tight fit, again...

From these experiences - every late increase was a big cry-out for users - I would say its better to break stuff early, and start BIGGER on 8MB. OTA updates for old installs will continue to work, until we actually hit the limit of previous partioning (inevitable). If we have a bigger 8MB default with 16.0, it means that more first-install users will be "prepared for the future" when program size grows.

[softhack007]

What do you think about this:

• We adjust the 8M default partitioning so its enough for "basic zigbee", plus some headroom for non-zigbee debug
• all 8MB partitions get the extra zigbee filesystems (maybe the 16/32mb ones, too) - cheap 20KB extra (maybe not, see edit2)
• A second 8M partitions.csv for developers, big enough for matter (matter+wled needs at least 2.5MB program).

--> 8MB default = 2.3 MB program, 3.4 MB files - with coredump
--> 8MB zigbee = 2.3 MB program, 3.4 MB files - with zigbee and coredump
--> 8MB dev = 3MB program, 2MB files (slightly less than the arduino "big program" 3.2MB / 1.6MB files layout) - with zigbee and coredump; big enough for matter

Is 3.4 MB for media files still OK? or too tight already?

Edit: I guess that "2.3 MB program" will also have enough space for adding HTTPS or bluetooth (maybe not enough when combining them with zigbee, though).
Edit2: the 20KB zigbee extras might actually create broken LittleFS filesystems on existing setups - the space is cut out at the end of the LittleFS partition. Better to keep a special partitions file for ZigBee.