slim_spi_bridge_controller.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/noexcept.h"
#include "fl/stl/static_assert.h"
 
#include "cpixel_ledcontroller.h"
#include "fl/channels/data.h"
#include "fl/channels/driver.h"
#include "fl/channels/manager.h"
#include "fl/channels/bus.h"
#include "fl/channels/bus_traits.h"  // IWYU pragma: keep (DriverTraits<Bus::X> satisfies the DriverTraits contract)
#include "fl/channels/channel_typed.h"  // IWYU pragma: keep (detail::resolve_bus, BusSupports)
#include "fl/channels/config.h"
#include "fl/chipsets/encoders/pixel_iterator.h"
#include "fl/log/log.h"
 
namespace fl {
#if defined(FL_IS_ESP32)
namespace platforms {
void registerNativeSpiDriver() FL_NO_EXCEPT;
}
#endif

template <fl::SpiChipset CHIPSET, EOrder RGB_ORDER, fl::Bus B, fl::u8 B_WHICH>
class SlimSpiBridgeController : public CPixelLEDController<RGB_ORDER> {
public:
    static constexpr Bus kBus = detail::resolve_bus<B, SpiChipsetConfig>::value;
 
    // Compile-time contract, mirrors TypedChannel<B, SpiChipsetConfig, Which>.
    FL_STATIC_ASSERT(
        BusSupports<kBus, SpiChipsetConfig, B_WHICH>::value,
        "SlimSpiBridgeController: Bus does not support SpiChipsetConfig");
 
    explicit SlimSpiBridgeController(const SpiChipsetConfig& cfg) FL_NO_EXCEPT
#if defined(FL_IS_ESP32)
        : mExplicitSpiHost(cfg.spiBus != Esp32SpiBus::AUTO)
#endif
    {
        mData = ChannelData::create(ChipsetVariant(cfg));
#if defined(FL_IS_ESP32)
        // The explicit-host addLeds() overload registers the native SPI
        // driver itself; referencing it here would link the ESP-IDF SPI
        // master stack (~20 KB) into every AUTO-host sketch.
        if (mExplicitSpiHost) {
            return;
        }
#endif
        // Idempotent by contract -- safe to call from every instantiation's
        // constructor (mirrors TypedChannel::create()'s registerWithManager() call).
        BusTraits<kBus, B_WHICH>::registerWithManager();
    }
 
    void init() FL_NO_EXCEPT override {}

