WLED is open-source firmware that turns an ESP32 or ESP8266 into a controller for addressable LED strips. It gives you a web interface, an app, effects, presets and a JSON API that all work on your local network, with no cloud account. This guide builds a basic controller for a 5 V WS2812B strip on an ESP32. It covers wiring, flashing with the web installer, first configuration and the settings that matter for safety: the current limit, the OTA lock and the default passwords.

Every pin number, setting name and default below comes from the official WLED documentation (kno.wled.ge). WLED changes quickly. The latest release on GitHub when this was written was v16.0.1 (July 2026), so labels in your version may differ slightly.

Choose the board and the strip

The WLED quick start recommends an ESP32 for new projects, because it is much more capable and ESP8266 support is coming to an end.

Addressable strips (also called digital strips) let you control every LED separately. That is what WLED's effects are built for. The documentation lists the supported chips with their voltages. A few common ones:

  • WS2812B: 5 V, one data line.
  • SK6812: 5 V or 12 V, RGBW versions available.
  • WS2815: 12 V, with a backup data line.
  • APA102 and SK9822: 5 V, with separate clock and data lines.

WLED can also drive non-addressable (analog) strips, but those need a MOSFET and a GPIO per color channel. This guide covers only addressable strips.

Size the power supply

A strip's current at full white is what decides the power supply and wire size. In the LED settings, WLED's default value for the current of one pixel at full white is "55mA (typ. 5V WS281x)". With that figure:

  • 30 LEDs: 30 × 55 mA = 1.65 A
  • 60 LEDs: 60 × 55 mA = 3.3 A
  • 150 LEDs: 150 × 55 mA = 8.25 A

These are worst-case figures at full white. The WLED wiring guide has practical rules for each size:

  • Under 30 LEDs. The strip may be powered through the board's USB port, if the brightness limiter is on and your board has no regulator or diode between USB and its 5 V pin. Never draw more than 1 A through a board's USB port.
  • 30-300 LEDs. Power the strip directly from the power supply and wire the controller in parallel. Above 150 LEDs, consider power injection: extra power wires from the same supply to more points on the strip, usually the beginning and the end. Dim or discolored LEDs at the far end are the typical sign that you need it. The guide says never to use anything thinner than 22 AWG wire for power injection.
  • Over 100 W. Add fuses. Place each fuse as close to the power supply as possible, on the positive lead, and rate it just above the expected draw. The documentation's example: if your LEDs draw at most 4.5 A, use a 5 A fuse.

Don't oversize the supply either. The guide suggests powering 30 LEDs from a 10 W (2 A at 5 V) supply rather than a 100 W one, so that less energy can flow through thin wires during a fault. It also warns that cheap supplies can cause flickering on addressable strips. Choose one that others have used with WS2812 or SK6812 strips, not only with analog strips.

If you use more than one supply, never connect their positive outputs together on the same strip. Split the LEDs into sections, one per supply, and connect only the grounds.

Wire the controller

A digital strip has three connections at its simplest: power, data and ground.

  1. Data. On an ESP32 the quick start recommends GPIO16. It says GPIOs 4, 13 and 16-33 can be used and other pins are not recommended. Board labels vary between manufacturers, so check your board's pinout and use GPIO numbers. On an ESP8266 the recommended pin is GPIO2, which most boards label D4.
  2. Ground. Connect the ESP ground and the strip ground together. This is required even when they use different power supplies.
  3. Direction. Strips have small arrows printed on them. Connect the data line to the end where the arrows start. Connecting to the wrong end is the first item on WLED's "Top 5 mistakes" list.
  4. Level shifter. The ESP32 outputs 3.3 V logic. The quick start says to use a level shifter if the data wire cannot be kept short. The wiring guides show an SN74AHCT125 (or SN74HCT125). Connect its output enable pins (1OE to 4OE) to ground, connect unused inputs to ground and leave unused outputs unconnected.

For data runs longer than a few meters, the WLED documentation describes another option: an RS485 transmitter and receiver pair. According to the documentation, signals become hard to keep clean beyond about 5 m. A differential pair can carry the data over tens of meters on a twisted pair from Cat5e cable.

Flash WLED from the browser

The easiest method is the web installer at https://install.wled.me.

  1. Use a desktop version of Chrome, Edge or Opera, or Firefox 151 or newer. Safari does not work, because it lacks the browser feature the installer needs to talk to the board.
  2. Connect the ESP32 over USB and follow the installer.
  3. On Linux, if the serial port is listed but cannot be opened, add your user to the group that has access to the port.

The installer does not support boards with less than 4 MB of flash. For those, and for flashing with esptool, see the "Install WLED Binary" page. If you download binaries yourself, note that WLED_x.x.x_ESP32.bin is for classic ESP32 chips, not for the ESP32-S2, S3 or C3.

When flashing succeeds, the first 30 LEDs light up orange. On an analog strip the whole strip turns orange.

