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 a dual-core ESP32. Single-core devices are not recommended. ESP32-C3 RMT output is experimental in V1.41 after physical tests showed visible artifacts even with stable LedFPS readings — see the hardware compatibility table.
  • For V1.41, ESP32 Classic is the preferred target for new multi-output installs. It has the strongest validated RMT performance in this release.
  • LED count matters. 1-wire NRZ strips (WS2812B, SK6812) are protocol-limited to ~800 kHz. On ESP32 Classic, V1.41 testing with the heavy Energy effect at default values showed 360 LEDs per GPIO as the near-60 LedFPS target and 600 LEDs per GPIO as the 30+ LedFPS target.
  • ESP32-S3 is a 2-output target in V1.41. Due to its notably smaller RMT symbol pool (192 symbols vs 512 on the Classic), just a maximum of 2 RMT or 2 SPI outputs per node is allowed. The first RMT output utilizes GDMA for optimal timing; work on a new parallel LED driver to unlock higher S3 output density is currently the top priority for upcoming releases.
  • Do not mix RMT and SPI on the same V1.41 node. Physical testing showed that sustained SPI traffic can disturb RMT timing on ESP32 Classic. Use RMT-only or SPI-only nodes, or split the transports across separate controllers. ChimeraFX will reject the configuration if you attempt to mix RMT and SPI.
  • 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

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