Skip to content

Instructions for installing WLED on ESP32-C3 #300

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

Open
chrimbo wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Instructions for installing WLED on ESP32-C3 #300

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7caa8b4
Instructions for installing WLED on ESP32-C3
chrimbo Jan 14, 2026
711d79b
Add table for different ESP32 bootloaders
chrimbo Jan 14, 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
15 changes: 11 additions & 4 deletions docs/basics/install-binary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,17 @@ esptool.py write-flash 0x0 ./WLED_XXX.bin

#### ESP32

Firstly, flash the version 4 bootloader file, which you can find [here](https://github.com/Aircoookie/WLED/releases/download/v0.13.1/esp32_bootloader_v4.bin).
This step only has to be done once, to update afterwards the bootloader does not have to be re-installed.
Unlike the ESP8266, the ESP32 requires a bootloader to be installed before WLED can be flashed. The exact bootloader depends on the specific ESP32 variant being used. Below you will find a list of bootloader links for the supported ESP32 models.

| Model | Bootloader |
|---|---|
ESP32 | [Bootloader Version 4](https://github.com/Aircoookie/WLED/releases/download/v0.13.1/esp32_bootloader_v4.bin)
Copy link
Member

@softhack007 softhack007 Feb 3, 2026

Choose a reason for hiding this comment

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

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.

ESP32-C3 | [Bootloader Version 2](https://github.com/wled/WLED-WebInstaller/raw/refs/heads/master/bin/Release/release_0_15_3/esp32-c3_bootloader_v2.bin)
ESP32-S2 | [Bootloader S2](https://github.com/wled/WLED-WebInstaller/raw/refs/heads/master/bin/Release/release_0_15_3/bootloader_s2.bin)
ESP32-S3 | [Booloader S3](https://github.com/wled/WLED-WebInstaller/raw/refs/heads/master/bin/Release/release_0_15_3/bootloader_s3.bin)
Copy link
Member

@softhack007 softhack007 Feb 3, 2026

Choose a reason for hiding this comment

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

@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).

Copy link
Collaborator

@DedeHai DedeHai Feb 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

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.


```bash
esptool.py write-flash 0x0 ./esp32_bootloader_v4.bin
esptool.py write-flash 0x0 ./esp32_bootloader_xx.bin
Copy link
Member

@softhack007 softhack007 Feb 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

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

```

Now you can flash the actual firmware binary. Keep in mind the bootloader needs to have a flash offset of 0, but the firmware 0x10000.
Expand All @@ -48,14 +54,15 @@ esptool.py write-flash 0x10000 ./WLED_XXX.bin

When esptool.py says `Connecting...`, some ESP32 boards require you to hold the boot button (to the right of the USB port) for a few seconds

- If you experience issues, run this command before trying `write_flash` again (Note: this will erase all settings stored on the ESP!)
- If you experience issues, run this command before trying `write-flash` again (Note: this will erase all settings stored on the ESP!)

```bash
esptool.py erase-flash
```

If you have a MagicHome controller, here is a [good video tutorial](https://www.youtube.com/watch?v=qgBAU39v07k) on how to flash it.


### ESP8266 Flashing method 3: [ESP Home Flasher](https://github.com/esphome/esphome-flasher/releases) tool

!!! warning
Expand Down