WLED
WLED
WLED is free, open-source firmware for ESP8266 and ESP32 microcontrollers that provides an easy-to-use web interface for controlling addressable LED pixels. It has become one of the most widely used firmware platforms for DIY holiday lighting because it combines powerful features with simple configuration and excellent community support.
Unlike traditional pixel controllers that require dedicated hardware, WLED allows inexpensive ESP-based controllers to drive addressable LEDs while communicating with lighting software such as xLights and Falcon Player (FPP).
Official WLED Resources
The DIYChristmas Wiki is intended to complement—not replace—the official WLED documentation. The following resources are maintained by the WLED development team and provide the latest installation instructions, feature documentation, and release information.
- Official WLED Documentation
- Getting Started
- Installation Guide
- Feature Documentation
- Web Interface
- Supported Hardware
- Release Notes
- GitHub Repository
Why Use WLED?
WLED has become one of the most popular firmware choices for DIY holiday lighting because it offers:
- Free and open-source firmware
- Supports ESP8266 and ESP32 controllers
- Excellent web-based configuration interface
- Supports inexpensive distributed controllers
- Reliable Wi-Fi networking
- Over-the-air (OTA) firmware updates
- Active development with frequent feature additions
- Large user community
- Excellent compatibility with xLights and Falcon Player (FPP)
Typical WLED Applications
WLED can be used in a variety of ways within a holiday lighting display, including:
- Standalone decorative lighting
- Pixel props synchronized with xLights
- Distributed controllers located near props
- Permanent architectural lighting
- Accent lighting
- Home automation
- Interactive displays
Typical WLED Applications
WLED is flexible enough to support many different types of holiday lighting projects. Common applications include:
- Standalone decorative lighting
- Pixel props synchronized with xLights
- Distributed controllers located near individual props
- Permanent architectural lighting
- Accent and landscape lighting
- Home automation
- Interactive lighting displays
Many DIY holiday displays combine several of these applications using the same WLED firmware.
Features Useful for Christmas Displays
The following WLED features are especially useful for holiday lighting displays.
DDP Support
DDP (Distributed Display Protocol) provides efficient communication between xLights or FPP and WLED controllers. Many hobbyists prefer DDP over E1.31 because it reduces network overhead and simplifies controller configuration.
E1.31 / sACN Support
WLED supports the industry-standard E1.31 (sACN) lighting protocol, allowing it to integrate with most sequencing software.
Art-Net Support
Art-Net is also supported for compatibility with professional lighting equipment and software.
Segments
Segments allow multiple independent lighting effects or virtual props to exist within a single LED strip.
Presets
Presets allow complete controller configurations to be saved and recalled for testing, daily operation, or seasonal effects.
Playlists
Playlists automatically sequence presets, making standalone decorative displays possible without external control software.
Mapping
LED Mapping allows the physical wiring order of LEDs to differ from their logical display order. This simplifies the construction of props where wiring convenience differs from the desired display layout, such as folded pixel strings, icicles, candy canes, matrices, and other custom props.
Virtual LEDs
Introduced in WLED 0.16, Virtual LEDs allow LEDs connected to multiple ESP controllers to appear as a single logical LED strip within WLED. This simplifies the configuration of some large displays.
Multiple GPIO Outputs
ESP32-based controllers can drive multiple independent LED outputs from a single controller. This allows one ESP32 to control multiple props or strings without requiring separate controllers.
Over-the-Air Updates
Firmware can normally be updated through the web interface without physically accessing the controller.
Christmas Display Tips
The following recommendations reflect practical experience from the DIY holiday lighting community.
- Consider using DDP whenever possible for controller communications.
- Lower brightness settings can dramatically reduce power requirements while maintaining excellent visual appearance.
- Label controllers with their hostname or IP address to simplify troubleshooting.
- Keep firmware versions consistent throughout the display whenever practical.
- Test new firmware on a single controller before updating an entire display.
- Use presets to verify wiring and pixel order before connecting a prop to xLights.
- Maintain a backup of each controller configuration before performing firmware updates.
- Organize controllers logically by display area to simplify troubleshooting and maintenance.
Compatibility
WLED supports a wide variety of hardware and software.
Hardware
- ESP8266
- Original ESP32, ESP32-S2, ESP32-S3, ESP32-C3, and selected newer ESP32 family processors (support varies by WLED version).
- Many addressable LED chipsets including WS2811, WS2812, SK6812, APA102, and others.
Software
Lessons Learned
The following observations have been made through real-world use in DIY holiday lighting displays.
- Distributed ESP controllers often simplify wiring compared to centralized controllers.
- Modern Wi-Fi networks can provide excellent reliability when properly designed.
- Small controllers located near each prop reduce voltage drop and simplify installation.
- Good controller naming conventions greatly simplify display maintenance.
- Planning for future expansion makes yearly display growth much easier.
- Configure and test each controller before installing it in the display to simplify troubleshooting.