    const ChannelDataPtr& channelData() const FL_NO_EXCEPT { return mData; }
 
protected:
    void showPixels(PixelController<RGB_ORDER>& pixels) FL_NO_EXCEPT override {
        fl::shared_ptr<IChannelDriver> driver = resolveDriver();
        if (!driver) {
            return;
        }
 
        // (A1) Respect runtime driver enable/disable: ChannelManager is the
        // single source of truth. A disabled driver means "drop this frame",
        // not "enqueue and hope" -- silently enqueuing to a disabled driver
        // is the #2517 silent-drop failure mode.
        if (!ChannelManager::registry().isDriverEnabled(*driver)) {
            FL_WARN_ONCE("SlimSpiBridgeController: driver '" << driver->getName() << "' is disabled - dropping frame");
            return;
        }
 
        // (A8) If the previous frame's buffer is still in flight, block
        // (bounded) until the driver reports it can accept more work rather
        // than racing the driver's in-progress transfer.
        if (mData->isInUse()) {
            if (!driver->waitForReady()) {
                FL_WARN_ONCE("SlimSpiBridgeController: driver '" << driver->getName() << "' did not become ready in time - dropping frame");
                return;
            }
        }
 
        // (A5) Publish the pixel byte layout so the driver (and any
        // downstream padding/diagnostic code) knows the encoded stride.
        if (this->getRgbww().active()) {
            mData->setPixelFormat(ChannelPixelFormat::RGBWW);
        } else if (this->getRgbw().active()) {
            mData->setPixelFormat(ChannelPixelFormat::RGBW);
        } else {
            mData->setPixelFormat(ChannelPixelFormat::RGB);
        }
 
        // Dither reseed mirrors Channel::encodeFrame(): only reseed when a
        // non-zero dither mode is set.
        if (pixels.ditherActive()) {
            pixels.reseed_binary_dithering(mDitherPhase);
        }
 
        // (A3) Re-encode into the same buffer every frame -- clear() keeps
        // capacity, so steady-state operation is allocation-free.
        mData->getData().clear();
        fl::PixelIterator it(&pixels, this->getRgbw(), this->getRgbww());
        encode(it, mData->getData());
 
        driver->enqueue(mData);
        // Presented, per the driver contract: an accepted enqueue is the
        // frame -- mirrors Channel::submitFrame()'s ++mDitherPhase placement
        // (dither only advances when a frame is actually handed to the
        // driver, not on every showPixels() attempt).
        ++mDitherPhase;
    }
 
private:
    fl::shared_ptr<IChannelDriver> resolveDriver() FL_NO_EXCEPT {
#if defined(FASTLED_DISABLE_DYNAMIC_DRIVER) && FASTLED_DISABLE_DYNAMIC_DRIVER
        return {};
#else
#if defined(FL_IS_ESP32)
        if (mExplicitSpiHost) {
            // A requested SPI host cannot be honored by the LCD_CAM driver.
            // Do not fall through to priority selection if the native adapter
            // is unavailable.
            return ChannelManager::registry().findDriverByName(
                fl::string::from_literal("SPI_UNIFIED"));
        }
#endif
        // Build busKey only when we actually need it (kBus != AUTO).
        fl::string busKey;
        if (kBus != Bus::AUTO) {
            busKey = fl::string::from_literal(busDriverName(kBus, B_WHICH, /*spi=*/true));
        }
 
        fl::shared_ptr<IChannelDriver> driver =
            ChannelManager::registry().selectDriverForChannel(mData, busKey);
 
#if FASTLED_LOG_RUNTIME_ENABLED
        if (!driver && !mBusWarned) {
            FL_ERROR("SlimSpiBridgeController: no compatible driver found for bus '" << busKey << "' - cannot transmit");
            mBusWarned = true;
        }
#endif  // FASTLED_LOG_RUNTIME_ENABLED
        return driver;
#endif  // !FASTLED_DISABLE_DYNAMIC_DRIVER
    }

    static void encode(fl::PixelIterator& it, fl::vector_psram<u8>& out) FL_NO_EXCEPT {
        switch (CHIPSET) {
            case fl::SpiChipset::APA102:
            case fl::SpiChipset::DOTSTAR:
            case fl::SpiChipset::HD107:
                it.writeAPA102(&out, false);
                break;
            case fl::SpiChipset::APA102HD:
            case fl::SpiChipset::DOTSTARHD:
            case fl::SpiChipset::HD107HD:
                it.writeAPA102(&out, true);
                break;
            case fl::SpiChipset::SK9822:
                it.writeSK9822(&out, false);
                break;
            case fl::SpiChipset::SK9822HD:
                it.writeSK9822(&out, true);
                break;
            case fl::SpiChipset::WS2801:
                it.writeWS2801(&out);
                break;
            case fl::SpiChipset::WS2803:
                it.writeWS2803(&out);
                break;
            case fl::SpiChipset::P9813:
                it.writeP9813(&out);
                break;
            case fl::SpiChipset::LPD8806:
                it.writeLPD8806(&out);
                break;
            case fl::SpiChipset::LPD6803:
                it.writeLPD6803(&out);
                break;
            case fl::SpiChipset::SM16716:
                it.writeSM16716(&out);
                break;
            case fl::SpiChipset::HD108:
                it.writeHD108(&out, false);
                break;
            case fl::SpiChipset::MY9221:
                // Never routed here -- FastLED.h sends MY9221 to the bit-bang
                // MY9221Controller (see file header comment). Defensive
                // no-op if this controller is ever instantiated directly
                // with CHIPSET == MY9221.
                break;
        }
    }
 
    ChannelDataPtr mData;
#if defined(FL_IS_ESP32)
    bool mExplicitSpiHost;
#endif
    u8 mDitherPhase = 0;
#if FASTLED_LOG_RUNTIME_ENABLED
    bool mBusWarned = false;
#endif
};
 
}  // namespace fl