WLED firmware review: ESP32 addressable LED control over WiFi

What WLED actually solves for LED builders

Driving an addressable strip means producing a precisely timed serial signal, holding a colour buffer, and re-rendering it at a stable frame rate. On a microcontroller that is real work, and it is the same work for every project. WLED packages that work into firmware you flash once.

The README describes it as "a fast and feature-rich firmware for ESP32 microcontrollers to control addressable LEDs, from simple strips to large 2D matrices and HUB75 panels." The ESP8266 is still listed in the repository topics and in the related search terms around the project, and the README's hardware section names ESP32 variants (original, S2, S3, C3) explicitly. Treat ESP32 as the first-class target.

The audience is specific. Someone who wants a shelf of animated light without writing C++. Someone who wants a matrix panel driven from a browser. Someone who wants their lights to appear in Home Assistant over MQTT and to accept DMX or Art-Net from a lighting desk. The project is not aimed at product engineers who need a certified, mains-rated lighting controller with a warranty and a support contract. It is a hobbyist and prosumer firmware, and the disclaimer in the README about photosensitive epilepsy is a reminder of how directly it drives bright, fast-changing output.

How the firmware, segments and APIs fit together

WLED runs on the microcontroller. A web UI is served from the device itself, so the browser is the configuration surface and no companion service is required. Settings and presets live on the device filesystem, which is why the README lists "filesystem-based config for easy backup and restore of presets and settings" as a hardware-adjacent feature.

The output model is segments. A segment is a range of LEDs with its own effect, colour and palette, and the README states that segments let you "apply different effects, colors and palettes to independent parts of your LED setup simultaneously." That is the mechanism behind most non-trivial installations: one physical strip, several logical zones, each animated independently. Up to 250 presets store colours, effects and segment configurations, and playlists cycle through them.

Control arrives through several paths. The JSON API and HTTP request API are the documented programmatic interfaces. MQTT is supported with Home Assistant discovery. E1.31, Art-Net, DDP and TPM2.net cover DMX and professional lighting workflows, and UDP realtime sync plus ESP-NOW handle device-to-device coordination, with ESP-NOW working without a WiFi router. Outputs are not limited to one strip: the README claims up to 17 LED outputs on ESP32 using parallel I2S and RMT, and an Auto Brightness Limiter per output exists for safe operation. That limiter is the feature to read about before you power a long strip from a small supply.

Installing WLED and running a first preset

The README does not contain flashing instructions. It points to the documentation at kno.wled.ge and to a tutorials and getting-started page under kno.wled.ge/basics/tutorials/. That is where the flashing options live, and the choice of method depends on your board. You should not expect to find a curl one-liner in the repository root.

What the repository does document is the build side. The project builds with PlatformIO, pinned in requirements.txt at platformio==6.1.19, and platformio.ini sits at the top level with a platformio_override.sample.ini for local overrides. The frontend assets are assembled by a Node toolchain, and package.json requires Node 20 or newer.

python -m pip install -r requirements.txt

That installs PlatformIO and its dependencies from the pinned lock file. After it completes, the pio command is available and the project can be compiled against platformio.ini.

npm install

package.json declares dependencies including clean-css, html-minifier-terser, web-resource-inliner and nodemon, and its engines field requires node >=20.0.0, so an older runtime will fail here rather than at the firmware build stage.

npm run build

package.json defines build as node tools/cdata.js, which generates the web UI data the firmware serves. The dev script in the same file watches tools/ and wled00/data/ and re-runs that generator.

pio run

The environment name comes from platformio.ini, and the sample override file exists so you can add a custom board without editing tracked files. Once firmware is on the device and the board has joined your network, the README's quick start path is the wiki, where the JSON API page documents the request format. OTA updates are supported over HTTP and ArduinoOTA and can be password-protected, so the first flash is the only one that needs a cable. The README does not document rollback if an OTA image misbehaves, so keep a physical flashing route available.

Where WLED stops being the right tool

