WLED Setup on ESP32: Control Addressable LEDs Without Coding

WLED setup is the quickest way to turn an ESP32 into a Wi-Fi LED controller without writing a single line of code. WLED is free, open-source firmware written to drive addressable LED strips, rings and matrices such as the WS2812B. It's flashed to the board from your browser in a few clicks; after that you pick from more than 100 effects, dozens of colour palettes, timers and music-reactive animations on your phone or computer. A TV bias light, shelf lighting, stair lights or Christmas decorations all run on the same setup.

In this guide you'll see step by step how to wire the ESP32, LED strip and power supply correctly, install WLED with the web installer, do the first Wi-Fi setup, and set the LED count, data pin and colour order. Then you'll learn to use effects, palettes, segments and presets, how to calculate power and inject it along long strips, how to sync the light to music with an I2S microphone, and how to integrate it with Home Assistant. Finally there are two short programs that control WLED over the JSON API from another ESP32 and a Raspberry Pi Pico W, plus fixes for the most common problems.

What is WLED and what can it do?

Normally, to drive addressable LEDs you write code in the Arduino IDE with Adafruit NeoPixel or FastLED and reprogram the board for every change. WLED turns this completely around: the board is programmed once, and every setting, effect and schedule is handled from the board's own web interface. The ESP32 joins your home Wi-Fi, runs a web server, and any device on the same network reaches it from a browser or the phone app. Settings are stored in the board's flash memory, so after a power cut the lights carry on where they left off.

• Supported LEDs: WS2812B, WS2811, WS2813, WS2815, SK6812 (including RGBW), TM1814, and clocked LEDs such as the APA102 and SK9822.
• Effects and palettes: More than 100 built-in effects and over 70 colour palettes; every effect can be tuned with speed and intensity sliders.
• Segments: Split a single strip into sections and give each one its own effect and colour.
• Presets and playlists: Save looks you like and recall them with one tap, or build lists that change in sequence.
• Timers: Lights that switch on or off at a set time, at sunrise or sunset, plus a sleep timer.
• Integration: Talks to other systems on the network through Home Assistant, MQTT, Alexa, E1.31 and Art-Net.

What you need

Compatibility note: WLED also runs on ESP8266-based boards (NodeMCU, Wemos D1 mini), but because their memory and processing power are more limited they handle fewer LEDs, and the music-reactive feature only exists on the ESP32. That's why we recommend an ESP32 for new projects, and this whole guide is written for the ESP32. The Raspberry Pi Pico can't run WLED; to drive addressable LEDs with a Pico you can use MicroPython's neopixel module, or, as in the JSON API example below, use a Pico W to control an ESP32 that runs WLED remotely.

Wiring: ESP32, LED strip and power supply

Installing WLED with the web installer

You don't need the Arduino IDE or any other program to install WLED. The official web installer (install.wled.me) connects straight to the ESP32 through the browser's Web Serial feature, detects the board's chip and writes the matching firmware. This works in Chromium-based desktop browsers such as Chrome, Edge and Opera; Firefox and Safari don't support Web Serial at the moment. For the board to show up as a serial port on your computer, the CP210x or CH340 driver must be installed.

1. Plug the ESP32 into the computer with a USB cable that can carry data. You don't need to connect the LED strip yet.
2. Open the WLED web installer in Chrome or Edge. From the version list choose the latest stable release; beta versions are for testing.
3. Press the Install button. In the window that opens, select your board's port (something like COM3 on Windows, cu.usbserial... or cu.wchusbserial... on macOS) and click Connect.
4. Once the installer has detected the chip, confirm the Install WLED option. If the board was used with another program before, clearing the memory with "Erase device" stops old settings from getting mixed in.
5. Writing takes about a minute. If the upload doesn't start, hold down the ESP32's BOOT button and try again.
6. When the installation finishes, the installer asks for your Wi-Fi details. Enter the network name and password and click Connect, then open the WLED interface with the Visit Device link that appears.

First Wi-Fi setup

If you skipped the installer's Wi-Fi step, or the board can't join the network, WLED opens its own access point. Connect your phone to the network called WLED-AP; the default password is wled1234. On most phones the settings page opens by itself; if it doesn't, type 4.3.2.1 into the browser. On the WiFi Setup page, enter your home network's name and password, save, and wait for the board to restart. The ESP32 only supports 2.4 GHz Wi-Fi; if your router uses the same name for 2.4 and 5 GHz it's usually fine, but it can't join a network that only broadcasts on 5 GHz. After connecting, you can find the board's IP address in your router's list of connected devices or with the WLED app's automatic discovery. It's also a good idea to change the access point password on the same page for security.

LED count, data pin and colour order

