We have published a step-by-step guide to flashing WLED on an ESP32-C3 board over USB, setting it up for addressable WS281x LEDs, and syncing it to CheerLights over MQTT. The guide was tested with WLED v16.0.0 on a GLEDOPTO WLED ESP32 Mini.
What You Need
- An ESP32-C3 board. The GPIO pins in the guide (LED on 10, button on 9) are for the GLEDOPTO WLED ESP32 Mini; other boards use different pins.
- A strip or string of addressable WS281x LEDs
- A USB data cable (a charge-only cable will not work)
- Python 3 with
pip, to installesptool
Flash WLED with esptool
For most people, the official web installer at install.wled.me is the way to put WLED on a board. The guide covers the manual esptool method, which helps with scripting, flashing offline, and seeing exactly what happens. That method writes only the app image, so it is for boards already running WLED; use the web installer for a blank chip. The guide walks through finding the COM port, installing esptool, downloading WLED_16.0.0_ESP32-C3.bin, and writing it to the app partition at 0x10000:
python -m esptool --port COM4 --baud 460800 write_flash 0x10000 WLED_16.0.0_ESP32-C3.binReplace COM4 with your port. The guide also covers making sure the board boots the new firmware, configuring the LED output and the button, powering longer strips, and troubleshooting.
Sync WLED to CheerLights
The CheerLights MQTT broker publishes the current color straight to WLED’s standard topics, so there is nothing custom to install. In WLED, open Settings → Sync Interfaces → MQTT, check Enable MQTT, and set:
- Broker: mqtt.cheerlights.com
- Port: 1883, with no username or password
- Device Topic: wled. CheerLights publishes the color to
wled/col, so a per-device topic likewled/xxxxxxnever gets it. - Group Topic: wled/all
Save, then unplug the board and plug it back in. WLED connects to the MQTT broker only at boot. Once it reconnects, pick a color on the CheerLights Discord and your LEDs change with every other CheerLights light around the world.
Read the full guide on GitHub, including a recipe where one pixel follows CheerLights and the rest run an effect, and see CheerLights + WLED for more WLED builds.