Build a WLED LED strip controller with an ESP32 for Home Assistant

WLED turns an ESP32 and a strip of addressable LEDs into a light with hundreds of effects, a phone-friendly web app and automatic Home Assistant discovery — without writing any code. Most problems people hit come from power and data wiring, so that's where this guide spends its time.

Parts

• An ESP32 DevKit. Any classic ESP32 board works. Newer WLED releases focus on the ESP32 family, so it's the safer choice over an ESP8266 for a new build.
• A 5 V addressable strip such as WS2812B or SK6812, usually 30 or 60 LEDs per meter. 12 V strips like WS2815 suit long runs; the wiring is the same except the ESP32 needs its own 5 V supply.
• A power supply sized with the calculator below.
• A 74AHCT125 level shifter to turn the ESP32's 3.3 V data signal into the 5 V the strip expects.
• A 1000 µF capacitor (6.3 V or higher) across the strip's power input, and a 330 Ω resistor in the data line.
• An inline fuse rated a little above the supply's current, and wire thick enough for that current.
• Optional: a WiZ remote (WiZmote) for wall-switch-style control. See adding a WiZ remote below.

Size the power supply first

Each LED is really three tiny LEDs: red, green and blue. At full white, a typical 5 V WS281x pixel draws about 55 mA, and that's the figure WLED itself assumes. Multiply by the LED count and the numbers get big fast: 300 LEDs at full white is over 16 A.

You rarely run every LED at full white, and WLED has a brightness limiter that caps current to whatever you tell it your supply can deliver. So size the supply for the worst case with a little headroom, then set the limiter just under it.

For 12 V and 24 V strips, check the datasheet: each controllable "pixel" draws a different amount from a 5 V LED, and some 12 V strips group three LEDs per pixel.

Wiring

Strips have a direction. The arrows printed on them point away from DIN; connect the controller to the end the arrows start from.

For 5 V strips longer than about 2–3 meters, voltage drops along the copper and the far end turns orange or pink at high brightness. The fix is power injection: run a second pair of wires from the supply to the other end of the strip (and to the middle on long runs). If you use two supplies, join their grounds but never their positive wires.

Flash WLED

1. Plug the ESP32 into your computer with a USB cable that carries data (some charging cables don't).
2. Open install.wled.me in Chrome or Edge, click Install, and pick the board's serial port.
3. When it finishes, the first 30 LEDs light orange. That's WLED's way of saying it's running.

First setup

1. On your phone, join the Wi-Fi network WLED-AP. The default password is wled1234.
2. Open 4.3.2.1 in a browser and enter your home Wi-Fi details under WiFi Setup. The board reboots onto your network.
3. Find its new address in your router or in Home Assistant (next section), then open Config → LED Preferences.
4. Set the LED count, the LED type (WS281x for WS2812B), the color order (usually GRB for WS2812B — if red shows as green, this is why), and the data GPIO.
5. Turn on the automatic brightness limiter and enter the max current from the calculator above. WLED's default is 3000 mA, which is too high for a small supply and too low for a big one.

Recent WLED versions include a Pin Info page under the config menu that shows which GPIOs are in use. For picking a different data pin, the ESP32 safe pin finder lists the ones that won't cause boot problems; GPIO4, 13 and 16–33 are the usual choices.

Add a WiZ remote

Phones are a clumsy way to turn on a light. WLED has built-in support for the WiZ remote, also called the WiZmote or the Philips Remote Dimmer Switch powered by WiZ. It talks to the ESP32 directly over ESP-NOW, so it needs no hub, no app and no Home Assistant — it keeps working even if your server is down.

Pair it

1. In WLED, open Config → WiFi Setup and turn on ESP-NOW. Also tick Disable WiFi sleep; WLED's docs say the remote isn't reliable without it. Save.
2. Press any button on the remote. Its MAC address appears in the Last device seen field.
3. Click + next to it to add it to the remote list, then save. WLED ignores remotes that aren't on the list, so a neighbor's WiZmote can't control your lights.

WLED accepts up to 10 remotes, and one remote can control several controllers: pair the same remote on each one and they all respond together.

What the buttons do

So the numbered buttons are only as good as your presets. Save your four favorite looks as presets with IDs 1 to 4 in WLED's Presets tab — for example warm white, bright white, a slow color effect, and movie dim.

Add it to Home Assistant

Home Assistant discovers WLED devices on your network automatically: look for it under Settings → Devices & services and click Add. If it doesn't appear, add the WLED integration manually and enter the controller's IP address.

You get a light entity you can dim and color like any bulb, plus selects for presets, playlists and palettes, and numbers for effect speed and intensity. If you split the strip into segments in WLED, each segment becomes its own light with a master light controlling them all.

Ideas that work well

• Presets as scenes. Build a few looks in WLED's own app (evening warm white, movie dim, holiday) and save them as presets. Home Assistant automations then just pick a preset, which is simpler than setting colors and effects from YAML.
• Presence-triggered lighting. Pair a strip under the kitchen cabinets with an LD2410 presence sensor: lights fade up when someone's at the counter and stay on while they're standing still.
• Status lights. Use one segment as an at-a-glance indicator — green when the washer is done, red when a door is left open.

Troubleshooting