1. In the WLED interface open the Config menu (gear icon) and go to LED Preferences.
2. Under LED outputs choose the LED type: "WS281x" for WS2812B, "SK6812/WS2814 RGBW" for RGBW strips.
3. Set Color Order to GRB for the WS2812B; if the colours come out wrong, change this field until you find the right one.
4. In Length, enter the number of LEDs on the strip (e.g. 60 for 1 m of 60 LED/m strip).
5. In GPIO, enter the pin the data wire is connected to (16 in this guide). GPIO 6–11 are reserved for the flash memory and 34–39 are input-only; don't use them.
6. In Maximum Current (the automatic brightness limiter), enter about 80% of the current your supply can deliver, in mA; 3200 for a 5 V 4 A supply.
7. Press Save at the bottom of the page. Go back to the main screen and pick a colour; the whole strip should light up in that colour.

Effects, palettes, segments and presets

WLED's main screen has three parts: the colour picker and brightness at the top, the effect list in the middle and the palette list beside it. When you pick an effect (e.g. Rainbow, Fire 2012, Twinkle), the Speed and Intensity sliders below it change its speed and density. The palette decides which family of colours the effect uses: the same "Colorwaves" effect looks like blue waves with the "Ocean" palette and like red flames with "Lava". If you want an effect to use the colours you picked, choose palettes such as "Default" or "Color 1".

• Segments: Split the strip into parts in the Segments section; for example, LEDs 0–29 can breathe in blue while 30–59 run a rainbow. Each segment has its own effect, palette, brightness and direction.
• Presets: Name and save the look you like in the Presets section. A preset stores effect, colour, segments and brightness all at once and brings them back with one tap.
• Playlists: Build a list that cycles through several presets in order, for durations you choose; ideal for shop windows or party lights.
• Timers: Set your time zone on the Config > Time & Macros page, then run a preset at a set time, at sunrise or at sunset.
• Nightlight: The moon button slowly dims the light and switches it off over a time you choose; handy for a child's room.
• Sync: Several WLED devices on the same network can link up over UDP and play the same effect at the same time.

The phone app

The interface works in any browser, but for everyday use the free WLED app for iOS and Android is more convenient. The app finds WLED devices on the same network automatically, lists them, and opens the board's own interface when you tap one. If you have several devices (e.g. living room, kitchen and stairs), you control them all from one screen. If a device doesn't appear in the list, make sure the phone and the ESP32 are on the same network, or add the IP address manually. Because the app is only an interface, the phone doesn't need to stay on for the lights to work; timers and presets keep running inside the ESP32.

Power budget and power injection

A WS2812B LED contains three tiny LEDs, red, green and blue, each drawing about 20 mA at full brightness. So a single pixel needs about 60 mA at full white. That's the worst case; with coloured effects and medium brightness the real consumption is often about a third of that. WLED's Maximum Current setting (the automatic brightness limiter) calculates the current each frame will draw and lowers the brightness by itself if it would exceed the limit. Thanks to this you can safely run a 300-LED strip from a 5 V 10 A supply; only full white gets a little dimmer. The default limit is kept low so the board stays safe when powered from USB, so be sure to update it when you move to an external supply.

• Voltage drop: The copper traces of 5 V strips are thin; as the current rises, the voltage drops towards the end of the strip and white looks yellowish or pinkish. This usually starts after 1–2 metres (60–120 LEDs).
• Power injection: Run separate 5 V and GND wires from the power supply to every 1–2 metres of the strip and solder them to the strip's copper pads. Feeding both ends of a long strip also works well. The data line only enters at the start; injection wires carry only 5 V and GND.
• Wire size: Use at least 0.75–1 mm² (around 18 AWG) for a few amps and 1.5 mm² for 10 A and above; the strip's own thin lead wires are only meant for short strips.
• Fuse: Fit a fuse between the supply and the strip on every feed, rated for what the wire can carry; it stops the wire from burning in a short circuit.
• 12 V option: For very long installations, 12 V strips such as the WS2815 draw a third of the current for the same power and suffer much less from voltage drop.
• Calculator: If you're building a portable setup on batteries or a power bank, work out the runtime with the battery life calculator.

Light synced to music with a microphone

WLED builds for the ESP32 come with the AudioReactive add-on built in; connect a microphone, change a few settings, and the effects move with the rhythm and frequencies of the music. The best results come from the INMP441, a digital I2S microphone: because it sends the signal digitally, you avoid the noise and gain problems of analog microphones. Analog microphone modules such as the MAX9814 or MAX4466 can also be used on an ADC1 pin (e.g. GPIO 36), but they need more tuning. Sound sensors such as the KY-038 only tell you whether there is sound, so they're not suitable for this job.

After wiring, enable the AudioReactive section on the Config > Usermods page, choose "Generic I2S" as the microphone type and enter the SD, WS and SCK pins as in the table. After saving and restarting the board, the sound-driven effects stand out in the effect list; GEQ, Gravimeter and Waterfall are good starting points. If the lights twitch when there's no sound, raise the Squelch value (noise threshold); if they don't react enough to the music, increase Gain. Placing the microphone somewhere it hears the room, rather than right in front of the speaker, gives the most balanced result.

Home Assistant integration

