chipsets.h

Go to the documentation of this file.

#pragma once
 
#ifndef __INC_CHIPSETS_H
#define __INC_CHIPSETS_H
 
// allow-include-after-namespace
 
#include "pixeltypes.h"
#include "fl/gfx/five_bit_hd_gamma.h"
#include "fl/stl/compiler_control.h"
#include "fl/stl/static_assert.h"
#include "fl/stl/bit_cast.h"
#include "fl/stl/unique_ptr.h"
#include "pixel_iterator.h"
#include "crgb.h"
#include "eorder.h"
#include "fl/math/math.h"
#include "platforms/is_platform.h"
 
// Include centralized LED chipset timing definitions
// These provide unified nanosecond-based T1, T2, T3 timing for all supported chipsets
#include "fl/chipsets/led_timing.h"
 
// Include legacy AVR-specific timing definitions (FMUL-based)
// Used for backward compatibility with existing AVR clockless drivers
#ifdef FL_IS_AVR
#include "platforms/avr/led_timing_legacy_avr.h"  // ok platform headers
#endif
 
// Platform-specific clockless controller dispatch
// Includes the appropriate clockless controller implementation for the target platform
#include "platforms/clockless.h"
 
// Include UCS7604 controller (works on all platforms with clockless controller support)
#include "fl/chipsets/ucs7604.h"
#include "fl/chipsets/encoders/ws2816.h"
 
// Include platform-independent SPI utilities
#include "platforms/shared/spi_pixel_writer.h"  // ok platform headers
 
// Platform-specific SPI output template dispatch
// Includes the appropriate SPIOutput template implementation for the target platform
// This must be included before any SPI chipset controllers (e.g., APA102, P9813)
#include "platforms/spi_output_template.h"
 
// Include SPI chipset controllers
#include "fl/chipsets/apa102.h"
#include "fl/chipsets/hd108.h"
#include "fl/chipsets/lpd880x.h"
#include "fl/chipsets/ws2801.h"
#include "fl/chipsets/p9813.h"
#include "fl/chipsets/sm16716.h"
 
// Platform-specific clockless timing configuration
//
// IMPORTANT: All platforms use nanosecond-based timing at the API level.
// Chipset timing values (T1, T2, T3) are specified in nanoseconds (e.g., T1=250ns, T2=625ns, T3=375ns)
//
// Platforms that need cycle-based timing internally (e.g., AVR, ARM, ESP8266) perform
// nanosecond-to-cycle conversion within their clockless driver implementation using F_CPU or equivalent.
//
// Platform-specific clockless drivers are defined in:
// - ESP32/ESP8266: platforms/esp/clockless.h
// - All ARM platforms: led_sysdefs_arm_*.h + platform-specific clockless headers
// - AVR platforms: led_sysdefs_avr.h + platforms/avr/clockless_*.h
// - Other platforms: respective led_sysdefs_*.h files
 
// ============================================================================
// PLATFORM-SPECIFIC SPECIALIZED CONTROLLERS (Bottom Includes)
// ============================================================================
// The includes below MUST be at this point in the file because:
//
// 1. C++ templates require full definition in headers (no .cpp separation)
// 2. Base templates and type definitions (above) must be defined BEFORE
//    platform-specific specializations (below) can see and use them
// 3. Platform specializations need to instantiate/specialize the base templates
//
// This is intentional C++ template architecture, not a code smell or circular
// dependency. Template-heavy libraries like FastLED naturally have includes at
// the bottom to support platform-specific specializations.
//
// Example: WS2812 is heavily optimized per-platform because it's the most
// popular chipset. Each platform provides specialized implementations that
// fully replace the default template instantiation.
// ============================================================================
 
#include "platforms/chipsets_specialized_ws2812.h"
 
