add() [2/9]

fl::ChannelPtr CFastLED::add ( const fl::ChannelConfig & config )

static

Add LED channel with runtime configuration (from ChannelConfig)

Creates and registers a Channel-based LED controller with runtime-configurable timing. Returns a shared_ptr handle for later inspection, reconfiguration, or removal. FastLED retains its own reference until remove(channel) is called.

Parameters

config

Channel configuration (pin, timing, leds, rgb order, settings)

Returns

Shared pointer to Channel (extends CLEDController), or nullptr if unsupported

Note

Supported platforms: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

Example:

auto timing = fl::makeTimingConfig<fl::TIMING_WS2812_800KHZ>();
fl::ChannelConfig config(PIN_DATA, timing, fl::span<CRGB>(leds, NUM_LEDS), RGB);
auto channel = FastLED.add(config);
fill_solid(leds, NUM_LEDS, CRGB::Red);
FastLED.show();
FastLED.remove(channel);  // Unregister and release FastLED's reference

Definition at line 817 of file FastLED.cpp.hpp.

                                                                     {
    // Issue #2459: the non-template `FastLED.add(cfg)` path is the runtime-
    // selection mode. To make sure `cfg.options.mBus` (or priority dispatch
    // when `mBus == Bus::AUTO`) can actually find the requested driver at
    // runtime, we eagerly enroll every driver available on this platform.
    // That trades binary size for ergonomics — the user wanted runtime
    // selection, so they get runtime selection.
    //
    // For minimum binary size, callers should use the compile-time path:
    //   FastLED.addLeds<CHIPSET, PIN, ORDER, fl::Bus::X>(leds, n);
    // which ODR-uses only `BusTraits<X>::instancePtr()` and lets
    // `--gc-sections` drop every other driver TU.
    //
    // The warning fires at most once per process (FL_WARN_ONCE) and can be
    // disabled with `-DFASTLED_SUPPRESS_RUNTIME_DRIVER_WARNING`.
    #ifndef FASTLED_SUPPRESS_RUNTIME_DRIVER_WARNING
    FL_WARN_ONCE("FastLED.add(cfg): runtime-selection mode — enrolling every "
                 "available driver via fl::enableAllDrivers(). For minimum "
                 "binary size, prefer FastLED.addLeds<CHIPSET, PIN, ORDER, "
                 "fl::Bus::X>(leds, n) which links only the named driver. "
                 "Suppress this warning with -DFASTLED_SUPPRESS_RUNTIME_DRIVER_WARNING.");
    #endif
    fl::enableAllDrivers();
 
    fl::ChannelManager& manager = fl::channelManager();
    FL_ASSERT(manager.getDriverCount() > 0,
              "No channel drivers available - channel API requires at least one registered driver");
    auto channel = fl::Channel::create(config);
    add(channel);
    return channel;
}

References add(), fl::channelManager(), fl::enableAllDrivers(), FL_ASSERT, FL_NO_EXCEPT, FL_WARN_ONCE, and fl::ChannelManager::getDriverCount().

Here is the call graph for this function: