ESP02 - Too big for OTA update (workaround by 2-step OTA update with _min build)

[netmindz]

Users are reporting inability to upgrade using the OTA, even when using the .gzip image

Have we pushed the flash usage too close the 100%?

Apparently 8266 can fail for values less than 100% but unclear quite how close you can go

[netmindz]

@coderabbitai - do you have any insight as to how close you can go to the flash usage before the 8622 has issue?

Might this error be due to users having a different partition table Vs our own pio env config

[coderabbitai]

🧩 Analysis chain

Let me first look at the issue for context.

Let me fetch the issue details now.

---

🏁 Script executed:

#!/bin/bash
gh issue view 5576 --repo wled/WLED --json title,body,comments | jq -r '.title, .body, (.comments[] | .body)'

Length of output: 455

---

🏁 Script executed:

#!/bin/bash
gh issue view 5576 --repo wled/WLED --json title,body,comments | jq -r '.title, "\n--- BODY ---", .body, "\n--- COMMENTS ---", (.comments[] | "[\(.author.login)]: \(.body)")'

Length of output: 499

---

Let me search for ESP8266 OTA flash requirements and also check WLED's PlatformIO config.

@netmindz — great questions, both of which have meaningful answers based on how ESP8266 OTA works:

---

1. How close to 100% flash usage before OTA fails on the ESP8266?

There isn't a simple percentage threshold — it's determined by the linker script / partition layout. Here's what actually matters:

OTA is doable only if there's enough room to store the new firmware on the flash before having it replace the old one. For the ESP8266:

• The new sketch is stored in the space between the old sketch and the SPIFFS. On the next reboot, the eboot bootloader checks for commands and the new sketch is then copied over the old one.
• The OTA update path checks ESP.getFreeSketchSpace() and rejects if the incoming binary won't fit. In ESP8266HTTPUpdate, if len > ESP.getFreeSketchSpace(), the update is rejected with [httpUpdate] FreeSketchSpace too low.
• If the binary is more than half the size of the flash, there won't be enough space on the FS to upload the same binary via OTA. This ~50% rule of thumb applies to the OTA region size, not raw total flash — so the exact limit is dictated by the ldscript.

So for a 2MB flash (ESP-02) with WLED's specific linker script, the threshold is: firmware (uncompressed) must be ≤ getFreeSketchSpace(), which is typically around half the configured sketch region. If WLED is now pushing close to or past that boundary, OTA will fail even with .bin.gz (since the ESP8266 still checks the OTA region against the compressed size before decompressing).

---

2. Could this be caused by a different partition table vs. WLED's PIO env config?

Yes, this is very likely a contributing factor. The getFreeSketchSpace() value is entirely determined by the linker script (eagle.flash.Xm.ld) used when the currently running firmware was compiled — not the new one being uploaded. So:

• A user who originally flashed WLED with, say, eagle.flash.2m1m.ld (2MB flash, 1MB SPIFFS) will have a different OTA region size than a user who flashed with WLED's current PIO env config.
• WLED 0.15.x needs a bit more app space than some ancient WLED installation. Usually updating the partition table requires a local USB connection; this is why tools exist to expand app partitions via OTA.
• If WLED's official PIO env specifies a specific ldscript that allocates more space to the sketch area (shrinking the OTA staging area), users on older installs with a different layout may have a smaller getFreeSketchSpace() than what the current WLED binary requires.

Recommended investigation steps:

1. Check what board_build.ldscript (or board_build.flash_size + board_build.filesystem_size) WLED's current PIO esp8266_2m env specifies.
2. Compare this against what previous WLED versions shipped with — if the ldscript changed between versions, users who can't OTA are likely still running under the old layout.
3. A possible mitigation is providing an intermediate "slimmed-down" OTA image that fits in the smaller legacy OTA region, which then reflashes with the correct layout — similar to the two-step OTA approach. This pattern (a small intermediate image that re-partitions, followed by the final firmware) has been used for ESPEasy and similar projects to handle exactly this scenario.

Would you like me to look at the current WLED platformio.ini to check the specific ESP8266 ldscript being used?