#if defined(ARDUINO) && (defined(SoftwareSerial_h) || defined(__SoftwareSerial_h))
// IWYU pragma: begin_keep
#include <SoftwareSerial.h>
// IWYU pragma: end_keep
#endif

 
 

 
#if defined(ARDUINO) && (defined(SoftwareSerial_h) || defined(__SoftwareSerial_h))
 
#define HAS_PIXIE
 

template<fl::u8 DATA_PIN, EOrder RGB_ORDER = RGB>
class PixieController : public CPixelLEDController<RGB_ORDER> {
    SoftwareSerial Serial;
    CMinWait<2000> mWait;
 
public:
    PixieController() : Serial(-1, DATA_PIN) {}
 
protected:
    virtual void init() {
        Serial.begin(115200);
        mWait.mark();
    }

    virtual void showPixels(PixelController<RGB_ORDER> & pixels) {
        mWait.wait();
        while(pixels.has(1)) {
            fl::u8 r = pixels.loadAndScale0();
            Serial.write(r);
            fl::u8 g = pixels.loadAndScale1();
            Serial.write(g);
            fl::u8 b = pixels.loadAndScale2();
            Serial.write(b);
            pixels.advanceData();
            pixels.stepDithering();
        }
        mWait.mark();
    }
 
};
 
// template<SoftwareSerial & STREAM, EOrder RGB_ORDER = RGB>
// class PixieController : public PixieBaseController<STREAM, RGB_ORDER> {
// public:
//  virtual void init() {
//      STREAM.begin(115200);
//  }
// };
 
#endif
#endif

 
 
template <
    typename CONTROLLER,
    EOrder RGB_ORDER = GRB>  // Default on WS2812>
class RGBWEmulatedController
    : public CPixelLEDController<RGB_ORDER, CONTROLLER::LANES_VALUE,
                                 CONTROLLER::MASK_VALUE> {
  public:
    // ControllerT is a helper class.  It subclasses the device controller class
    // and has three methods to call the three protected methods we use.
    // This is janky, but redeclaring public methods protected in a derived class
    // is janky, too.
 
    // N.B., byte order must be RGB.
    typedef CONTROLLER ControllerBaseT;
    class ControllerT : public CONTROLLER {
        friend class RGBWEmulatedController<CONTROLLER, RGB_ORDER>;
        void *callBeginShowLeds(int size) { return ControllerBaseT::beginShowLeds(size); }
        void callShow(CRGB *data, int nLeds, fl::u8 brightness) {
            ControllerBaseT::show(data, nLeds, brightness);
        }
        void callEndShowLeds(void *data) { ControllerBaseT::endShowLeds(data); }
    };
 
 
    static const int LANES = CONTROLLER::LANES_VALUE;
    static const fl::u32 MASK = CONTROLLER::MASK_VALUE;
 
    // The delegated controller must do no reordering.
    FL_STATIC_ASSERT(RGB == CONTROLLER::RGB_ORDER_VALUE, "The delegated controller MUST NOT do reordering");

    RGBWEmulatedController(const Rgbw& rgbw = RgbwDefault()) {
        this->setRgbw(rgbw);
    };

    ~RGBWEmulatedController() = default;
 
    virtual void *beginShowLeds(int size) override {
        return mController.callBeginShowLeds(Rgbw::size_as_rgb(size));
    }
 
    virtual void endShowLeds(void *data) override {
        return mController.callEndShowLeds(data);
    }

    virtual void showPixels(PixelController<RGB_ORDER, LANES, MASK> &pixels) override {
        // Ensure buffer is large enough
        ensureBuffer(pixels.size());
        Rgbw rgbw = this->getRgbw();
        fl::u8 *data = fl::bit_cast_ptr<fl::u8>(mRGBWPixels.get());
        while (pixels.has(1)) {
            pixels.stepDithering();
            pixels.loadAndScaleRGBW(rgbw, data, data + 1, data + 2, data + 3);
            data += 4;
            pixels.advanceData();
        }
 
        // Force the device controller to a state where it passes data through
        // unmodified: color correction, color temperature, dither, and brightness
        // (passed as an argument to show()).  Temporarily enable the controller,
        // show the LEDs, and disable it again.
        //
        // The device controller is in the global controller list, so if we 
        // don't keep it disabled, it will refresh again with unknown brightness,
        // temperature, etc.
 
        mController.setCorrection(CRGB(255, 255, 255));
        mController.setTemperature(CRGB(255, 255, 255));
        mController.setDither(DISABLE_DITHER);
 
        mController.setEnabled(true);
        mController.callShow(mRGBWPixels.get(), Rgbw::size_as_rgb(pixels.size()), 255);
        mController.setEnabled(false);
    }
 
  private:
    void init() override {
        mController.init();
        mController.setEnabled(false);
    }

    void ensureBuffer(fl::i32 num_leds) {
        if (num_leds != mNumRGBLeds) {
            mNumRGBLeds = num_leds;
            // The delegate controller expects the raw pixel byte data in multiples of 3.
            // In the case of src data not a multiple of 3, then we need to
            // add pad bytes so that the delegate controller doesn't walk off the end
            // of the array and invoke a buffer overflow panic.
            fl::u32 new_size = Rgbw::size_as_rgb(num_leds);
            mRGBWPixels.reset(new CRGB[new_size]);  // ok bare allocation (array new)
            // showPixels may never clear the last two pixels.
            for (fl::u32 i = 0; i < new_size; i++) {
                mRGBWPixels[i] = CRGB(0, 0, 0);
            }
 
            mController.setLeds(mRGBWPixels.get(), new_size);
        }
    }
 
    fl::unique_ptr<CRGB[]> mRGBWPixels; 
    fl::i32 mNumRGBLeds = 0;            
    fl::i32 mNumRGBWLeds = 0;           
    ControllerT mController;             
};


 
 

