WLED Runner for ESPHome

High-performance WLED port for ESPHome (ESP-IDF Only)

wled-runner

High-quality WLED effects running natively within ESPHome.

wled-runner is a C++ bridge that brings the visual fidelity of WLED's best effects (Pacifica, Plasma, Aurora, etc.) into the ESPHome ecosystem without the overhead of complex YAML lambdas.

🎯 Is this for me?

This project is not a full WLED replacement. Choose the right tool for your hardware:

• Install WLED if: You want the full experience (Segments, E1.31, 150+ effects) or are dedicating an MCU solely to lighting.
• Use wled-runner if: You want to consolidate! You need a single ESP32 to handle sensors, relays, or switches AND run smooth, high-quality lighting effects simultaneously.

⚠️ Reality Check

Your mileage may vary. Visual effects are computationally expensive.

• Hardware: An ESP32 is highly recommended.
• Resources: Trying to run complex effects (like Pacifica) alongside heavy components (like Bluetooth Proxy or Cameras) will likely cause instability.
• Optimization: This library is optimized for ESP-IDF, but hardware resources are finite. Manage your load accordingly.

This native C++ component brings WLED's advanced lighting effects to ESPHome. Unlike the old addressable_lambda method, this implementation runs as a proper component optimized for the ESP-IDF framework.

⚠️ Platform Compatibility:

• Framework: ESP-IDF Only (Arduino is NOT supported)
• Chips: ESP32 Classic and ESP32-S3 Only.
  • ESP32-C3 is currently not supported due to single-core limitations affecting effect smoothness.

If you want to know how and why I created this component head over here.

✨ Features

• Native C++ Performance - optimized for multi-core ESP32s
• Clean YAML Syntax - Simple addressable_wled configuration
• 11 Built-in Palettes - Easily customizable
• Smooth Transitions - Professional-grade animations
• Dynamic Controls - Speed, intensity, palette, and reverse direction

🚀 Quick Start

See QUICKSTART.md for installation and configuration instructions.

📋 Available Effects

Currently, the following core effects are fully ported and optimized:

ID	Name	Description
2	Breathe	Apple-style standby breathing LED
3	Wipe	Primary/Secondary color wipe
4	Wipe Random	Wipe with random colors
6	Sweep	Ping-pong wipe
8	Colorloop	Solid color cycling through palette
9	Rainbow	Per-pixel rainbow with density control
18	Dissolve	Random pixel color transitions
38	Aurora	Northern lights animation
63	Pride 2015	Rainbow flag with breathing motion
64	Juggle	Eight bouncing dots with trails
66	Fire 2012	Realistic fire simulation
74	Colortwinkle	Magical fairy-dust twinkles
76	Meteor	Meteor with random decay trail
91	Bouncing Balls	Real gravity physics with ball count control
97	Plasma	Smooth plasma animation
101	Pacifica	Gentle ocean waves
104	Sunrise	Gradual sunrise/sunset simulation
105	Phased	Sine wave interference pattern
110	Flow	Smooth color zones pushing each other

Tip

Why aren't all WLED effects here yet?
Bringing WLED effects to WLED-Runner takes time. Each effect is manually rewritten trying to "squeeze" every bit of performance out of the hardware with minimal resources cost. My goal is to maintain the original look while ensuring it runs perfectly on ESPHome. Thank you for your patience as I port them incrementally! (No ETA).

🎨 Available Palettes

• Default (0) - Effect-specific
• Forest (1) - Earth greens and browns
• Ocean (2) - Deep to light blues
• Rainbow (3) - Full spectrum
• Fire (4) - Red/orange/yellow
• Sunset (5) - Purple/red/orange/yellow
• Ice (6) - Cool whites and light blues
• Party (7) - Vibrant mixed colors
• Lava (8) - Black/red/orange
• Pastel (9) - Soft desaturated colors
• Pacifica (10) - Deep ocean blues with white crests
• HeatColors (11) - Sunrise gradient
• Sakura (12) - Pink/White cherry blossom
• Rivendell (13) - Green/Teal elven forest
• Cyberpunk (14) - Neon pink/cyan
• Orange & Teal (15) - Cinematic color grading
• Christmas (16) - Red/green/white holiday
• Red & Blue (17) - Continuous Gradient
• Matrix (18) - Green digital rain
• Sunny/Gold (19) - Warm white/gold
• Solid (255) - Uses current color

🎬 Intro Customization

Configure an intro animation that plays only when the light is turned on from an OFF state. Effects switched on while the light is already running will skip the intro.

Options:

• intro_effect: Select component.
  • "Wipe": Fills strip from start to end (White). Respects Reverse and Mirror.
  • "Double Wipe": Fills strip from both edges to center (White). Alias for Wipe + Mirror. (Reverse triggers Center-Out).
  • "Fade": Simple white fade-in.
  • "None": Disables intro.
• intro_duration: Number component (seconds). Controls the speed of the intro.

(Note: Intro currently uses White color for maximum visibility).

ℹ️ Architecture & Requirements

Why ESP-IDF?

This project is built strictly for the ESP-IDF framework to leverage:

• Direct RMT Access: Precise timing for addressable LEDs without Arduino overhead.
• Multitasking: Effects run on a separate core (where available) to prevent wifi blocking.
• Memory Management: Better heap control for complex effects like Pacifica.

Note: ESP8266 is explicitly NOT supported due to hardware limitations (RAM/Floating Point speed).

🙏 Credits

• WLED by Aircoookie - Original effect algorithms
• FastLED library - Color handling and utilities
• ESPHome - Framework integration

📄 License

MIT License - See LICENSE file for details.