The output ceiling is real. Seventeen outputs is generous for a hobby build and small for a commercial installation. If your design needs hundreds of universes or a rack of controllers with redundant power and network paths, WLED is the wrong layer.

Memory and effect complexity interact. The README advertises 200+ built-in effects, 2D effects and HUB75 support, all on a microcontroller. Large 2D matrices and audio-reactive effects are the heaviest configurations, and the ESP8266 has far less headroom than an ESP32. The README does not publish memory budgets or frame-rate guarantees per board, so the only honest way to size a build is to test your own panel geometry on your own board.

The license is another boundary that surprises people. WLED is EUPL-1.2, a copyleft licence. If you plan to ship a product built on this firmware, the reciprocal obligations deserve a lawyer's attention, not a blog post's. The README also carries a photosensitive epilepsy disclaimer and recommends against the software for people prone to it, advising anyone who proceeds to avoid strobe, lightning and noise modes and high effect speed settings. That is not a marketing caveat; it is a statement about what the effects do.

Finally, the project is community-maintained. The README says it was originally created by Aircoookie and is "now maintained by a community of contributors." The last push to the repository was on 2026-09-20, and the most recent tagged release in the list is v16.0.1 from 2026-07-07, with a nightly from 2026-07-17. There is no vendor SLA behind any of it.

WLED versus writing your own FastLED sketch

The closest alternative is not another firmware project. It is writing your own sketch on FastLED or a similar library and flashing it directly. The difference in approach is who owns the runtime. A custom sketch gives you exact control over frame timing, memory layout and pin assignment, and it carries no copyleft obligation beyond whatever the LED library itself uses. It also gives you a web UI, presets, MQTT, E1.31 and OTA updates only if you build them.

WLED's bet is that most people want the second list more than the first. Segments, 250 presets, playlists, a nightlight with a configurable dimming curve, and a custom palette editor are all pre-built. For a shelf, a desk or a matrix panel, that is months of work you do not do.

Choose the custom sketch when your animation is the product, when you need deterministic timing that a general-purpose effect engine cannot promise, or when your hardware is unusual enough that the compatible-hardware list does not cover it. Choose WLED when the lighting is the point and the firmware is plumbing. The usermod system is the middle path: the README describes it as a way to "extend WLED with community or custom modules without modifying core code," and there is a community usermod library covering AudioReactive, temperature sensors, rotary encoders and displays.

Licence, upgrades and the cost of staying current

WLED is licensed under EUPL v1.2. The README states this plainly and links the LICENSE file. EUPL is a copyleft licence with a compatibility list, and it is not the MIT-style permissive licence many hobby firmware projects use. For personal builds this changes nothing practical. For a product, it changes what you can do with your modifications, and the README offers no guidance on that question. Treat that as a legal review item, not a documentation gap.

Upgrade cost is low by design. OTA updates over HTTP and ArduinoOTA mean you do not need physical access to the device, and password protection is available. Presets and settings live on the filesystem, so backup and restore are file operations rather than a reconfiguration exercise. The nightly release channel exists alongside tagged releases, which means you can choose stability or new effects, but the README does not describe a support policy for nightlies. If you run a nightly, you are the test coverage.

The build side has recurring cost. Node 20 or newer is required, PlatformIO is pinned through requirements.txt, and the frontend is generated by tools/cdata.js rather than committed as a finished artifact. Anyone building from source re-runs that toolchain. Anyone flashing a released binary skips it entirely, which is the cheaper path for almost everyone.

Editorial conclusion

Adopt WLED if you have an ESP32 or ESP8266 board, a supported strip or panel, and you want effects, presets and network control without writing firmware. Skip it if you need a certified mains product, if your strip is not on the compatible list, or if you cannot budget time for PlatformIO builds and OTA updates. Before buying hardware, verify that your exact LED chipset and board appear on the wiki's compatible hardware pages, and check whether the output count you need fits within the 17-output ceiling on ESP32.

Frequently asked questions

Official sources

1. License: EUPL-1.2
2. Project website
3. README
4. Releases
5. wled/WLED on GitHub