[netmindz]

@coderabbitai so if I'm understanding you correctly there is no a fixed partition like esp32 has, so this is why some users reported that they can downgrade to an order version and then upgrade to the latest version

Should we provide a super minimal build env with as much disabled as possible, so the user can flash that first, then use the OTA to flash the normal build?

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check WLED's platformio.ini for ESP8266 related build configs
gh api repos/wled/WLED/contents/platformio.ini --jq '.download_url' | xargs curl -s | grep -A 20 -i "esp8266\|8622\|2m\|ldscript\|minimal\|WLED_RELEASE_1M"

Length of output: 17184

---

@netmindz — yes, your understanding is exactly right, and the minimal build idea is a proven approach. Here's the full picture:

---

Why the ESP8266 is different from ESP32

The ESP8266 has no fixed partition table binary. Instead, the layout is entirely determined by the linker script (ldscript) baked into the running firmware. The _FS_start symbol is a linker-resolved address, and getFreeSketchSpace() computes:

OTA staging size = _FS_start − (sketch_start + current_sketch_size)

So the OTA staging area is the gap between the end of the currently running sketch and the start of SPIFFS. This is the key: it's dynamic based on how large the running firmware is.

From the platformio.ini, env:esp8266_2m uses ldscript_2m512k (eagle.flash.2m512.ld):

• ~1019 KB sketch area
• 512 KB SPIFFS at the top
• OTA staging = 512KB_boundary − current_sketch_end

If the current WLED binary is 950 KB, the staging area is only ~69 KB — nowhere near enough to OTA a new 1000+ KB binary.

---

Why downgrade → upgrade works

When a user OTAs to an older/smaller WLED (say 600 KB), it fits in whatever small gap remains. Now the running sketch is only 600 KB, so the new staging gap becomes much larger (~419 KB in the example above), and the full new binary can then be OTA'd in the second step.

---

The minimal build idea — yes, absolutely do this

This is exactly the pattern tasmota-minimal.bin is a specialised build to subsequently allow OTA uploads. Tasmota even documents the size target: to ensure that there is enough memory available to flash the firmware, it is best to keep the total size as small as possible, and definitely under 625K total to ensure OTA updates are possible.

If a binary build is larger than the available free flash program space, the device needs to first install the minimal version to make more space. To have this work via the web server OTA process, the minimal binary is placed alongside the full binary.

For WLED, a proposed env:esp8266_2m_ota_bridge or env:esp8266_minimal could disable as much as possible. Based on what's already in the platformio.ini, the following flags could be stacked:

[env:esp8266_2m_ota_bridge]
extends = env:esp8266_2m
build_flags = ${common.build_flags} ${esp8266.build_flags}
  -D WLED_RELEASE_NAME=\"ESP02_mini\"
  -D WLED_DISABLE_PARTICLESYSTEM2D
  -D WLED_DISABLE_PARTICLESYSTEM1D
  -D WLED_DISABLE_PIXELFORGE
  -D WLED_DISABLE_LOXONE
  -D WLED_DISABLE_ALEXA
  -D WLED_DISABLE_HUESYNC
  -D WLED_DISABLE_INFRARED
  -D WLED_DISABLE_WEBSOCKETS
  ; strip effects down to a bare minimum
  -D WLED_MAX_BUSSES=1
  -D WLED_PS_DONT_REPLACE_FX

The goal is to get it under ~450–500 KB — small enough to fit in even the tightest staging gap on a device that's been running a maxed-out WLED binary.

---

Important nuances to be aware of

1. Same ldscript required: The bridge build must use the same ldscript_2m512k as the full build. If the ldscript changes between bridge and full build, SPIFFS starts at different addresses and things break.
2. Don't leave users on the minimal build: It should be clearly documented as a one-step intermediate, not a usable build. Note the Tasmota caution: Do not install only tasmota-minimal.bin but upgrade to full, working firmware.
3. Auto-detection opportunity: WLED's OTA handler could proactively check ESP.getFreeSketchSpace() and warn users (or even redirect them to the minimal build URL) before the update fails silently.

