Skip to content

Add esp8266_2m_min: minimal ESP02 build for OTA recovery #5577

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
netmindz merged 3 commits into from
May 7, 2026
+23 −0
Merged

Add esp8266_2m_min: minimal ESP02 build for OTA recovery #5577

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8935997
Initial plan
Copilot May 7, 2026
59c5991
Add esp8266_2m_min minimal build env for ESP02 OTA recovery
Copilot May 7, 2026
367d64f
no need to build esp8266_2m_min for PRs
netmindz May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/platformio_release.ini.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
[platformio]
default_envs = nodemcuv2
esp8266_2m
esp8266_2m_min
esp01_1m_full
nodemcuv2_160
esp8266_2m_160
Expand Down
22 changes: 22 additions & 0 deletions platformio.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -428,6 +428,28 @@ build_flags = ${common.build_flags} ${esp8266.build_flags} -D WLED_RELEASE_NAME=
-D WLED_DISABLE_PARTICLESYSTEM2D
custom_usermods = audioreactive

[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.
Copy link
Copy Markdown
Member

@willmmiles willmmiles May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It really is stupid AI day -- this comment is just plain incorrect. Flashing a smaller program binary (serial or otherwise) will not allow you to OTA the "full" build later -- it's the partition map that matters. The full build is still too big (even compressed) to fit in the available OTA space with ldscript_2m512k.

We have essentially two options:

  • Repartition to a smaller data partition to leave enough space for larger OTAs. 2m256k or 2m128k are both long term safe -- the uncompressed program binary is capped at 1MB, so with compression it should always fit in 768k. Of course, by repartitioning, existing devices would need to be reconfigured from scratch.
  • Produce smaller binaries by disabling features that fit in the existing OTA areas (as is done here, though with incorrect comments).

Likely we want to do both...

Copy link
Copy Markdown
Collaborator

@DedeHai DedeHai May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It really is stupid AI day -- this comment is just plain incorrect. Flashing a smaller program binary (serial or otherwise) will not allow you to OTA the "full" build later

@willmmiles I would have thought so too but users report this to work for some reason:
https://www.reddit.com/r/WLED/comments/1t625n2/comment/okhfmch/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button

Copy link
Copy Markdown
Member

@netmindz netmindz May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think for version 17, if we are still going to support such limited hardware as the ESP02, then i think we just need to accept it will be two-step upgrade for users, possibly with a minimal image for stage 1 that is even more stripped back / optimised for this use.

This is preferable I would say to just pulling more and more features as the core of WLED grows in size

;; 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

[env:esp01_1m_full]
extends = esp8266
board = esp01_1m
Expand Down
Loading