Instructions for installing WLED on ESP32-C3

[chrimbo]

Added instructions specifically for ESP32-C3, as the procedure for ESP32 does not work.

Summary by CodeRabbit

• Documentation
  • Updated ESP32 installation guide with clarified bootloader requirements. Added a reference table providing variant-specific bootloader downloads for ESP32, ESP32-C3, ESP32-S2, and ESP32-S3 models.

[DedeHai]

thanks, but why duplicate the whole text block just to add a different link to the bootloader? I think a better way would be to just add a list on top with links to all bootloaders (maybe exempt the S3 as that booloader is highly hardware specific). I am also not sure the ESP32 instructions hold for WROVER.
@lost-hope can you comment on which bootloader works with which hardware?

[chrimbo]

You're right. I started to add a section for 0.16 alpha of WLED, which requires 2 additional files to be flashed and then found out that for the current release only the right bootloader was needed.
NVM, I looked up the different models and added a table for the variants.

Edit: TBF, I just saw that for S2 and S3 theres an additional partitions file that needs to be flashed beforehand. I'm not even sure if it is necessary atm for the C3, as with version 0.16 there is a partitions file for C3 (along with a 4th file (bootapp))

[softhack007]

as we are modernizing the part - its time to remove the old "aircoookie esp32 bootloader", and replace with a URL to the file from WebInstaller.

[softhack007]

@lost-hope I think one bootloader is not enough for S3, correct?
There should be different bootloaders for the different flash access modes (dio, dio_qspi, qio, qio_qspi, qio_opi, opi_opi).

[DedeHai]

C3 is the same, a DIO bootloader will bootloop on a QIO firmware (it might work the other way around, not sure)
Edit: the bootloader from the installer for C3 is DIO, that is why an OTA to QIO V 0.16 will bootloop and auto-revert.

[softhack007]

sorry not correct either. Bootloader offsets are different for each board, see wled/WLED#5064, and https://github.com/wled/WLED-WebInstaller/blob/master/bin/nightly/manifest.json .

Edit: It seems that the "aircoookie V4" bootloader is a special case (combined bootloader), so its flashed at 0x0 although the bootloader for classic esp32 is located at 0x1000

[softhack007]

Edit: TBF, I just saw that for S2 and S3 theres an additional partitions file that needs to be flashed beforehand. I'm not even sure if it is necessary atm for the C3, as with version 0.16 there is a partitions file for C3 (along with a 4th file (bootapp))

To clarify the confusion:

• there are always 4 files needed: bootloader, partitions, boot_app0, WLED
• some "bootloader.bin" files are so-called "combined bootloaders" that include bootloader.bin, partitions.bin and boot_app0.bin in one file.
• when having a "combined bootloader", you only need to flash two files - bootloader and WLED. But it never hurts to also flash the correct partitions.bin (address 0x8000) after flashing bootloader.

[coderabbitai]

Walkthrough

Documentation update for ESP32 flashing instructions clarifies bootloader requirements by replacing generic guidance with a variant-specific table containing download URLs for ESP32 models (v4, C3 v2, S2, S3) and updating the example command placeholder accordingly.

Changes

Cohort / File(s)	Summary
ESP32 Flashing Documentation docs/basics/install-binary.md	Added bootloader requirement clarification and model-to-bootloader mapping table with download URLs for ESP32 variants; updated example command from hardcoded v4 filename to variant placeholder; added formatting blank line.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title specifically mentions ESP32-C3 installation, but the changeset updates bootloader documentation for multiple ESP32 variants (ESP32, ESP32-C3, ESP32-S2, ESP32-S3), making the title only partially representative of the main change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/basics/install-binary.md (1)

39-53: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

ESP32-C3/S2/S3 flashing steps likely incomplete (partitions/boot_app0 not mentioned).

The doc currently says “install a bootloader” (Lines 39-47) and then instructs flashing:

• bootloader at offset 0x0 (Line 52)
• firmware at 0x10000 (Line 52)

But for ESP32-C3/S2/S3, flashing may also require partitions.bin and boot_app0.bin unless the downloaded “bootloader” is a combined bootloader that already bundles them (this was discussed in the PR thread history you included).

As written, users following this section may end up with a device that doesn’t boot / reverts / fails to mount storage for variants that need those extra files.

Please add a short conditional note like:

• “If your download is a combined bootloader, flash bootloader + firmware.”
• “If it’s not combined, also flash partitions.bin (typically at 0x8000) and boot_app0 (offset varies by chip/format) before the firmware.”
  And ideally clarify which of the provided URLs are combined vs not.

If you want, I can draft the exact wording once you confirm which of those four URLs correspond to combined images.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/basics/install-binary.md` around lines 39 - 53, Update the ESP32
bootloader section to warn about combined vs split images and include flashing
offsets for missing blobs: state that esp32_bootloader_v4.bin,
esp32-c3_bootloader_v2.bin, bootloader_s2.bin and bootloader_s3.bin may be
either combined or split; give two short conditional instructions—“If the
downloaded bootloader is a combined image, flash only bootloader at 0x0 and
firmware at 0x10000” and “If it is not combined, also flash partitions.bin
(typically at 0x8000) and boot_app0.bin (chip/format-dependent) before flashing
the firmware” —and mark which of the four listed URLs are combined vs split (or
add a TODO note to confirm and link to the correct combined/split artifacts).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@docs/basics/install-binary.md`:
- Around line 39-53: Update the ESP32 bootloader section to warn about combined
vs split images and include flashing offsets for missing blobs: state that
esp32_bootloader_v4.bin, esp32-c3_bootloader_v2.bin, bootloader_s2.bin and
bootloader_s3.bin may be either combined or split; give two short conditional
instructions—“If the downloaded bootloader is a combined image, flash only
bootloader at 0x0 and firmware at 0x10000” and “If it is not combined, also
flash partitions.bin (typically at 0x8000) and boot_app0.bin
(chip/format-dependent) before flashing the firmware” —and mark which of the
four listed URLs are combined vs split (or add a TODO note to confirm and link
to the correct combined/split artifacts).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3450df24-bf12-4fb1-8975-260a93208243

📥 Commits

Reviewing files that changed from the base of the PR and between b29b482 and 9a14638.

📒 Files selected for processing (1)

• docs/basics/install-binary.md

[softhack007]

⚠️ Outside diff range comments (1)

docs/basics/install-binary.md (1)> 39-53: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

ESP32 (incl. -C3/S2/S3) flashing steps likely incomplete (partitions/boot_app0 not mentioned).
The doc currently says “install a bootloader” (Lines 39-47) and then instructs flashing:

• bootloader at offset 0x0 (Line 52)
• firmware at 0x10000 (Line 52)

But for ESP32 (and -C3/S2/S3), flashing may also require partitions.bin and boot_app0.bin unless the downloaded “bootloader” is a combined bootloader that already bundles them (this was discussed in the PR thread history you included).
As written, users following this section may end up with a device that doesn’t boot / reverts / fails to mount storage for variants that need those extra files.
Please add a short conditional note like:

• “If your download is a combined bootloader, flash bootloader + firmware.”
• “If it’s not combined, also flash partitions.bin (typically at 0x8000) and boot_app0 (offset varies by chip/format) before the firmware.”
  And ideally clarify which of the provided URLs are combined vs not.

I agree this should be added.