The WLED 16.0.1 LED effect engine, ported to ESPHome as an external component.
It runs WLED's effects on an ESPHome device with no WLED firmware, no FastLED and no Arduino dependency, on plain addressable strips through the light stack and on matrix panels such as HUB75 through the display stack.
All 214 of WLED's 216 effects are ported, plus the nine WLED-MM exclusives, for
223 registered effects. The two that are not ported, Image and Copy Segment, need
a filesystem and a multi-segment model this component does not have; BATCHES.md
records why.
- WLED's segment model, 32 bit lossless framebuffer, palettes and colour maths
- All 72 WLED palettes: the dynamic ones, the seven FastLED ones and the 59 cpt-city gradients
- Effects keyed by name, with their WLED defaults read out of the original metadata strings
- A compile-time allow-list, so a build only carries the effects it uses
- Addressable light effect front end, for any
light::AddressableLightdriver - Display front end, one bulk frame push per tick, hub75 aware
- Runtime control from Home Assistant and from the ESPHome web page, with no
Home Assistant needed:
select,number,switch,light,text_sensorandsensorplatforms plus actions - Per-effect control labels, read out of the WLED metadata, so a generic "Custom 1" slider says what it does in the effect that is running
- Per-effect frame timings, so the effects that are slow on a given board can be found without reflashing
- A host simulator that renders every effect to a PNG contact sheet
- A real audio source for the audio reactive effects: microphone, FFT and AGC,
ported from WLED's
audioreactiveusermod, with simulated sound as the fallback when no microphone is configured
- ESP32 family boards only. Config validation refuses the ESP8266 with a message saying so. WLED runs there, on a build that gives one effect 384 bytes of scratch against the 4096 an ESP32-S3 gets, and nothing here has ever been compiled or measured on one. An untested branch that half works is worse than a clear no.
- Barely any of this has run on real hardware. One session on an Apollo M-1,
a 64x64 HUB75 panel on an ESP32-S3, is the whole of it. Everything else is
verified in a host simulator, and every example config is verified by
compilation.
HARDWARE-CHECKLIST.mdlists what a real panel or a real microphone would settle, grouped by what you have to flash to check it. - One segment. WLED's multi-segment model is not ported, so there is one canvas, one effect and one set of controls per front end. Image and Copy Segment are the two upstream effects that need what is missing.
- The control entities do not restore across a reboot by default. A
select,numberorswitchpublishes what the YAML and the effect metadata say, so a change made from Home Assistant is lost on restart. Pin the value in YAML, or set it from anon_bootautomation. Theswitchplatform does take ESPHome'srestore_mode, defaulting toDISABLEDbecause the engine owns the checkmark; set it to something else and the switch drives the engine at boot instead. - Panels wider than 180 pixels hit upstream's own arithmetic. A handful of 2D effects hold a coordinate or a scale factor in 8 or 16 bits, which is upstream's code unchanged and is fine to the 256x64 this has been tested at, but 2D Octopus loses its radius scale above 180 and Game Of Life loses spaceship detection above about 16384 pixels with coprime dimensions. Both degrade to a duller animation rather than misbehaving.
- No transition or preset model. ESPHome owns both: the light's own
transitions apply on top of the light front end. Brightness and blanking are
the Colour 1 light, which is WLED's own arrangement, and the display front end
also takes
gamma_correct. That option is WLED's output gamma stage and nothing else; the gamma effects and the particle renderer apply while drawing is the engine's and is always on, because it is part of the picture rather than a preference. See Gamma and what the panel emits.
docs/HARDWARE-TESTING.md is the session guide for changing that first line, with four ready to flash test firmwares in examples/hardware-test and a tour mode that walks every effect.
docs/gallery is an animated preview of every effect below, with
its parameters and a copy-ready snippet. Serve it with
python -m http.server 8731 --directory docs/gallery and open
localhost:8731; it gets a GitHub Pages address too
once Pages is switched on, which
docs/gallery/README.md explains.
223 effects are registered. Names are the WLED display names and they are what an effects: allow-list, the effect: option and the select entity all use.
Which of them an output offers depends on its shape: 167 on a 1D output and 64 on a 2D output, or all 223 on a 2D output that sets include_1d_effects: true. The "Runs on" column below is what decides that; see Which effects an output offers.
1D, batch A (1d_a, 7)
| Effect | Runs on |
|---|---|
| Solid | 1D |
| Blink | 1D |
| Rainbow | 1D |
| Pride 2015 | 1D |
| Fire 2012 | 1D |
| Noise 1 | 1D |
| Plasma | 1D |
1D, batch B (1d_b, 30)
| Effect | Runs on |
|---|---|
| Wipe | 1D |
| Wipe Random | 1D |
| Sweep | 1D |
| Sweep Random | 1D |
| Strobe | 1D |
| Strobe Rainbow | 1D |
| Blink Rainbow | 1D |
| Twinkle | 1D |
| Twinkleup | 1D |
| Fairytwinkle | 1D |
| Colortwinkles | 1D |
| Twinklefox | 1D |
| Twinklecat | 1D |
| Gradient | 1D |
| Loading | 1D |
| Glitter | 1D |
| Solid Glitter | 1D |
| Dynamic | 1D |
| Dynamic Smooth | 1D |
| Rolling Balls | 1D |
| Tetrix | 1D |
| ICU | 1D |
| Oscillate | 1D |
| Sunrise | 1D |
| Stream | 1D |
| Solid Pattern Tri | 1D |
| Chunchun | 1D |
| Sine | 1D |
| Perlin Move | 1D |
| Wavesins | 1D |
1D, batch C (1d_c, 24)
| Effect | Runs on |
|---|---|
| Dissolve | 1D |
| Dissolve Rnd | 1D |
| Scan | 1D |
| Scan Dual | 1D |
| Scanner | 1D |
| Scanner Dual | 1D |
| Sinelon | 1D |
| Sinelon Dual | 1D |
| Sinelon Rainbow | 1D |
| Spots | 1D |
| Spots Fade | 1D |
| Washing Machine | 1D |
| PacMan | 1D |
| TV Simulator | 1D |
| Drip | 1D |
| Fairy | 1D |
| Meteor | 1D |
| Tri Fade | 1D |
| Traffic Light | 1D |
| Fire Flicker | 1D |
| Two Dots | 1D |
| Juggle | 1D |
| Colorloop | 1D |
| Fade | 1D |
1D, batch D (1d_d, 30)
| Effect | Runs on |
|---|---|
| Theater | 1D |
| Theater Rainbow | 1D |
| Chase 2 | 1D |
| Running | 1D |
| Saw | 1D |
| Running Dual | 1D |
| Chase Flash | 1D |
| Chase Flash Rnd | 1D |
| Random Colors | 1D |
| Pacifica | 1D |
| Noise 2 | 1D |
| Noise 3 | 1D |
| Noise 4 | 1D |
| Fill Noise | 1D |
| Noise Pal | 1D |
| Sparkle | 1D |
| Sparkle Dark | 1D |
| Sparkle+ | 1D |
| Dancing Shadows | 1D |
| Shimmer | 1D |
| Popcorn | 1D |
| Colorful | 1D |
| Aurora | 1D |
| Tri Wipe | 1D |
| Flow | 1D |
| Railway | 1D |
| Strobe Mega | 1D |
| Blends | 1D |
| Breathe | 1D |
| Flow Stripe | 1D |
1D, batch E (1d_e, 24)
| Effect | Runs on |
|---|---|
| Android | 1D |
| Chase | 1D |
| Chase Random | 1D |
| Chase Rainbow | 1D |
| Rainbow Runner | 1D |
| Lighthouse | 1D |
| Chase 3 | 1D |
| Multi Comet | 1D |
| Stream 2 | 1D |
| Lightning | 1D |
| Colorwaves | 1D |
| Bpm | 1D |
| Lake | 1D |
| Solid Pattern | 1D |
| Bouncing Balls | 1D |
| Candle | 1D |
| Candle Multi | 1D |
| Fireworks Starburst | 1D |
| Percent | 1D |
| Heartbeat | 1D |
| Phased | 1D |
| Phased Noise | 1D |
| Color Clouds | 1D |
| Slow Transition | 1D |
2D, batch A (2d_a, 3)
| Effect | Runs on |
|---|---|
| Matrix | 2D |
| Metaballs | 2D |
| Scrolling Text | 2D |
2D, batch B (2d_b, 29)
| Effect | Runs on |
|---|---|
| Black Hole | 2D |
| Colored Bursts | 2D |
| DNA | 2D |
| DNA Spiral | 2D |
| Drift | 2D |
| Firenoise | 2D |
| Frizzles | 2D |
| Game Of Life | 2D |
| Hiphotic | 2D |
| Julia | 2D |
| Lissajous | 2D |
| Noise2D | 2D |
| Plasma Ball | 2D |
| Polar Lights | 2D |
| Pulser | 2D |
| Sindots | 2D |
| Squared Swirl | 2D |
| Sun Radiation | 2D |
| Tartan | 2D |
| Spaceships | 2D |
| Crazy Bees | 2D |
| Ghost Rider | 2D |
| Blobs | 2D |
| Drift Rose | 2D |
| Rotozoomer | 2D |
| Distortion Waves | 2D |
| Soap | 2D |
| Octopus | 2D |
| Waving Cell | 2D |
Audio reactive, FFT (audio_fft, 13)
| Effect | Runs on |
|---|---|
| Gravfreq | 1D, FFT |
| Freqwave | 1D, FFT |
| Freqmatrix | 1D, FFT |
| GEQ | 2D, FFT |
| Waterfall | 1D, FFT |
| Freqpixels | 1D, FFT |
| Noisemove | 1D, FFT |
| Freqmap | 1D, FFT |
| DJ Light | 1D, FFT |
| Funky Plank | 2D, FFT |
| Blurz | 1D, FFT |
| Rocktaves | 1D, FFT |
| Akemi | 2D, FFT |
Audio reactive, particle (audio_particle, 8)
| Effect | Runs on |
|---|---|
| PS Spray | 2D, volume |
| PS GEQ 2D | 2D, FFT |
| PS GEQ Nova | 2D, FFT |
| PS Blobs | 2D, volume |
| PS GEQ 1D | 1D, FFT |
| PS Sonic Stream | 1D, FFT |
| PS Sonic Boom | 1D, FFT |
| PS Springy | 1D, FFT |
Audio reactive, volume (audio_vol, 16)
| Effect | Runs on |
|---|---|
| Ripple Peak | 1D, volume |
| Swirl | 2D, volume |
| Waverly | 2D, volume |
| Gravcenter | 1D, volume |
| Gravcentric | 1D, volume |
| Gravimeter | 1D, volume |
| Juggles | 1D, volume |
| Matripix | 1D, volume |
| Midnoise | 1D, volume |
| Noisefire | 1D, volume |
| Noisemeter | 1D, volume |
| Pixelwave | 1D, volume |
| Plasmoid | 1D, volume |
| Puddlepeak | 1D, volume |
| Puddles | 1D, volume |
| Pixels | 1D, volume |
Native 1D and 2D (1d2d, 7)
| Effect | Runs on |
|---|---|
| Fireworks | 1D, 2D |
| Rain | 1D, 2D |
| Ripple | 1D, 2D |
| Ripple Rainbow | 1D, 2D |
| Palette | 1D, 2D |
| Halloween Eyes | 1D, 2D |
| Fireworks 1D | 1D, 2D |
Particle, 1D (particle_1d, 11)
| Effect | Runs on |
|---|---|
| PS DripDrop | 1D |
| PS Pinball | 1D |
| PS Dancing Shadows | 1D |
| PS Fireworks 1D | 1D |
| PS Sparkler | 1D |
| PS Hourglass | 1D |
| PS Spray 1D | 1D |
| PS 1D Balance | 1D |
| PS Chase | 1D |
| PS Starburst | 1D |
| PS Fire 1D | 1D |
Particle, 2D (particle_2d, 12)
| Effect | Runs on |
|---|---|
| PS Fire | 2D |
| PS Fireworks | 2D |
| PS Vortex | 2D |
| PS Volcano | 2D |
| PS Ballpit | 2D |
| PS Waterfall | 2D |
| PS Box | 2D |
| PS Fuzzy Noise | 2D |
| PS Impact | 2D |
| PS Attractor | 2D |
| PS Ghost Rider | 2D |
| PS Galaxy | 2D |
WLED-MM exclusives (mm, 9)
| Effect | Runs on |
|---|---|
| Meteor Smooth | 1D |
| Party jerk | 1D, volume |
| Popcorn audio | 1D, volume |
| Multi Comet audio | 1D, volume |
| Fw Starburst audio | 1D, volume |
| Fireworks audio | 1D, 2D, volume |
| GEQ 3D | 2D, FFT |
| Paintbrush | 2D, FFT |
| Snow Fall | 2D |
external_components:
- source: github://bharvey88/esphome-wled-fx
# A bare wled_fx block is what puts the effect into the light effect registry.
wled_fx:
light:
- platform: esp32_rmt_led_strip
id: strip
name: Strip
pin: GPIO16
num_leds: 60
rgb_order: GRB
chipset: WS2812
effects:
- wled_fx:
name: WLED FX
effect: Pride 2015The engine owns the frame clock, so the display must be handed over with
update_interval: never and auto_clear_enabled: false. That is enforced at
codegen time.
display:
- platform: hub75
id: matrix
board: apollo-automation-m1-rev6
panel_width: 64
panel_height: 64
update_interval: never
auto_clear_enabled: false
wled_fx:
id: fx
display_id: matrix
update_interval: 23ms
effect: PS Fire
select:
- platform: wled_fx
wled_fx_id: fx
type: effect
name: EffectFull configurations are in examples/.
With LVGL in the same firmware. ESPHome's hub75 driver is compiled for
LVGL's colour depth, which ESPHome pins at 16 bits, and its draw_pixels_at()
then refuses a 24 bit frame with Unsupported LV_COLOR_DEPTH: 16 on every
frame. wled_fx sees LVGL in the configuration and hands that display RGB565
instead, as native little-endian words with the call saying so; esp-hub75
reads each word in the order the call declares, so this holds whatever
byte_order LVGL itself is given. output_format makes the choice explicit.
Two more things follow from LVGL being there. hub75's own validation requires
double_buffer: false in an LVGL build, so every wled_fx frame goes straight
into the buffer the panel is scanning and update() no longer flips: expect
some tearing on fast effects. And both would draw into the same panel, so
pause LVGL while an effect runs (lvgl.pause) and resume it afterwards
(lvgl.resume redraws the screen by itself). RGB565 also costs the dark end
of the picture; see Gamma and what the panel emits.
Checked on a 128x64 HUB75 panel, ESPHome 2026.8.2.
Accepts one entry or a list of them. An entry with no display_id is just the
registration stub that makes the light effect available, or the place an audio:
block lives; it never becomes a component, so it takes no control keys. Put those
on the light effect instead.
| Option | Type | Default | Notes |
|---|---|---|---|
id |
id | generated | needed to point a select, number or switch at it |
display_id |
id | none | the display to drive; makes this a display front end |
effects |
list of names | all | compile-time allow-list, see below; the lists of every entry are merged into one |
include_1d_effects |
bool | false |
offer the 1D-only effects on this display too, through WLED's 1D-to-2D mapping. See Which effects an output offers |
width / height |
int | from the display | canvas size override |
update_interval |
time | 23ms |
one rendered frame per interval, WLED's own 42 fps |
gamma_correct |
0.1 to 10.0 | 2.2 |
this is WLED's show() stage: the whole frame on its way to the display, at WLED's own default. Set it to 1.0 for an output that already applies a curve of its own, and see Gamma and what the panel emits before doing that on a hub75 panel. It is not the gamma effects and the particle renderer do while drawing, which the engine always does with WLED's real tables. See PORTING.md deviation 33 |
effect |
name | first registered | |
palette |
name | effect default | |
speed, intensity |
0 to 255 | effect default | |
custom1, custom2 |
0 to 255 | effect default | |
custom3 |
0 to 31 | effect default | |
check1, check2, check3 |
bool | effect default | |
text |
string | empty | read by Scrolling Text |
optimize |
speed, size |
speed |
compile this component's own sources at -O2 rather than ESPHome's -Os. One setting for the whole build, so every entry has to agree. See Performance |
canvas_memory |
auto, internal, psram |
auto |
where the canvas and the small per-frame buffers go. One setting for the whole build. See Performance |
loop_interval |
time, auto, never |
auto |
the main loop interval to ask ESPHome for, so the frame deadline is not rounded up to the next tick. auto is a third of update_interval, floored at 4 ms, and never longer than what the firmware already has. See Performance |
output_format |
rgb888, rgb565 |
rgb888; rgb565 with LVGL and hub75 |
the pixel format handed to the display. rgb888 is WLED's own 24 bit output. A build with LVGL and a hub75 display gets rgb565, because ESPHome's hub75 driver refuses anything else there; see Quick start, HUB75 matrix |
Every control key here, and on the light effect below, is pinned: naming
speed: in YAML keeps that value when the effect changes, and leaving it out
lets the new effect's own metadata refill it. That is the single most surprising
thing about the component, and it is what the select, number and switch
entities follow when they republish.
A control moved at runtime is pinned the same way unless something turns
pinning off. That is a deliberate difference from WLED, and the palette is
where it shows: on a WLED device, choosing Fire 2012 puts the palette back to
Fire whatever the user had picked, because the effect's metadata declares
pal=35. Here the picked palette stays. The four hardware test firmwares turn
runtime pinning off at boot with their "Pin controls" switch, so they behave as
WLED does; the plain examples have no such switch and keep it on. If a select
or number entity that "will not go back to the effect's own value" is not what
you want, add the same switch, or call
id(fx)->engine().set_sticky_controls(false); in an on_boot lambda.
The 1D-to-2D mapping is not configurable. It comes from each effect's m12
metadata key, which is what WLED's "Expand 1D FX" selector sets. The simulator's
--map can force it; the component cannot.
effects:
- wled_fx:
id: strip_fx # optional, for the select/number/switch platforms
name: WLED FX
width: 16 # for a matrix wired as one strip
height: 16
serpentine: true
use_light_color: true # the light's own colour becomes segment colour 1
include_1d_effects: true # only on a matrix, see below
update_interval: 23ms
# plus every control key from the table abovewidth and height describe a matrix wired as one strip. Give both or neither:
width on its own leaves the height at one, which is a strip. Giving both makes
this a 2D output, with everything that follows from it in
Which effects an output offers, and giving
neither makes it a 1D one.
Each wled_fx: entry in a light's effects: list owns a canvas of its own, and
keeps it once it has run, so two of them on one light hold two canvases. Turning
the light off puts the effect back to frame zero but does not hand the memory
back; see the memory note under Licence.
WLED corrects the finished frame once, with gamma 2.2, in show(), and the
LED driver gets the corrected bytes. This component's display front end is that
stage, and since v0.4.0 it carries the same default. A mid grey of 128 in the
engine buffer leaves as 56, which is what a WLED device sends.
Two things sit either side of it and both matter.
A hub75 panel. WLED's HUB75 builds compile the panel library with
-D NO_CIE1931, so nothing after show() touches the value. ESPHome's hub75
driver applies CIE1931 by default, which on top of gamma 2.2 is two curves and
a panel far darker than a WLED one. The four shipped matrix configurations set
gamma_correct: LINEAR on the display for that reason, and a configuration
that does not gets a warning at validation naming both curves. The other way
round, gamma_correct: 1.0 on wled_fx with the driver left on CIE1931, is a
reasonable look and is not WLED's.
A hub75 panel in an LVGL build gets RGB565 (see the quick start), and the
quantisation happens after this stage: red and blue keep five bits, green six.
With gamma 2.2 that folds every canvas value below 53 (38 for green) into
black, where the 24 bit path still sends 1 to 7 and the panel shows faint
embers; slow fades and the particle fire lose their tails. For that build the
other ordering is the better one: gamma_correct: 1.0 on wled_fx and the
driver's CIE1931 left on, so the 32 levels are spent on linear values and the
curve runs on the widened 8 bit value inside the driver.
A light. ESPHome owns the output stage of a light, its gamma_correct
defaults to 2.8, and it corrects after its own brightness scaling where WLED
corrects before. Set gamma_correct: 2.2 on the light, as the strip examples
now do, and a full brightness strip matches a WLED one. A dimmed strip does
not: at half brightness a buffer value of 128 reaches a WLED strip as 28
(gamma2.2(128) * 128/255) and an ESPHome strip as 5 (gamma2.8(64)). There
is no setting that fixes the ordering, because the light applies the curve
itself after this component has handed over the frame.
| engine buffer | WLED, and this display front end at 2.2 | display front end at 1.0 | light at ESPHome's 2.8 |
|---|---|---|---|
| 32 | 3 | 32 | 1 |
| 64 | 12 | 64 | 5 |
| 128 | 56 | 128 | 37 |
| 192 | 137 | 192 | 115 |
| 215 | 175 | 215 | 158 |
The last row is Matrix's spawn pixel. The effect builds it as
gamma8inv(175) so that the output stage turns it back into 175, which is the
round trip this table is really about.
WLED's audio reactive effects read one shared analysis struct: a smoothed volume,
a 16 channel graphic equaliser, a dominant frequency and a beat flag. With no
microphone configured they run on WLED's own simulateSound(), so every audio
effect animates out of the box and nothing has to be set up to try them.
Point audio: at a microphone and they run on real sound instead. This is a port
of WLED's audioreactive usermod: the same pre-filter, the same 512 point FFT,
the same GEQ bin mapping with its pink noise correction, the same AGC presets and
the same post-processing.
microphone:
- platform: i2s_audio
id: board_mic
i2s_audio_id: i2s_mic_bus
i2s_din_pin: GPIO12
adc_type: external
channel: left
bits_per_sample: 32bit
sample_rate: 22050
wled_fx:
id: fx
display_id: matrix
effect: GEQ
audio:
microphone: board_mic
agc: normalThe block sits on a wled_fx entry, but the analysis source is process wide:
there is one canvas and one segment, so one microphone serves both front ends.
An entry that carries nothing but audio: is the normal way to give the light
effect a microphone, and only one entry may carry the block.
| Option | Type | Default | Notes |
|---|---|---|---|
microphone |
microphone source | required | microphone, bits_per_sample, channels, gain_factor, exactly as sound_level takes them. One channel of 16 bit audio |
passive |
bool | false |
leave the microphone to another component to start and stop, and only listen in. Only useful when something else, a voice assistant or sound_level, is already running that microphone; on its own it leaves the analysis permanently silent |
gain |
0 to 255 | 60 |
WLED sampleGain, the manual input gain. Ignored while AGC is on |
squelch |
0 to 255 | 10 |
WLED soundSquelch, the noise gate |
input_level |
0 to 255 | 128 |
WLED inputLevel, and 128 is unity. With AGC off it multiplies the pre-amplifier on both the volume and the GEQ channels, alongside gain. With AGC on the AGC owns that stage, and input_level becomes a post-amplifier on the GEQ channels only, softened below unity so it cannot mute them |
agc |
off, normal, vivid, lazy |
normal |
WLED's three AGC presets, a PI controller over the input level |
scaling |
none, log, linear, sqrt |
sqrt |
WLED FFTScalingMode, how a GEQ channel maps to 0 to 255 |
limiter |
bool | true |
WLED's dynamics limiter on the smoothed volume |
attack / decay |
time | 80ms / 1400ms |
limiter attack and decay, and the decay picks the GEQ fall-off curve |
mic_filter |
bool | false |
an IIR band pass, 90 Hz to 20 kHz, over the raw samples |
bandpass |
bool | false |
WLED's alternative bin mapping that ignores everything under 100 Hz |
task_in_psram |
bool | false |
put the analysis task's stack in PSRAM |
Notes worth knowing before you tune it:
- Sample rate. 22050 Hz is what the usermod assumes and is the best match for its bin mapping. Any rate the microphone supports works: the GEQ bin ranges are rescaled from upstream's 22050 Hz reference so each channel keeps the frequency band WLED gave it, and the dominant frequency is reported in Hz either way.
- The noise gate is aggressive. Upstream's gate zeroes the filter state, not
just its output, so a signal has to be roughly five times
squelchbefore anything passes at all. If everything stays dark, lowersquelchbefore reaching forgain. - Prefer
agcovergain_factor. The microphone source'sgain_factoris a plain integer multiplier applied before the analysis; the AGC is a controller that tracks the room. - ESP32 only, because ESPHome's
microphoneis.
The FFT runs on its own FreeRTOS task, never in the render loop, and every buffer
it uses is allocated once at setup. On ESP32 it uses espressif/esp-dsp, which
ESPHome already pins, so this adds no new third party dependency: the ESP32
assembly kernel on a plain ESP32, the S3 one on an S3, and the library's ANSI C
one elsewhere. The host simulator, and any target without esp-dsp, falls back to a
small radix-2 transform in wf_fft.cpp, and the analysis itself is identical
either way.
Enabling audio on an ESP32 costs about 55 to 60 KB of flash and 9 KB of static
RAM, most of it the microphone, i2s_audio and audio components rather than
the analysis, plus a 12 KB task stack and an 11 KB ring buffer at runtime.
Not every effect runs on every shape of output, so a wled_fx front end offers
the ones that do and hides the rest. The shape is fixed by the configuration,
so this is decided when you build rather than guessed at runtime.
| Output | What it is | What it offers |
|---|---|---|
| 1D | an addressable light with no width and height |
1D effects and 1D+2D effects |
| 2D | any display, or a light given width and height |
2D, 1D+2D, 2D particle and 2D audio effects |
A 2D-only effect on a strip paints a solid colour and nothing else, which is what WLED does too and is never what anybody meant, so it is not offered and there is no way to ask for it. A 1D effect on a matrix does work, through WLED's own 1D-to-2D mapping, but a line stretched over a panel is rarely what somebody was after, so those are hidden by default and one option brings them back:
wled_fx:
id: fx
display_id: matrix
include_1d_effects: trueThat is the one line an error message will tell you to add. Naming an effect the
configured output cannot run is a configuration error that says which case it is
and what to do about it, the select entity only lists what is offered, and an
action or an API call asking for something else logs a warning and is ignored
rather than leaving the panel on a solid fill.
It also decides what gets compiled. With no effects: allow-list, a build whose
only outputs are matrices carries only the effects a matrix can show, so the
1D-only effects cost nothing. Measured on examples/m1-hub75.yaml, an ESP32-S3
esp-idf build: 839,979 bytes of flash with the 64 effects a matrix offers and
900,903 with include_1d_effects: true and all 223, so the 159 effects a panel
was never going to show are 60,924 bytes, about 59 KB. RAM is identical to
the byte, because the canvas is sized from the panel and not from the effect
list. The two totals move with the ESPHome version; the difference between them
does not.
effects: and include_1d_effects are independent. The allow-list narrows what
is built; this decides what a given output may show of it. An allow-list naming
something no configured output could ever show is an error, because it would be
flash spent on nothing.
Dimensionality comes from each effect's own WLED metadata, with one exception.
Flow Stripe's metadata string has no dimensionality group at all, so the
fourth ; group that WLED and this port both read as one is really its
defaults; the answer that falls out is right and the reasoning is not. The
FLAG_OVERRIDES table in components/wled_fx/wf_registry.cpp pins it, and both
the firmware and the config validation read that one table.
A configuration that names a 1D effect on a display, or on a light with a
width and a height, used to build and now fails with an error naming the one
line to add. Two ways out, and the error says both: add
include_1d_effects: true to keep exactly what you had, or pick a 2D effect and
take the flash back. Nothing on a plain strip changes.
Listing effects compiles only those in. Measured on an ESP32 with esp-idf, on a
config stripped to nothing but the light and the component so the delta is all
effects: 343,343 bytes of flash with all 223 compiled in, 226,115 with an
allow-list naming one, so the other 222 effects are 117,228 bytes, about 114 KB.
RAM is the same either way, within a hundred bytes, because the canvas is sized
from the strip and not from the effect list. PLAN.md records the config and
the whole-firmware figures for the four examples.
wled_fx:
effects:
- Fire 2012
- RainbowNames are the WLED display names, case insensitive. A name that matches nothing
is a configuration error, with the nearest registered name suggested. The same
check applies to effect: and palette: anywhere they appear, so a typo is
caught at esphome config time rather than silently leaving the device on
whatever it booted with.
select:
- platform: wled_fx
wled_fx_id: fx
type: effect # or palette
name: Effect
# `scope` narrows an effect list. `all`, the default, is everything this
# output offers. On a matrix with include_1d_effects: true that is all 223
# and two thirds of them are 1D effects drawn through WLED's 1D-to-2D
# mapping, which look like a line crawling across the panel. `panel` lists
# what a 2D output offers without the opt-in and `strip` lists what a 1D
# output offers, both read from the same rule the component enforces, so a
# panel can have one dropdown of the effects that suit it and a second,
# named for what it is, holding the mapped ones. While an effect outside
# its scope is running, a select holds its last value.
scope: all # or panel, strip
number:
- platform: wled_fx
wled_fx_id: fx
type: speed # intensity, custom1, custom2, custom3
name: Speed # the range is fixed by the type, 0 to 255 or 0 to 31
switch:
- platform: wled_fx
wled_fx_id: fx
type: check1 # check2, check3
name: Check 1
# The three WLED colour slots. A light is the only ESPHome entity that renders
# as a colour picker, in web_server and in Home Assistant both.
light:
- platform: wled_fx
wled_fx_id: fx
type: color1 # color2, color3
name: Color 1
# What those generic controls are called in the effect that is running, read
# out of its WLED metadata and republished on every effect change. Controls the
# effect does not use are left out.
# Effect speed · Effect intensity: Spawning rate · Custom 1: Trail · Check 1: Custom color
# Color 1: Spawn · Color 2: Trail
text_sensor:
- platform: wled_fx
wled_fx_id: fx
type: controls # or colors
name: Effect controls
# Microseconds per frame, averaged over the time the current effect has been
# running, with its first second left out.
sensor:
- platform: wled_fx
wled_fx_id: fx
type: render_time # or output_time
name: Effect render timeColour 1 is also the master, as it is in WLED: its brightness scales the whole
finished frame and turning it off blanks a panel driven by the display front
end. Colour 2 and colour 3 are plain slots, so their brightness dims that
colour and off makes it black. On the light front end set use_light_color: false if you want colour 1 to come from this entity rather than from the
light's own colour.
Actions: wled_fx.set_effect, wled_fx.next_effect, wled_fx.set_palette,
wled_fx.set_text, wled_fx.set_speed, wled_fx.set_intensity,
wled_fx.set_custom1 to set_custom3, wled_fx.set_check1 to set_check3,
wled_fx.set_color.
- wled_fx.set_color:
id: fx
color: 2 # 1, 2 or 3
red: 255
green: 170
blue: 0The frame gate targets WLED's own 23 ms, about 43 fps. Whether an effect reaches it depends on the board, the canvas size and the effect.
Measured on an Apollo M-1, an ESP32-S3 at 240 MHz with octal PSRAM driving a 64x64 HUB75 panel, against a WLED 16.0.1 device on the same panel: at v0.4.1 this port held 40 fps or better on 58 of its 223 effects with a median of 34.6 fps, where WLED holds it on 199 of 216 with a median of 43.0. v0.5.0 is about closing that. On the host benchmark, over all 223 effects at 64x64, a frame went from 94.0 us to 54.8 us, a factor of 1.71, with no pixel of any frame of any effect changing.
Three options control it, and each can be turned off on its own.
ESPHome compiles a firmware with -Os on both frameworks. That is right for a
firmware, which is mostly setup code, and wrong for a per-pixel loop that runs
43 times a second, which is why WLED compiles its own hottest functions with
__attribute__((optimize("O2"))).
optimize: speed, the default, puts this component's own translation units, and
nothing else in the build, on -O2 through a #pragma GCC optimize in
wf_optimize.h. optimize: size leaves them at -Os. It is one flag for the
whole build, so every wled_fx: entry has to agree and config validation says
so rather than taking the last one.
The flash cost, ESPHome 2026.8.2:
Image size in bytes, ESPHome 2026.8.2, esphome compile of each example:
| Configuration | v0.4.1 | v0.5.0 optimize: size |
v0.5.0 optimize: speed |
speed costs |
|---|---|---|---|---|
examples/m1-hub75.yaml |
883,027 | 882,567 | 894,643 | +12,076 |
examples/m1-hub75-audio.yaml |
937,107 | 936,707 | 948,567 | +11,860 |
examples/strip-esp32.yaml |
888,287 | 888,267 | 911,475 | +23,208 |
examples/strip-esp32-arduino.yaml |
975,659 | 975,451 | 998,587 | +23,136 |
hardware-test/m1-test.yaml |
1,036,315 | 1,036,215 | 1,069,655 | +33,440 |
hardware-test/m1-test-audio.yaml |
1,096,123 | 1,095,975 | 1,132,335 | +36,360 |
hardware-test/matrix-test.yaml |
1,024,251 | 1,023,459 | 1,056,331 | +32,872 |
hardware-test/strip-test.yaml |
977,919 | 977,783 | 1,004,163 | +26,380 |
optimize: size lands within a few hundred bytes of v0.4.1 on every one
of them, and slightly under it, because the two 2D pixel accessors moved
into a header and stopped being emitted as functions. So the column to read
is the last one: speed costs 12 KB on a matrix build that compiles only the
64 effects a matrix offers, and up to 36 KB on a build carrying all 223.
Statically allocated RAM, bytes:
| Configuration | v0.4.1 | v0.5.0 optimize: size |
v0.5.0 optimize: speed |
|---|---|---|---|
examples/m1-hub75.yaml |
126,411 | 126,691 | 126,691 |
examples/m1-hub75-audio.yaml |
135,331 | 135,603 | 135,603 |
examples/strip-esp32.yaml |
126,115 | 126,155 | 126,147 |
examples/strip-esp32-arduino.yaml |
126,883 | 126,907 | 126,899 |
hardware-test/m1-test.yaml |
129,959 | 130,303 | 130,303 |
hardware-test/m1-test-audio.yaml |
140,239 | 140,591 | 140,591 |
hardware-test/matrix-test.yaml |
129,619 | 129,707 | 129,707 |
hardware-test/strip-test.yaml |
129,619 | 129,643 | 129,635 |
The setting does not move RAM. The few hundred bytes v0.5.0 adds are the new lookup table and the cached geometry, not the optimisation level.
ESPHome's default allocator prefers PSRAM. The canvas is 16 KB on a 64x64 panel and every effect reads and writes it several times a frame in scattered order, which is the access pattern PSRAM is worst at.
canvas_memory: auto, the default, asks for internal RAM for the canvas, the
frame buffer and the small per-frame scratch buffers, then looks at what is left
and hands the block back if taking it would leave less than 48 KB of internal
heap or no free block of 16 KB. Wifi, the API and OTA all want internal RAM
after setup() has run, and a panel that renders fast and cannot join a network
is not a trade worth making. internal takes it whenever the allocation
succeeds at all. psram never does, which is v0.4.1's behaviour.
The effect scratch block is deliberately left in PSRAM whatever this is set to: it reaches 25 KB on the particle effects and would be competing with the canvas for exactly the memory the canvas needs.
The floors are deliberately cautious, because a device that renders fast and
cannot join a network is a worse outcome than one that renders at v0.4.1's
speed. If dump_config says the canvas went to external RAM on a board you know
has room, canvas_memory: internal takes it anyway; that is what the log line
is there for.
dump_config prints the policy, where each buffer landed and how much internal
heap is left:
[C][wled_fx]: WLED FX display:
[C][wled_fx]: Canvas: 64x64
[C][wled_fx]: Main loop interval: 7 ms
[C][wled_fx]: Optimised for: speed
[C][wled_fx]: Memory policy: auto (canvas in internal RAM, frame buffer in external RAM)
[C][wled_fx]: Internal heap free: 58240 bytes, largest block 22528
ESPHome runs its component phase at most every 16 ms. A 23 ms frame deadline against a 16 ms tick is meant to alternate one tick and two for an average of 23 ms, and for a cheap effect it does. It stops working as soon as a rendered tick runs long: ESPHome times the next tick from the start of the last one, so a tick that took 19 ms pushes the one after it a further 16 ms out, the deadline falls in the gap and the frame lands at 35 ms instead of 23.
loop_interval: auto, the default, asks ESPHome for a third of update_interval
floored at 4 ms, so the gate lands within one short tick of every deadline. It
only ever lowers the interval and never raises it, so nothing else in the
firmware loses responsiveness it already had, and the frame gate still
accumulates its deadline, so nothing renders faster than it was asked to. The
cost is that every component's loop() is polled more often, which on a mains
powered panel is idle time being spent.
This is the one setting here that changes something outside this component.
loop_interval: never leaves ESPHome's own value alone, and it is the first
thing to try if anything else in a firmware starts behaving oddly.
It is a display front end option and the light effect has no equivalent, which is deliberate rather than an omission: the quantisation only bites when a rendered tick overruns 16 ms on its own, and that takes a canvas of thousands of pixels. A 60 LED strip, or a 16x16 matrix on the light path, renders in microseconds and the alternating pattern the frame gate was designed around works exactly as intended.
The two per-effect sensors are always compiled in:
sensor:
- platform: wled_fx
wled_fx_id: fx
type: render_time # or output_time
name: Effect render timerender_time is microseconds in the effect function and output_time is
microseconds from the canvas to the output, both averaged over the time the
current effect has been running with its first second left out. On the M-1 the
output side is a flat figure for every effect, most of it inside the HUB75
driver turning pixels into bit planes; PORTING.md section 11 has the whole
accounting, including what a second core would and would not buy.
On the host, tools/wsl/wfx.ps1 bench times every effect and
tools/wsl/wfx.ps1 golden checks that none of them draws anything different.
Renders every effect at 16x16, 64x64, 60x1, 64x32, 32x64 and 31x17, checks the framebuffer guard bands after every frame, checks that no two effects derive the same allow-list macro or the same output file name, and writes a PNG contact sheet per effect.
cmake -S tools/sim -B tools/sim/build -G Ninja
cmake --build tools/sim/build
tools/sim/build/wled_fx_sim --out tools/sim/out
--effect NAME, --group NAME, --palette N, --frames N, --size WxH,
--map N, --speed N, --intensity N, --text STRING, --no-images and
--list narrow it down. --speed, --intensity and the --custom and
--check options are how a state seen on hardware gets reproduced here, since
a control left over from a previous effect is what most "this effect is broken"
reports turn out to be. --map only applies to
effects that can run in 1D, because that is the only place the 1D to 2D mapping
means anything. -DWLED_FX_SANITIZE=ON adds ASan and UBSan on toolchains
that have them.
--size is how the geometries the defaults do not cover get run: 1x1, 1x2,
2x1 and 3x1 for the division-by-a-tiny-length class of bug, and 128x64,
256x64 and 1000x1 for the does-this-index-still-fit class. CI runs the small
ones next to the sanitizers and the large ones in a second job without them,
because a 256x64 frame is sixteen times a 64x64 one and the sanitizers cannot
afford it.
Contact sheets are large, about 726 MB for a full run, so CI only renders and uploads them on a manual run or a tag, and keeps them for five days. Every push still runs every effect; it just does not draw the pictures.
The same build produces wled_fx_audio_test, which feeds synthetic PCM through
the audio processing core, the same code the firmware runs, and checks the
answers: a 1 kHz sine lights the right GEQ channel and reports the right
frequency, a sweep walks up the channels, a kick drum pulse train fires the beat
flag, silence and anything under the squelch stay dark, the AGC presets wind the
gain up and down, and the bin mapping still works at 16000, 32000 and 44100 Hz.
Add --verbose to see every band.
It also produces wled_fx_effect_test, which answers the questions a still
image cannot: which way Scrolling Text moves across a 64x64 panel and that its
glyphs are upright at the metadata defaults, that a control set with sticky
controls off does not follow you into the next effect, that custom3 is five
bits everywhere, and that every effect's control labels parse to something
readable that fits in a Home Assistant state.
Read PORTING.md. It has the exact transform table, the file conventions, how the
metadata string is parsed, the traps, and the workflow for porting a batch of
effects in parallel with other people.
BATCHES.md is the work breakdown: it assigns every WLED 16.0.1 effect that is not
ported yet to exactly one batch, one translation unit and one branch, so the
batches cannot collide.
GPL-3.0-or-later.
The effect engine, palettes, colour maths and effect bodies are derived from WLED at v16.0.1, which is licensed under the EUPL v1.2 or later. EUPL-1.2 Article 5 allows a derivative that is combined with a work under a compatible licence to be distributed under that compatible licence, and the EUPL Appendix lists GPL-3.0. Every derived file either carries its own header naming the upstream file and authors, or points at the sibling header that does.
Parts of the scaling, wave and colour container code, and seven of the palettes,
originate in FastLED 3.6.0 and stay under
the MIT licence, with the notice reproduced in
components/wled_fx/wf_math.h.
The bitmap fonts come from WLED's console fonts, credited upstream to raster-fonts. The gradient palettes come from cpt-city.
The Python side of the component is independent work and holds no effect list, palette data or parameter tables copied from WLED: it reads what it needs out of the C++ sources at config time. Everything WLED-derived is on the C++ side, so the Python can be relicensed when it goes upstream into ESPHome's MIT-licensed Python tree. As shipped here it is GPL-3.0-or-later like the rest of the repo.
Nine effects come from WLED-MM, the
MoonModules fork, rather than from WLED itself: Meteor Smooth, Party jerk,
Popcorn audio, Multi Comet audio, Fw Starburst audio, Fireworks audio, GEQ 3D,
Paintbrush and Snow Fall. They all live in
components/wled_fx/wf_effects_mm.cpp.
WLED-MM as a whole is EUPL-1.2-or-later, the same licence as upstream WLED, so the same Article 5 compatibility route to GPL-3.0-or-later applies. Two of the nine carry their own notice on top of that, and both are reproduced verbatim in the source above the effect they belong to:
- Paintbrush carries an explicit GPLv3 grant block,
@license GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007, and the standard "free software ... either version 3 of the License, or (at your option) any later version" paragraphs. Author@TroyHacks, copyright "(c) 2024 Github MoonModules Commit Authors". - GEQ 3D is labelled two different ways four lines apart upstream. Its file
block says
@license Licensed under the EUPL-1.2 or later; the first comment insidemode_GEQLASERsays@license GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007. Both statements are quoted in full in the source rather than one being chosen. Author@TroyHacks, copyright "(c) 2024 Github MoonModules Commit Authors". The contradiction is unresolved upstream and only the authors can settle it; it does not block this port, because EUPL-1.2-or-later and GPLv3 are each compatible with GPL-3.0-or-later.
Snow Fall is credited upstream to Brandon Butler, Multi Comet audio to
@softhack007, Party jerk to @tonyxforce and the merged Meteor core to
@dedehai; all four are plain EUPL-1.2-or-later.
The 51 ANIMartRIX effects WLED-MM also ships are not ported and must not be: they are CC BY-NC 3.0, which is not compatible with GPL-3.0-or-later. The ARTI-FX scripting interpreter and the three IMU games are out of scope for a different reason, that they are not effects.