Would you like me to look at the specific WLED OTA update code to see where that check could be added, or help draft the minimal build env more precisely?

[softhack007]

WLED/platformio.ini

Lines 431 to 435 in 665d66f

	[env:esp8266_2m_min]
	;; Minimal-feature build for ESP02 (2MB flash).
	;; Use this to recover from a failed OTA: flash via serial, then OTA-upload the regular esp8266_2m binary.
	;; OTA is intentionally kept enabled. All other optional features are stripped to minimise binary size.
	extends = esp8266

The buildenv description is totally misleading (written on "stupid AI day" 😜 ).
If a user can flash via serial, then why first upload a "small OTA-only" firmware, instead of simply flashing the correct image via serial?

What I remember about 8266 OTA is that the "OTA partition" is actually FlashSize - LittleFSPartitionSize - ProgramSize . So in contrast to esp32, its not a fixed size, but the available OTA size varies depending on the running firmware image.

This implies that the esp8266_2m_min firmware is a one-time solution for boards where updating via USB is not an option. "OTA image too big" errors will re-appear on the next OTA update. And its not avoidable, unless we permanently remove features from 8266, or shrink the filesystem from 512 Kb to 128Kb like the "1MB" firmware.

But reducing the filesystem size means that users will see errors when frequently saving presets (file grows beyond the 128Kb limits), and that advanced features will not be possible - for example "config backups and auto-rollback", "Pixelforge multi-tool", and "custom fonts for scrolling text".

The need for "2-step OTA" on some 8266 with 1MB or 2MB flash is nothing new, see https://kno.wled.ge/basics/install-binary/#flashing-method-4-ota-update . We were lucky that in the past, a compressed firmware (.bin.gz) was small enough so 8266 could store the running image + OTA file in flash. Now it appears that the 2MB image has grown, and the compressed firmaware is still too big.

see also

• Cant update some of my 8266 controllers (might be due to small flash size) #5363
• WLED_0.14.0-b3 binary too large for OTA updates of 2M ESP8266 boards (e.g. Athom devices) #3257
• esp02.bin.gz is missing from 0.14.0-b6 #3390
• Esp8266-01 #4002
• OTA update for 1M flash size? #2040

[softhack007]

@coderabbitai there is a potential problem with the new minimal ESP02 firmware. If users trigger saving/writing the cfg.json file, then user settings for removed features might be lost.

Please check if any of the removed/disabled features also prevent that configuration settings for that feature will be wriiten to cfg.json.

WLED/platformio.ini

Lines 431 to 451 in 665d66f

	[env:esp8266_2m_min]
	;; Minimal-feature build for ESP02 (2MB flash).
	;; Use this to recover from a failed OTA: flash via serial, then OTA-upload the regular esp8266_2m binary.
	;; OTA is intentionally kept enabled. All other optional features are stripped to minimise binary size.
	extends = esp8266
	board = esp_wroom_02
	board_build.ldscript = ${common.ldscript_2m512k}
	build_flags = ${common.build_flags} ${esp8266.build_flags} -D WLED_RELEASE_NAME=\"ESP02_min\"
	-D WLED_DISABLE_ALEXA
	-D WLED_DISABLE_HUESYNC
	-D WLED_DISABLE_INFRARED
	-D WLED_DISABLE_MQTT
	-D WLED_DISABLE_ADALIGHT
	-D WLED_DISABLE_LOXONE
	-D WLED_DISABLE_WEBSOCKETS
	-D WLED_DISABLE_ESPNOW
	-D WLED_DISABLE_2D
	-D WLED_DISABLE_PARTICLESYSTEM1D
	-D WLED_DISABLE_PARTICLESYSTEM2D
	-D WLED_DISABLE_PIXELFORGE
	-D WLED_DISABLE_IMPROV_WIFISCAN

[coderabbitai]

🧩 Analysis chain

Let me inspect the build flags and the config serialization code to check for this issue.

---

🏁 Script executed:

#!/bin/bash
# Fetch platformio.ini lines 431-451
gh api repos/wled/WLED/contents/platformio.ini --jq '.download_url' | xargs curl -s | sed -n '425,460p'