Connect it to your Wi-Fi

  1. On your phone or computer, join the Wi-Fi network WLED-AP with the default password wled1234.
  2. Open http://4.3.2.1 (or wled.me) in the browser.
  3. Click the Config (gear) icon and choose WiFi Setup.
  4. Select Scan or type your network name, then enter the Wi-Fi password. It is case-sensitive.
  5. Set an mDNS address, for example wled-livingroom.
  6. Change the AP password. The default wled1234 is the same on every WLED device.
  7. Click Save & Connect, then reconnect your phone or computer to your home network.
  8. Open http://wled-livingroom.local. If the .local name doesn't resolve on your device, find the IP in the WLED app or in your router's list of devices.

After the device joins your network, 4.3.2.1 and wled.me stop working.

On the same page, the AP opens setting decides when the hotspot comes back. The options are "No connection after boot", "Disconnected", "Always", "Never (not recommended)" and "Temporary (no connection after boot)".

Configure the LED output and the current limit

Open Config, then LED Preferences:

  • Type: the chip on your strip. The default is "WS281x RGB". Some strips need a different type. The documentation's example is WS2814, which must be set as SK6812, not WS281x.
  • Color order: the default is GRB. If red and green are swapped, try another order.
  • Length: the number of LEDs.
  • GPIO: the data pin, for example 16.
  • Enable automatic brightness limiter: on by default. When on, WLED lowers the overall brightness to keep the estimated current below Maximum PSU Current. The mA/LED setting (default "55mA (typ. 5V WS281x)") feeds this estimate. The limiter does not work for analog (PWM) or virtual LEDs.

Set Maximum PSU Current a little below what your supply and wiring can actually deliver. Check the value after flashing. The WLED documentation gives two different defaults: the Settings page lists 3000 mA, while the wiring guide and the "Top 5 mistakes" page mention 850 mA. A limit that is too low gives a typical symptom with many LEDs: they stay dark, or flash briefly and go out after a color change. A limit that is too high lets the strip draw more than your supply or wires can handle.

Global brightness factor (1-100 %) is another way to cap brightness permanently.

Lock down the device

The WLED documentation is open about its security model. WLED assumes a trusted network, and anyone with network access to the device can do almost anything with it. Connections use unencrypted HTTP. In practice:

  • Change both default passwords. Change the AP password (wled1234) in WiFi Setup. Change the OTA passphrase (wledota) in the Security settings.
  • Turn on the OTA lock. In Security settings, enable Lock wireless (OTA) software update. Without the passphrase, nobody can then upload firmware over Wi-Fi. That matters because your Wi-Fi password is stored unencrypted on the device, and malicious firmware could send it to an attacker.
  • Set a settings PIN (4 digits) if others use your network. It is sent unencrypted, so don't reuse a PIN you use anywhere else. According to the OTA lock FAQ, the settings stay unlocked for 15 minutes after the PIN is entered.
  • Know what can't be protected. The FAQ says the light controls themselves cannot be password-protected. Anyone who can reach the device's IP can change the lights.
  • Don't expose it to the internet. The FAQ asks users who forward a port anyway to enable the OTA lock, and never to change Wi-Fi or OTA passwords through the forwarded port. A VPN to your home network avoids the problem altogether.
  • Watch for VLANs. The Only allow update from same network/WiFi option rejects firmware uploads from other subnets. If you manage IoT devices from a different VLAN, the documentation says to either set a PIN or disable this option. Disabling it makes the device less secure.

The Backup & Restore section on the same page downloads presets and configuration as JSON files. Passwords are not included in the backup.

Update the firmware

To update over Wi-Fi:

  1. In Security settings, untick the OTA lock and enter the passphrase.
  2. Save and reboot.
  3. Use Update WLED (the quick start calls it "Manual OTA update") to upload the new release binary for your board.
  4. Lock OTA again and reboot.

If the update page shows "OTA lock active", the lock is still on.

Control it from scripts

WLED has a JSON API at /json. Sending a POST to /json/state changes the state. This example from the documentation toggles the light and returns the new state:

curl -X POST "http://wled-livingroom.local/json/state" -d '{"on":"t","v":true}' -H "Content-Type: application/json"

Per the same page, {"on":true,"bri":255} turns the light on at full brightness:

curl -X POST "http://wled-livingroom.local/json/state" -d '{"on":true,"bri":255}' -H "Content-Type: application/json"

The documentation also covers MQTT, E1.31/Art-Net, the WLED UDP sync between devices and a home automation section, if you want to connect WLED to other systems.

Troubleshooting checklist

From WLED's "Top 5 mistakes" page:

  1. Data connected to the wrong end of the strip (check the arrows).
  2. Wrong GPIO in LED Preferences. On a D1 mini, labels like D4 are not GPIO numbers.
  3. Current limit too low for the number of LEDs.
  4. Wrong LED type or color order.
  5. Bad wiring: loose contacts, cold solder joints, wires too thin, or separate supplies without a common ground.