//
// Clockless template instantiations - see clockless.h for how the timing values are used
//
 
#ifdef FL_CLOCKLESS_CONTROLLER_DEFINED
 
// Allow clock that clockless controller is based on to have different
// frequency than the CPU.
#if !defined(CLOCKLESS_FREQUENCY)
    #define CLOCKLESS_FREQUENCY F_CPU
#endif
 
// We want to force all avr's to use the Trinket controller when running at 8Mhz, because even the 328's at 8Mhz
// need the more tightly defined timeframes.
// Suppress -Wsubobject-linkage warning for controller template instantiations.
// In C++11/14, constexpr variables have internal linkage, which causes the compiler
// to warn when they are used in base classes of externally-linked templates. The macro
// FL_INLINE_CONSTEXPR adds explicit 'inline' in C++17+ to resolve this, but for C++11
// compatibility we suppress the warning here.
FL_DISABLE_WARNING_PUSH
FL_DISABLE_WARNING_SUBOBJECT_LINKAGE
 
 
 
 
// Legacy macro for nanoseconds to clock cycles conversion
// This is no longer used by the core API but kept for backward compatibility
#define FL_NANOSECONDS_TO_CLOCK_CYCLES(_NS) (((_NS * ((CLOCKLESS_FREQUENCY / 1000000L)) + 999)) / 1000)
 
 
//
// Given datasheet timing values T0H, T0L, T1H, T1L (in nanoseconds):
//
//  duration = max(T0H + T0L, T1H + T1L)  # Maximum cycle time
//  T1 = T0H                               # High time for '0' bit
//  T2 = T1H - T0H                         # Additional time for '1' bit
//  T3 = duration - T1H                    # Tail time after '1' bit
//
// Example (WS2812B with T0H=400, T0L=850, T1H=850, T1L=400):
//  duration = 1250, T1 = 400, T2 = 450, T3 = 400
//
// For interactive conversion or validation, use: uv run ci/tools/led_timing_conversions.py
// For automated testing of all chipsets: uv run ci/test_led_timing_conversion.py
// For C++ check out
//   * converter: src/fl/clockless/timing_conversion.h
//   * tests: tests/fl/clockless/timing_conversion.cpp
 

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class GE8822Controller800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_GE8822_800KHZ, RGB_ORDER, 4, false> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class GW6205Controller400Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_GW6205_400KHZ, RGB_ORDER, 4, false> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class GW6205Controller800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_GW6205_800KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class UCS1903Controller400Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_UCS1903_400KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class UCS1903BController800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_UCS1903B_800KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class UCS1904Controller800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_UCS1904_800KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class UCS2903Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_UCS2903, RGB_ORDER> {};
 