Length of output: 1450

---

🏁 Script executed:

#!/bin/bash
# Find cfg.cpp or similar config serialization files
gh api "repos/wled/WLED/git/trees/665d66f45eba17b42a30d99689430b7297ff2559?recursive=1" --jq '.tree[] | select(.path | test("cfg|config|json"; "i")) | .path' | head -30

Length of output: 966

---

🏁 Script executed:

#!/bin/bash
# Find source files in wled00
gh api "repos/wled/WLED/git/trees/665d66f45eba17b42a30d99689430b7297ff2559?recursive=1" --jq '.tree[] | select(.path | startswith("wled00/")) | .path'

Length of output: 6002

---

🏁 Script executed:

#!/bin/bash
# Fetch cfg.cpp and grep for all DISABLE_ ifdef guards
BASE="https://raw.githubusercontent.com/wled/WLED/665d66f45eba17b42a30d99689430b7297ff2559"
curl -s "$BASE/wled00/cfg.cpp" | grep -n "WLED_DISABLE\|ifndef WLED_DISABLE\|ifdef WLED_DISABLE\|endif" | head -80

Length of output: 1336

---

🏁 Script executed:

#!/bin/bash
BASE="https://raw.githubusercontent.com/wled/WLED/665d66f45eba17b42a30d99689430b7297ff2559"
# Also check xml.cpp for similar guards (xml.cpp often handles settings serialization)
curl -s "$BASE/wled00/xml.cpp" | grep -n "WLED_DISABLE\|ifndef WLED_DISABLE\|ifdef WLED_DISABLE\|endif" | head -80

Length of output: 726

---

🏁 Script executed:

#!/bin/bash
BASE="https://raw.githubusercontent.com/wled/WLED/665d66f45eba17b42a30d99689430b7297ff2559"
CFG=$(curl -s "$BASE/wled00/cfg.cpp")

echo "=== ALEXA section (around line 623) ==="
echo "$CFG" | sed -n '618,665p'

echo ""
echo "=== MQTT section (around line 630) ==="
echo "$CFG" | sed -n '626,660p'

echo ""
echo "=== HUESYNC section (around line 644) ==="
echo "$CFG" | sed -n '640,665p'

echo ""
echo "=== INFRARED section (around line 447) ==="
echo "$CFG" | sed -n '442,465p'

echo ""
echo "=== 2D section (around line 953) ==="
echo "$CFG" | sed -n '948,975p'

echo ""
echo "=== ESPNOW section (around line 858) ==="
echo "$CFG" | sed -n '852,870p'

echo ""
echo "=== ALEXA read section (around line 852) ==="
echo "$CFG" | sed -n '845,865p'

echo ""
echo "=== MQTT read section (around line 1162) ==="
echo "$CFG" | sed -n '1155,1200p'

Length of output: 8648

---

🏁 Script executed:

#!/bin/bash
BASE="https://raw.githubusercontent.com/wled/WLED/665d66f45eba17b42a30d99689430b7297ff2559"
XML=$(curl -s "$BASE/wled00/xml.cpp")

echo "=== ALEXA section xml (around line 527) ==="
echo "$XML" | sed -n '522,542p'

echo ""
echo "=== MQTT section xml (around line 536) ==="
echo "$XML" | sed -n '530,560p'

echo ""
echo "=== HUESYNC section xml (around line 557) ==="
echo "$XML" | sed -n '552,590p'

echo ""
echo "=== INFRARED section xml (around line 459) ==="
echo "$XML" | sed -n '454,468p'

echo ""
echo "=== ESPNOW section xml (around line 279) ==="
echo "$XML" | sed -n '274,295p'

echo ""
echo "=== 2D section xml (around line 721) ==="
echo "$XML" | sed -n '716,750p'

Length of output: 8345

---

🏁 Script executed:

#!/bin/bash
BASE="https://raw.githubusercontent.com/wled/WLED/665d66f45eba17b42a30d99689430b7297ff2559"
CFG=$(curl -s "$BASE/wled00/cfg.cpp")

