How to Get Started with WLED

Updated

WLED is a fast, feature-rich firmware for ESP32 and ESP8266 boards that controls addressable LEDs such as WS2812B, WS2811, and SK6812, plus SPI chipsets like WS2801 and APA102 and HUB75 video wall panels. To get started you need three things: a compatible ESP board, a compatible LED strip, and a way to flash the WLED binary onto the board. After flashing, the board creates its own Wi-Fi access point so you can open the web UI in a browser and configure everything from there — no coding required.

What you need before you start

  • A controller board. WLED runs on ESP32 and ESP8266 hardware. The project notes support for up to 3 LED outputs per ESP8266 instance and up to 10 LED outputs per ESP32 instance.
  • A compatible LED strip. NeoPixel-style strips (WS2812B, WS2811, SK6812) work, as do SPI-based chipsets (WS2801, APA102) and HUB75 panels. RGBW strips are supported.
  • A power supply matched to your strip, and a way to connect the board to your computer (usually USB).
  • A browser on a phone, tablet, or computer to reach the WLED web UI.

Step 1: Install the WLED firmware

The documentation lists several installation routes. Pick the one that matches your setup:

Method When to use it
Install WLED Binary You want to flash a prebuilt binary directly to the board
Install using ESP GUI You prefer a graphical flashing tool
Install using WLED ESP Flasher You want a dedicated WLED flashing utility
Compiling WLED You need custom features or a build not covered by the binaries

The exact menus and buttons depend on the tool you choose, so follow the linked page for your method rather than guessing at screen layouts. The expected result is the same in every case: the board reboots running WLED and starts broadcasting its own Wi-Fi network.

Step 2: Connect to the WLED access point

On first boot, WLED runs in Access Point mode with an automatic failsafe AP. Join that network from your phone or computer, then open the web UI in a browser. This is the same interface you'll use for all later configuration.

Step 3: Configure Wi-Fi and LED output

In the web UI:

  1. Open the Settings page — the documentation describes it as network-based configuration.
  2. Enter your home Wi-Fi credentials so the board can switch to station mode and join your normal network. Access Point and station mode are both supported, so you can fall back to the AP if the credentials are wrong.
  3. Set your LED output: strip type, length, color order, and which GPIO pin drives the data line. Wiring details are covered in the project's wiring guides.
  4. Save and reboot if prompted.

Once the board is on your network, you can reach the web UI from any device on the same network instead of joining the AP each time.

Step 4: Start using effects, palettes, and presets

The web UI gives you color, effect, and segment controls. Key things you can do right away:

  • Effects and palettes. WLED integrates the WS2812FX library for over 100 special effects, plus FastLED noise effects and 50 palettes.
  • Segments. Split your strip into parts and give each segment its own effect and color.
  • Presets. Save and load colors and effects — up to 250 user presets, with support for cycling through them. Presets can also trigger API calls automatically.
  • Nightlight. Gradually dims the strip down, useful for bedtime lighting.

Wiring and hardware notes

The documentation includes dedicated wiring guides and a "Top 5 mistakes" page — read both before powering anything up. Two practical points from the project's own documentation:

  • Long data lines are covered under wiring protips; if your strip is far from the controller, check that section before assuming a fault.
  • Multi-strip support and relay control are built in, so you can drive more than one strip or switch a power relay from the same board.

Common mistakes to avoid

The project maintains a "Top 5 mistakes" page for a reason. The recurring themes in WLED setups are:

  • Powering a long strip from the board's regulator instead of a separate supply sized for the current draw.
  • Wrong color order — colors look swapped until you correct the RGB/RGBW order in settings.
  • Data line and ground issues — a missing common ground between controller and strip causes flicker or no output.
  • Flashing the wrong binary for your chip family (ESP32 vs ESP8266).
  • Losing the AP after entering bad Wi-Fi credentials — the failsafe AP exists so you can recover, but you need to know it's there.

Where to go next

Beyond the basics, the documentation covers DMX output and input, E1.31/Art-Net, the JSON and HTTP request APIs, MQTT, Philips Hue integration, UDP sync and realtime modes, audio-reactive effects, home automation, and remote access. If you hit a problem, the FAQ and the recovery pages (including ESP32 recovery and boot-loop detection) are the first places to check.