// Template wrapper to adapt ClocklessControllerImpl (6-param template alias)
// to the 3-param template template parameter expected by UCS7604ControllerT
namespace {
    template<int DATA_PIN, typename TIMING, EOrder RGB_ORDER>
    class ClocklessControllerWrapper : public fl::ClocklessControllerImpl<DATA_PIN, TIMING, RGB_ORDER> {};
}

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
using UCS7604Controller8bit = fl::UCS7604Controller8bitT<DATA_PIN, RGB_ORDER, ClocklessControllerWrapper>;

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
using UCS7604Controller16bit = fl::UCS7604Controller16bitT<DATA_PIN, RGB_ORDER, ClocklessControllerWrapper>;

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
using UCS7604Controller16bit1600 = fl::UCS7604Controller16bit1600T<DATA_PIN, RGB_ORDER, ClocklessControllerWrapper>;

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class TM1809Controller800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_TM1809_800KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = GRB>
class WS2811Controller800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_WS2811_800KHZ_LEGACY, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = GRB>
class WS2813Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_WS2813, RGB_ORDER> {};

#if !FASTLED_WS2812_HAS_SPECIAL_DRIVER
template <int DATA_PIN, EOrder RGB_ORDER = GRB>
class WS2812Controller800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_WS2812_800KHZ, RGB_ORDER> {};
#endif

template <int DATA_PIN, EOrder RGB_ORDER = GRB>
class WS2812BMiniV3Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_WS2812B_MINI_V3, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = GRB>
class WS2812BV5Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_WS2812B_V5, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = GRB>
class WS2811Controller400Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_WS2811_400KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = GRB>
class WS2815Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_WS2815, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class DP1903Controller800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_DP1903_800KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class DP1903Controller400Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_DP1903_400KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class TM1803Controller400Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_TM1803_400KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class TM1829Controller800Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_TM1829_800KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class TM1829Controller1600Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_TM1829_1600KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class LPD1886Controller1250Khz : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_LPD1886_1250KHZ, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class LPD1886Controller1250Khz_8bit : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_LPD1886_1250KHZ, RGB_ORDER> {};
 

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class SK6822Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_SK6822, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class SK6812Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_SK6812, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class SM16703Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_SM16703, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class PL9823Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_PL9823, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class UCS1912Controller : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_UCS1912, RGB_ORDER> {};

template <int DATA_PIN, EOrder RGB_ORDER = RGB>
class SM16824EController : public fl::ClocklessControllerImpl<DATA_PIN, fl::TIMING_SM16824E, RGB_ORDER> {};
 
