Skip to content

About

WLED 16.0.1 LED effect engine ported to ESPHome as an external component

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

esphome-wled-fx

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.

What works today

  • 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::AddressableLight driver
  • 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_sensor and sensor platforms 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 audioreactive usermod, with simulated sound as the fallback when no microphone is configured

Known limitations

  • 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.md lists 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, number or switch publishes 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 an on_boot automation. The switch platform does take ESPHome's restore_mode, defaulting to DISABLED because 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.

Effects

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

Quick start, addressable strip

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 2015

Quick start, HUB75 matrix

The 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: Effect

Full 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.

Configuration

wled_fx:

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.

The light effect

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 above

width 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.

Gamma and what the panel emits

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.

Audio reactive effects

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: normal

The 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 squelch before anything passes at all. If everything stays dark, lower squelch before reaching for gain.
  • Prefer agc over gain_factor. The microphone source's gain_factor is a plain integer multiplier applied before the analysis; the AGC is a controller that tracks the room.
  • ESP32 only, because ESPHome's microphone is.

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.

Which effects an output offers

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: true

That 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.

Upgrading from 0.2.x

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.

Trimming the build

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
    - Rainbow

Names 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.

Platforms and actions

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 time

Colour 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: 0

Performance

The 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.

optimize:

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.

canvas_memory:

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

loop_interval:

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.

Measuring it

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 time

render_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.

Host simulator

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.

Contributing an effect

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.

Licence

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.

WLED-MM derived effects and their licences

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 inside mode_GEQLASER says @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.

About

WLED 16.0.1 LED effect engine ported to ESPHome as an external component

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages