Build Your First CheerLights Light with WLED

Your first CheerLights light is an LED strip that shows the same color as every other CheerLights light in the world. You put WLED, firmware that drives LED strips, on a small ESP32 board, connect it to your Wi-Fi, and point it at the CheerLights MQTT broker, the server that sends out each new color. There is no code to write. When it works, someone picks a color on the CheerLights Discord and your strip changes with everyone else’s.

These steps were tested with WLED v16.0.0 on a GLEDOPTO WLED ESP32 Mini, an ESP32-C3 controller. Other ESP32 boards were not tested with this guide; they wire the LED data to a different pin, which step 4 covers.

What You Need

• An ESP32 board that runs WLED, such as the GLEDOPTO WLED ESP32 Mini (ESP32-C3)
• A strip or string of addressable WS281x LEDs (5 V), such as ALITOVE WS2811 12 mm diffused pixels (a string of 50)
• A USB cable that carries data, not only power
• A computer with desktop Chrome or Edge, to install WLED
• A 2.4 GHz Wi-Fi network. ESP32-C3 boards do not connect to 5 GHz.

As an Amazon Associate I earn from qualifying purchases.

1. Connect the LEDs

Connect the strip’s 5 V, ground, and data wires to the board. The board’s ground and the strip’s ground must be connected, or the data signal does not work. Note which GPIO pin (a numbered input/output pin) the data wire goes to; you need it in step 4. Printed pin labels vary between boards, so check your board’s pinout for the GPIO number.

2. Install WLED

Some controllers come with WLED already installed. Power yours up: if a Wi-Fi network named WLED-AP appears, skip to step 3.

1. Plug the board into your computer with the USB cable.
2. Open install.wled.me in desktop Chrome or Edge.
3. Pick the latest version, click Install, and choose your board’s COM port (the serial port the board shows up as).

If the installer finds no device, your computer may need the driver for the board’s USB chip (CP2102 or CH34x; the installer links to both), or the cable may be charge-only.

3. Connect WLED to Your Wi-Fi

1. On your phone or computer, join the Wi-Fi network WLED-AP with the password wled1234.
2. Open http://4.3.2.1 in a browser.
3. Open Settings → WiFi & Network, enter your Wi-Fi name and password, and save.

The board restarts and joins your network. Rejoin your own Wi-Fi, then open WLED at http://wled.local. If that does not load, find the board’s IP address in your router’s device list or the WLED app, and open that.

4. Tell WLED About Your LEDs

Open Settings → LED & Hardware (older versions of WLED call it LED Preferences). In the Hardware setup section, set:

• LED type: WS281x
• Length: the number of LEDs on your strip
• GPIO: the data pin from step 1. It is 10 on the GLEDOPTO WLED ESP32 Mini; WLED’s default for ESP32 boards is 16.
• Color Order: WLED’s default, GRB, is right for WS2812 LEDs. Many WS2811 pixels need RGB.

If the LEDs run from USB power, scroll to Automatic Brightness Limiter and set Maximum Current to about 400 mA. WLED then dims the LEDs to stay under that limit, so they do not pull more power than USB gives and reset the board (a brownout). Save, then turn the LEDs on from WLED’s main page and pick a color. The strip should show it.

5. Join CheerLights

The CheerLights broker publishes every new color to the topic wled/col. A topic is a named channel on the broker, and WLED listens on the topics that start with its Device Topic. Open Settings → Sync Interfaces → MQTT and set:

• Enable MQTT: checked
• Broker: mqtt.cheerlights.com, Port: 1883
• Username and Password: leave blank
• Device Topic: wled. WLED’s own default, wled/ followed by a code unique to your board, never receives the CheerLights color.
• Group Topic: wled/all

Save, then unplug the board and plug it back in. WLED connects to the MQTT broker when it starts, so the new settings take effect after a restart.

What You Should See

Once the board reconnects, the strip lights up in the current CheerLights color. To check, open the current color in a browser and compare. Then pick a new color on the CheerLights Discord with the /cheerlights command and watch your strip change along with lights around the world.

If It Does Not Work

• The color never arrives: check that MQTT is enabled, the broker is mqtt.cheerlights.com, and the Device Topic is wled, then restart the board.
• The colors are wrong (red shows as green): change the Color Order, usually to RGB.
• The strip stays dark: check the data GPIO, the LED type, and that the board and the strip share ground.
• The board keeps restarting: the LEDs draw more power than USB gives. Lower the Maximum Current, or power the strip from its own 5 V supply with a shared ground.
• No WLED-AP network and not on your Wi-Fi: install WLED again (step 2). If you can still open WLED, a factory reset from Settings → Security & Update also works.

Next

Make one pixel follow CheerLights while the rest of the strip runs an effect, with the recipe in the WLED ESP32-C3 guide. For other ways to build, from Arduino to MATLAB, see Build a CheerLights Display.