FL_DISABLE_WARNING_POP
 
 
// WS2816 - is an emulated controller that emits 48 bit pixels by forwarding
// them to a platform specific WS2812 controller.  The WS2812 controller
// has to output twice as many 24 bit pixels.
template <int DATA_PIN, EOrder RGB_ORDER = GRB>
class WS2816Controller
    : public CPixelLEDController<RGB_ORDER, 
                                 WS2812Controller800Khz<DATA_PIN, RGB>::LANES_VALUE,
                                 WS2812Controller800Khz<DATA_PIN, RGB>::MASK_VALUE> {
 
public:
 
    // ControllerT is a helper class.  It subclasses the device controller class
    // and has three methods to call the three protected methods we use.
    // This is janky, but redeclaring public methods protected in a derived class
    // is janky, too.
 
    // N.B., byte order must be RGB.
    typedef WS2812Controller800Khz<DATA_PIN, RGB> ControllerBaseT;
    class ControllerT : public ControllerBaseT {
        friend class WS2816Controller<DATA_PIN, RGB_ORDER>;
        void *callBeginShowLeds(int size) { return ControllerBaseT::beginShowLeds(size); }
        void callShow(CRGB *data, int nLeds, fl::u8 brightness) {
            ControllerBaseT::show(data, nLeds, brightness);
        }
        void callEndShowLeds(void *data) { ControllerBaseT::endShowLeds(data); }
    };
 
    static const int LANES = ControllerT::LANES_VALUE;
    static const fl::u32 MASK = ControllerT::MASK_VALUE;
 
    WS2816Controller() {}
    ~WS2816Controller() {
        mController.setLeds(nullptr, 0);
    }
 
    virtual void *beginShowLeds(int size) override {
        mController.setEnabled(true);
        void *result = mController.callBeginShowLeds(2 * size);
        mController.setEnabled(false);
        return result;
    }
 
    virtual void endShowLeds(void *data) override {
        mController.setEnabled(true);
        mController.callEndShowLeds(data);
        mController.setEnabled(false);
    }
 
    virtual void showPixels(PixelController<RGB_ORDER, LANES, MASK> &pixels) override {
        // Ensure buffer is large enough
        ensureBuffer(pixels.size());
 
        // Create PixelIterator from PixelController (WS2816 is RGB-only, no W channel)
        fl::PixelIterator pixel_iter = pixels.as_iterator(fl::Rgbw());
 
        // Create 16-bit RGB iterator range (handles RGB reordering, scaling, brightness)
        auto rgb16_range = fl::makeScaledPixelRangeRGB16(&pixel_iter);
 
        // Encode 16-bit RGB pixels to dual 8-bit CRGB format
        fl::encodeWS2816(rgb16_range.first, rgb16_range.second, mData.get());
 
        // Ensure device controller won't modify color values
        mController.setCorrection(CRGB(255, 255, 255));
        mController.setTemperature(CRGB(255, 255, 255));
        mController.setDither(DISABLE_DITHER);
 
        // Output the data stream
        mController.setEnabled(true);
        mController.callShow(mData.get(), 2 * pixels.size(), 255);
        mController.setEnabled(false);
    }
 
private:
    void init() override {
        mController.init();
        mController.setEnabled(false);
    }
 
    void ensureBuffer(int size_8bit) {
        int size_16bit = 2 * size_8bit;
        if (mController.size() != size_16bit) {
            
            auto new_leds = fl::make_unique<CRGB[]>(size_16bit);
            mData = fl::move(new_leds);
            mController.setLeds(mData.get(), size_16bit);
        }
    }
 
    fl::unique_ptr<CRGB[]> mData;
    ControllerT mController;
};
 
 
#endif

 
#if defined(FL_IS_SILABS)
 
#include "platforms/arm/mgm240/clockless_ezws2812_gpio.h"  // ok platform headers

template<fl::u8 DATA_PIN, EOrder RGB_ORDER = GRB>
using EZWS2812_GPIO = fl::ClocklessController_ezWS2812_GPIO_Auto<DATA_PIN, RGB_ORDER>;
 
#ifdef FASTLED_USES_EZWS2812_SPI
 
#include "platforms/arm/mgm240/clockless_ezws2812_spi.h"  // ok platform headers

template<EOrder RGB_ORDER = GRB>
using EZWS2812_SPI = fl::ClocklessController_ezWS2812_SPI<RGB_ORDER>;
 
#endif // FASTLED_USES_EZWS2812_SPI
 
#endif // ARDUINO_ARCH_SILABS