Installation & Setup

Prerequisites

ESPHome Version: The minimum version to run ChimeraFX for ESPHome is 2026.7.0
Supported Hardware:
- ESP32 (Classic): Fully supported and still a strong choice for ordinary RMT and SPI nodes, especially when you need several moderate 1-wire outputs.
- ESP32-S3: Fully supported and the preferred target for dense 1-wire installations. Use the parallel backend for high LED counts, multi-lane SK6812/WS2812X layouts, or heavily segmented strips.
- ESP32-C3: Experimental for segmented RMT and not recommended for new builds. Use it only for simple or low-segment layouts; avoid 4-segment builds.
- Other ESP32 variants (S2, P4, C6, H2, etc.): Untested. Dual-core variants are expected to work; single-core variants are not recommended for the same reasons as the C3. Community reports welcome.
- ESP8266 (and variants): Supported for cfx_sync over UDP as a follower, satellite, or controller using a normal ESPHome light, PWM light, or Tuya light. It cannot run cfx_light or ChimeraFX effects because it lacks the FPU and RAM required by the rendering engine. ESP8266 cannot be a ChimeraFX sync leader.
Framework: cfx_light supports both ESP-IDF and Arduino on ESP32. ESP8266 Sync-only nodes use ESPHome's normal ESP8266 platform.

ESPHome 2026.7 uses the native ESP-IDF build toolchain by default on ESP32, including when the Arduino framework is selected. This is the recommended path for ChimeraFX, and the normal framework: type: esp-idf configuration below is all you need. Do not add a toolchain: option unless you intentionally want to override ESPHome's default.

ESPHome 2026.7 also treats an explicit brightness of 0 as OFF. ChimeraFX already sends ON/OFF separately and preserves the last non-zero brightness. No ChimeraFX YAML change is needed. Only custom lambdas that deliberately set brightness to 0 should be reviewed: a later bare turn-on will use 100% unless that turn-on also provides a brightness.

Before You Flash a `cfx_light` Node

This section applies to ESP32 nodes running cfx_light. Addressable LEDs are picky about wiring and power. Before your first compile and flash:

Connect the LED strip ground and ESP32 ground together.
Use a power supply sized for your LED count and expected brightness.
Use a level shifter for serious 5V strip builds; ESP32 data pins are 3.3V.
Keep the data wire from the ESP32 to the first LED short.
Plan power injection for longer strips instead of feeding everything from one end.

For flicker, random colors, resets, SPI inrush, and memory pressure, see Performance & Troubleshooting.

Keep each ESP32 node running cfx_light on one LED transport family: RMT-only, SPI-only, or parallel-only. Mixed transport cfx_light entries are blocked at compile time; use separate ESP32 controllers if your installation needs multiple transport families.

You can install the component in two ways:

1. Declaring the External Component

ESPHome will download the component directly from GitHub at compile-time.

Add this to your esphome.yaml:

external_components:
  - source: github://effelle/ChimeraFX@main
    refresh: always

Do not add a components: list for the normal GitHub install. If you keep an old allow-list, ESPHome will only import those named components; using cfx_button: then requires cfx_button to be present in that list.

⚠️ About refresh: always

Setting to always forces ESPHome to download the absolute latest version of the code every time you compile.

Pros: You always get the newest features and bug fixes immediately.
Cons: If something breaks in main branch, your build might break too!

For Production Stability: Once you have a working setup, it is safer to remove refresh: always or pin to a specific commit hash. This ensures your lights keep working even if the repository changes.

2. Advanced Manual Installation

If you are developing, need to modify the code locally, or prefer not to rely on the GitHub repository, you can manually copy the component to your ESPHome config directory:

Download the repository's components/ folder.
Copy its contents into your ESPHome config directory so the component folders live at paths such as config/components/cfx_light and config/components/cfx_effect.
Point your configuration to the local folder:

external_components:
  - source: components
    components: [cfx_light, cfx_effect, cfx_effect_registry, cfx_sequence, cfx_power, cfx_button]

If you use a local or manual allow-list, include every ChimeraFX component you use and their shared support components. In particular, cfx_effect requires cfx_effect_registry. Omitting an entry from this list makes ESPHome report Component not found even when the folder exists.

Complete Minimal Example

If you already have a working ESPHome device YAML, you only need the external_components block and the light block shown below. This complete example is here as a known-good starting point for a new ESP32 node:

esphome:
  name: chimera_led_demo
  friendly_name: Chimera LED Demo

esp32:
  board: esp32dev
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

logger:

api:

ota:
  - platform: esphome

external_components:
  - source: github://effelle/ChimeraFX@main
    refresh: always

light:
  - platform: cfx_light
    name: "LED Strip"
    id: led_strip
    pin: GPIO16
    num_leds: 60
    chipset: WS2812X

After the first successful compile, consider removing refresh: always or pinning to a known working commit for a more stable production device.

Quick Light Configuration

ChimeraFX introduces its own high-performance, asynchronous DMA LED driver called cfx_light. This component automatically detects your ESP32 model and allocates the optimal memory blocks for flawless, jitter-free animation.

Example config for 1-wire NRZ strips (WS2812X, SK6812, WS2811):

light:
  - platform: cfx_light
    name: "LED Strip"
    id: led_strip
    pin: GPIO16             # Remember to select the correct pin for your board
    num_leds: 60            # Number of LEDs in your strip
    chipset: WS2812X        # WS2812X, SK6812, WS2811, etc.

Example config for 2-wire SPI strips (APA102, SK9822):

light:
  - platform: cfx_light
    name: "LED Strip"
    id: led_strip
    data_pin: GPIO23       # Data pin required for SPI strips
    clock_pin: GPIO18      # Clock pin required for SPI strips
    spi_speed: 15MHz       # SPI speed for SPI strips
    num_leds: 60           # Number of LEDs in your strip
    chipset: SK9822        # APA102, SK9822

For a full overview of the cfx_light platform, please refer to the cfx_light documentation.

Adding Effects Manually (Without `all_effects`)

If you prefer not to use all_effects: true, or want to create custom presets you can manually include specific effects:

    effects:
      - addressable_cfx:
          name: "Kaleidos" # The display name of the effect (Required, customizable)
          effect_id: 155   # The ChimeraFX effect ID (Required)

      - addressable_cfx:
          # Add more effects here

The necessary YAML to declare each single effect is available on the Effects-Library.md page.

Dependencies

The component handles its own dependencies automatically. You don't need to install anything else manually.