echo "=== WEBSOCKETS in cfg.cpp ==="
echo "$CFG" | grep -n "WEBSOCKET\|websocket\|ws\b" | head -20

echo ""
echo "=== ADALIGHT in cfg.cpp ==="
echo "$CFG" | grep -n "ADALIGHT\|adalight\|serial\|Serial\b" | head -20

echo ""
echo "=== LOXONE in cfg.cpp ==="
echo "$CFG" | grep -n "LOXONE\|loxone\|lx\b" | head -20

echo ""
echo "=== PIXELFORGE in cfg.cpp ==="
echo "$CFG" | grep -n "PIXELFORGE\|pixelforge\|pf\b" | head -20

echo ""
echo "=== IMPROV in cfg.cpp ==="
echo "$CFG" | grep -n "IMPROV\|improv" | head -20

echo ""
echo "=== PARTICLESYSTEM in cfg.cpp ==="
echo "$CFG" | grep -n "PARTICLE\|particle" | head -20

Length of output: 1029

---

@softhack007 — confirmed, your concern is valid. Here is a precise breakdown of which disabled features will cause cfg.json data loss if the user saves config while running the minimal build, and which are safe.

---

⚠️ Features that WILL cause cfg.json data loss

These are guarded by #ifndef WLED_DISABLE_* in both the serializeConfig() write path and the deserializeConfig() read path in cfg.cpp. If the minimal firmware saves cfg.json, those JSON keys are simply omitted — and when the full firmware later loads the file, it falls back to compile-time defaults.

Disabled flag	Config keys lost from cfg.json
WLED_DISABLE_ALEXA	alexaEnabled, alexaInvocationName, macroAlexaOn, macroAlexaOff, alexaNumPresets
WLED_DISABLE_MQTT	mqttEnabled, broker, port, user, password, client ID, device/group topics, retainMqttMsg
WLED_DISABLE_HUESYNC	huePollingEnabled, huePollLightId, huePollIntervalMs, apply-on/bri/col flags, hueIP[4]
WLED_DISABLE_INFRARED	irPin, irEnabled (note: irApplyToAllSelected is outside the guard and is always saved — safe)
WLED_DISABLE_2D	Entire matrix panel layout (strip.panel[] — bottom/right/vertical/serpentine/x/y/h/w per panel)
WLED_DISABLE_ESPNOW	enableESPNow, linked_remotes[]

---

✅ Features that are safe (no cfg.json entries)

These flags have no guarded entries in cfg.cpp — disabling them does not affect what gets written to cfg.json:

Disabled flag	Reason it's safe
WLED_DISABLE_WEBSOCKETS	No config state persisted to cfg.json
WLED_DISABLE_ADALIGHT	serialBaud is always written (not guarded by this flag)
WLED_DISABLE_LOXONE	No config state in cfg.json
WLED_DISABLE_PIXELFORGE	No config state in cfg.json
WLED_DISABLE_IMPROV_WIFISCAN	No config state in cfg.json
WLED_DISABLE_PARTICLESYSTEM1D/2D	Effect-only flags, no cfg.json entries

---

Implications for the minimal build

The scenario that triggers the data loss is: user flashes esp8266_2m_min via serial → opens the WLED UI → makes any change that triggers a config save (e.g. changes LED count, renames the device, etc.) → the cfg.json is rewritten without the MQTT/Alexa/Hue/IR/2D/ESPNow sections → user OTAs to the full esp8266_2m → those settings are gone.

Possible mitigations worth considering:

1. Document the risk prominently: the build env comment already says "flash via serial, then OTA-upload the regular binary" — it could add "do not change any settings while running this build."
2. Read-only config mode: add a compile-time flag (e.g. WLED_READONLY_CONFIG) that disables the config write path entirely when running the minimal build — settings pages would still be viewable but the Save button would be disabled or show a warning.
3. Preserve-unknown-keys approach: modify serializeConfig() to first load the existing cfg.json, then overlay only the keys the minimal build knows about, leaving unknown/disabled keys untouched. This is the most robust fix but requires care with the ArduinoJson document lifecycle.