Home Assistant has a built-in WLED integration and usually finds WLED devices on the same network by itself. If a "New device discovered" notification appears, just confirm it; if not, go to Settings > Devices & Services > Add integration, choose WLED and enter the device's IP address. The integration adds the strip and each segment as separate lights, presets, playlists and palettes as select boxes, and speed and intensity as sliders. That lets you set up automations such as "switch the living room strip to warm white at sunset" or "light the hallway when the door opens" in a few clicks. If you'd rather use MQTT, WLED can also connect to an MQTT broker from its Sync Interfaces page; we covered using MQTT with Home Assistant in the ESP32, MQTT and Home Assistant article.

Controlling WLED from code: the JSON API

WLED works without code, but when you want another device to control it, a simple HTTP request is enough. A JSON message sent to the device's /json/state address changes the light's state: {"on":"t"} toggles it, {"bri":128} sets half brightness, {"ps":2} runs preset number 2. If you add "v":true to the message, WLED replies with the current state. The first program below uses a button on a separate ESP32 to cycle through the first three presets on WLED; the second does the same with a Raspberry Pi Pico W and MicroPython. In both programs, enter your own network details and the IP address of the WLED device.

1// İkinci bir ESP32'den WLED preset değiştirme (JSON API) / Switch WLED presets from a second ESP32 (JSON API)
2// Buton: GPIO 4 -> GND (dahili pull-up) / button: GPIO 4 -> GND (internal pull-up)
3#include <WiFi.h>
4#include <HTTPClient.h>
5
6const char* WIFI_SSID = "AgAdi";                           // ağ adı / network name
7const char* WIFI_PASS = "Sifre";                           // ağ şifresi / network password
8const char* WLED_URL = "http://192.168.1.50/json/state";   // WLED cihazının IP'si / IP of the WLED device
9const int BUTTON_PIN = 4;
10
11int preset = 1;
12bool lastState = HIGH;
13
14int sendJson(const String& body) {
15  HTTPClient http;
16  http.begin(WLED_URL);
17  http.addHeader("Content-Type", "application/json");
18  int code = http.POST(body);                              // 200 = başarılı / success
19  http.end();
20  return code;
21}
22
23void setup() {
24  Serial.begin(115200);
25  pinMode(BUTTON_PIN, INPUT_PULLUP);
26  WiFi.begin(WIFI_SSID, WIFI_PASS);
27  while (WiFi.status() != WL_CONNECTED) {
28    delay(300);
29    Serial.print('.');
30  }
31  Serial.print("\nIP: ");
32  Serial.println(WiFi.localIP());
33}
34
35void loop() {
36  bool state = digitalRead(BUTTON_PIN);
37  if (lastState == HIGH && state == LOW) {                 // butona basıldı / button pressed
38    String body = "{\"on\":true,\"ps\":" + String(preset) + "}";
39    int code = sendJson(body);
40    Serial.printf("Preset %d -> HTTP %d\n", preset, code);
41    preset = preset % 3 + 1;                               // 1 -> 2 -> 3 -> 1
42    delay(50);                                             // basit debounce / simple debounce
43  }
44  lastState = state;
45}

1# Raspberry Pi Pico W: butonla WLED aç/kapat (JSON API) / toggle WLED with a button (JSON API)
2# Buton: GP14 -> GND (dahili pull-up) / button: GP14 -> GND (internal pull-up)
3import network
4import time
5import urequests
6from machine import Pin
7
8SSID = "AgAdi"                                  # ağ adı / network name
9PASSWORD = "Sifre"                              # ağ şifresi / network password
10WLED_URL = "http://192.168.1.50/json/state"     # WLED cihazının IP'si / IP of the WLED device
11
12button = Pin(14, Pin.IN, Pin.PULL_UP)
13
14wlan = network.WLAN(network.STA_IF)
15wlan.active(True)
16wlan.connect(SSID, PASSWORD)
17while not wlan.isconnected():
18    time.sleep(0.3)
19print("IP:", wlan.ifconfig()[0])
20
21last = 1
22while True:
23    now = button.value()
24    if last == 1 and now == 0:                  # butona basıldı / button pressed
25        r = urequests.post(WLED_URL, json={"on": "t", "v": True})
26        state = r.json()                        # güncel durum / current state
27        r.close()
28        print("Acik / On:", state["on"], " Parlaklik / Brightness:", state["bri"])
29        time.sleep_ms(50)                       # basit debounce / simple debounce
30    last = now
31    time.sleep_ms(10)

In both programs the current state is compared with the previous one so that a single press sends only one request, and the 50 ms wait filters out the button's mechanical bounce. In a real project it's a good idea to give the WLED device a fixed IP address on your router, or use its mDNS name from the WLED interface, because the IP can change when the power goes off and the router restarts. With the same method you can turn on stair lights when a motion sensor triggers, switch to a night preset when an LDR says it's getting dark, or change the strip's colour according to a temperature reading.

Common problems and fixes

WLED is one of the most enjoyable ways to work with addressable LEDs: setup takes a few minutes, you get professional-looking effects without writing code, and when you need to you can tie it into your own projects with the JSON API. If you'd like to learn how LEDs are driven in code, you can build the "ESP32 WS2812B NeoPixel Strip Control" project and the WS2812B chaser, Knight Rider and police light projects in the BlueGrays app, step by step with a wiring diagram and ready-made code.