Skip to content

ChimeraFX

Welcome to ChimeraFX

ChimeraFX is a native C++ custom component for ESPHome that brings the beauty of iconic RGB LED effects to your Home Assistant setup. By integrating these effects directly into your existing ESPHome nodes, you can run premium animations and your sensors on a single MCU, eliminating the need for a separate, dedicated lighting controller.

It allows you to run complex RGB LED effects with high performance on ESP32 devices, completely avoiding the overhead and "spaghetti code" of old YAML lambda implementations.

Is this for me?

ChimeraFX is not intended to be a full WLED replacement. You should choose the tool that best fits your hardware and requirements:

  • Install WLED if: You want the complete WLED experience (E1.31/DDP support, 150+ effects, 2D matrix, audio reactive effects, etc.) and are dedicating an MCU solely to lighting.
  • Use ChimeraFX if: You want to consolidate! If you need a single ESP32 to handle sensors, relays, or switches and run smooth, high-quality lighting effects simultaneously, ChimeraFX is for you.

Reality Check

Your mileage may vary. Visual effects are computationally expensive.

  • Use the right ESP32 for the job. Dual-core ESP32 variants have the most timing headroom. ESP32-C3 segmented RMT support is experimental and not recommended for new builds; use it only for simple or low-segment layouts, not 4-segment builds.
  • ESP32-S3 is the preferred dense 1-wire target. The parallel backend lets several SK6812 or WS2812X lanes refresh together, making the S3 the best choice for large multi-strip installations.
  • ESP32 Classic remains a strong RMT/SPI target. It is still a good fit for ordinary multi-output 1-wire nodes and high-count SPI layouts.
  • LED count matters. 1-wire NRZ strips (WS2812B, SK6812) are protocol-limited to ~800 kHz. Long strips can be transport-bound even when the effect renderer still has CPU headroom.
  • Do not mix transport families on one node. Use RMT-only, SPI-only, or parallel-only cfx_light entries. ChimeraFX rejects mixed transport configurations at compile time.
  • SPI strips (APA102, SK9822) shift the bottleneck to the CPU, not the wire. The current ESP32 Classic test rig ran 2x2000 SPI LEDs smoothly, but power delivery and inrush still matter.
  • Heavy co-residents hurt. Running ChimeraFX alongside Bluetooth Proxy or Camera components will likely cause instability.

For detailed FPS targets, RMT limits, RAM budgets, and power planning, see Performance & Troubleshooting.

When testing performance, use LedFPS as the visible strip-refresh metric. RenderFPS shows how fast ChimeraFX calculates frames, which is useful for diagnosis but can be higher than the true LED output rate on long RMT strips.

The "Good Citizen" Philosophy

ChimeraFX is built as a transparent tool designed to coexist peacefully with the rest of your ESPHome node. Unlike "greedy" implementations that sequester system resources, ChimeraFX operates under a "Good Citizen" principle: it respects the MCU's ability to handle multiple critical tasks simultaneously.

  • System Integrity: It never overwrites core ESPHome components, ensuring compatibility with future updates.
  • Intelligent Resource Sharing:
    • Memory Safety: It employs a dynamic "Heap Floor" to ensure critical stacks (Wi-Fi, API, Bluetooth) always have the memory they need to function safely.
    • Power Awareness: Includes integrated Power Monitoring & Reduction to estimate LED strip current and PSU load, with optional automatic brightness reduction to prevent hardware strain.
  • Resource Awareness: It avoids "hijacking" the CPU, allowing your sensors, climate controls, and security features to remain responsive and reliable.
  • Active Transparency: Through a built-in runtime debugger, the engine reports real-time performance metrics and memory usage, empowering you to optimize your configuration based on hard data.

This philosophy distinguishes ChimeraFX as a lighting engine that prioritizes the stability of your entire smart home ecosystem over just "showing pretty lights".

Key Features

  • Magic Buttons: Bind physical buttons to on-device dimming, CCT sweeping, hue or palette selection, and effect selection without lambdas or extra Home Assistant entities.

  • Native Performance: Optimized for ESP-IDF and dual-core ESP32s.

  • ChimeraFX Light Platform: A custom ESPHome light platform that support segments, allows you to run parallel complex RGB LED effects on ESP32 devices.
  • ChimeraFX Sequencer: High-performance logic layer for hardware-precise event triggers and responsive Home Assistant automations.
  • Power Monitoring & Reduction: Estimate LED strip current, power, PSU load, and energy usage, with optional manual or automatic brightness reduction.
  • Zero-Lambda Config: Uses a clean external_components setup.
  • Rich Effect Library: Ports of complex effects that were previously impossible or slow in pure YAML using addressable_lambda.
  • Custom Palettes: A curated selection of palettes to choose from plus a smart palette generator.
  • Intro and Outro Effects: Run a special effect when the light turns on or off.
  • Presets: Capture and recall custom configurations from a near-infinite matrix of possibilities—layering specific intro/outro transitions, granular speed and intensity settings, and dynamic palettes into a single, cohesive lighting state.
  • Full Control: Support for Speed, Intensity, Palettes, and Mirroring in real time or through presets.
  • Autotuning: Automatically load default parameters and tune the effect for you .
  • Debug Logger: An easy way to enable/disable the logger at runtime level.

Donations are never expected, but always appreciated. If you find ChimeraFX useful and would like to support its development, you can buy me a coffee here!

ChimeraFX is an independent project. It is not affiliated with, maintained by, or endorsed by the WLED project, the ESPHome project, or Nabu Casa. WLED, ESPHome, and Nabu Casa are trademarks of their respective owners.

This work incorporates some code and logic derived from WLED and is licensed under the European Union Public Licence v1.2 (EUPL-1.2).

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.