Skip to content

Latest commit

 

History

History
337 lines (256 loc) · 15.8 KB

readme.md

File metadata and controls

337 lines (256 loc) · 15.8 KB

FastLED Platforms Directory

Table of Contents

The src/platforms/ directory contains platform backends and integrations that FastLED targets. Each subfolder provides pin helpers, timing implementations, and controllers tailored to specific microcontrollers or host environments.

What lives here

  • adafruit – Adapter that lets you use Adafruit_NeoPixel via the FastLED API
  • apollo3 – Ambiq Apollo3 (SparkFun Artemis family)
  • arm – ARM families (Teensy, SAMD21/SAMD51, RP2040, STM32/GIGA, nRF5x, Renesas UNO R4)
  • avr – AVR (Arduino UNO, Nano Every, ATtiny/ATmega variants)
  • esp – ESP8266 and ESP32 families
  • neopixelbus – Adapter to drive NeoPixelBus through the FastLED API
  • posix – POSIX networking helpers for host builds
  • shared – Platform‑agnostic components (ActiveStripData, JSON UI)
  • stub – Native, no‑hardware target used by unit tests/host builds
  • wasm – WebAssembly/browser target and JS bridges
  • win – Windows‑specific networking helpers

Popular boards → where to look

If you are targeting a desktop/browser host for demos or tests:

  • Native host tests → stub (with shared for data/UI)
  • Browser/WASM builds → wasm

Platform header organization pattern

FastLED follows a coarse-to-fine delegation pattern for platform detection headers located directly in src/platforms/. This keeps platform routing clean and maintainable.

Rule: Headers at platforms/header.h perform coarse platform detection and delegate to platform-specific subdirectories for fine-grained detection.

Pattern structure

// platforms/header.h - Coarse detection
#if defined(FASTLED_TESTING)
    #include "platforms/stub/platform_stub.h"
#elif defined(ESP32)
    // Delegate to ESP-specific header for fine-grained variant detection
    #include "platforms/esp/platform_esp.h"
#elif defined(__AVR__)
    #include "platforms/avr/platform_avr.h"
#else
    // Fallback
#endif
// platforms/esp/platform_esp.h - Fine-grained detection
#if defined(ESP32) || defined(CONFIG_IDF_TARGET_ESP32)
    // ESP32 classic
#elif defined(ESP32S2) || defined(CONFIG_IDF_TARGET_ESP32S2)
    // ESP32-S2
#elif defined(ESP32S3) || defined(CONFIG_IDF_TARGET_ESP32S3)
    // ESP32-S3
#elif defined(ESP32C3) || defined(CONFIG_IDF_TARGET_ESP32C3)
    // ESP32-C3
#elif defined(ESP32P4) || defined(CONFIG_IDF_TARGET_ESP32P4)
    // ESP32-P4
// ... etc
#endif

Why this pattern?

  1. Coarse headers stay simple: Only check for broad platform families (ESP32, __AVR__, FASTLED_ARM)
  2. Fine-grained logic isolated: Variant-specific detection (ESP32S3, CONFIG_IDF_TARGET_ESP32C6) lives in platform subdirectories
  3. Easy to maintain: Adding new variants only requires changes in platform-specific headers
  4. Follows existing patterns: See platforms/int.h, platforms/audio.h for reference implementations

Real-world example: Quad-SPI detection

Modern approach uses runtime detection with weak symbols instead of compile-time macros:

// platforms/quad_spi_platform.h - Simple compile-time API check
#if defined(FASTLED_TESTING) || defined(ESP32)
    #define FASTLED_HAS_QUAD_SPI_API 1
#else
    #define FASTLED_HAS_QUAD_SPI_API 0
#endif

Platform-specific implementation in platforms/esp/32/spi_quad_esp32.cpp:

// Weak default in platforms/shared/spi_quad.cpp
FL_LINK_WEAK
fl::vector<SPIQuad*> SPIQuad::createInstances() {
    return fl::vector<SPIQuad*>();  // No Quad-SPI
}

// Strong override in platforms/esp/32/spi_quad_esp32.cpp
fl::vector<SPIQuad*> SPIQuad::createInstances() {
    fl::vector<SPIQuad*> controllers;

#if defined(ESP32) || defined(ESP32S2) || defined(ESP32S3)
    static SPIQuadESP32 controller2(2, "HSPI");
    static SPIQuadESP32 controller3(3, "VSPI");
    controllers.push_back(&controller2);
    controllers.push_back(&controller3);
#elif defined(ESP32C3)
    static SPIQuadESP32 controller2(2, "SPI2");  // Dual-SPI only
    controllers.push_back(&controller2);
#elif defined(ESP32P4)
    // Octal-SPI support - future enhancement
    static SPIQuadESP32 controller2(2, "SPI2");
    static SPIQuadESP32 controller3(3, "SPI3");
    controllers.push_back(&controller2);
    controllers.push_back(&controller3);
#endif

    return controllers;
}

Runtime usage:

// Check available controllers at runtime
const auto& controllers = SPIQuad::getAll();
if (controllers.empty()) {
    // Platform doesn't support Quad-SPI
} else {
    // Use controllers[0], controllers[1], etc.
}

This pattern uses weak linkage to provide default behavior while allowing platform-specific implementations to override at link time. It moves platform detection from compile-time to runtime, making the codebase more maintainable and testable.

Controller types in FastLED

FastLED provides two primary controller categories. Choose based on your LED chipset and platform capabilities.

1) Clockless (one‑wire NRZ)

  • For WS2811/WS2812/WS2812B/SK6812 and similar “NeoPixel”‑class LEDs
  • Encodes bits as precisely timed high/low pulses (T0H/T1H/T0L/T1L)
  • Implemented with tight CPU timing loops, SysTick, or hardware assist (e.g., ESP32 RMT or I2S‑parallel)
  • Available as single‑lane and, on some platforms, multi‑lane “block clockless” drivers
  • Sensitive to long interrupts; keep ISRs short during show()

Special cases:

  • ESP32 offers multiple backends for clockless output (see esp/32):
    • RMT (recommended, per‑channel timing)
    • I2S‑parallel (many strips with identical timing)
    • Clockless over SPI (WS2812‑class only)

2) SPI (clocked)

  • For chipsets with data+clock lines (APA102/DotStar, SK9822, LPD8806, WS2801)
  • Uses hardware SPI peripherals to shift pixels with explicit clocking
  • Generally tolerant of interrupts and scales to higher data rates more easily
  • Requires an SPI‑capable LED chipset (not for WS2812‑class, except the ESP32 “clockless over SPI” path above)

Picking the right path

  • WS2812/SK6812 → Clockless controllers (ESP32: RMT or I2S‑parallel for many identical strips)
  • APA102/SK9822/DotStar → SPI controllers for stability and speed
  • Prefer neopixelbus or adafruit adapters if you rely on those ecosystems but want to keep FastLED’s API RP2040 (PIO clockless) needs no special defines; use standard WS2812 addLeds call.

Backend selection cheat sheet

  • ESP32 clockless: RMT (flexible), I2S‑parallel (many identical strips), or SPI‑WS2812 path (WS2812‑only)
    • See ESP32 section for detailed I2S support (ESP32Dev, ESP32‑S3) and RMT v4 vs v5 selection, including define examples and guidance on avoiding mixed RMT4/RMT5 usage.
  • Teensy 3.x/4.x: clockless (single or block multi‑lane), plus OctoWS2811/SmartMatrix integrations (see arm/k20, arm/mxrt1062)
  • AVR: clockless WS2812 and SPI chipsets; small devices benefit from fewer interrupts during show()

Troubleshooting and tips

  • First‑pixel flicker or color glitches often indicate interrupt interference. Reduce background ISRs (Wi‑Fi/BLE/logging) during FastLED.show() or select a hardware‑assisted backend.
  • Power and level shifting matter: WS281x typically need 5V data at sufficient current; ensure a common ground between controller and LEDs.
  • On ARM families, PROGMEM is typically disabled (FASTLED_USE_PROGMEM=0); on AVR it is enabled.
  • For very large installations, consider parallel outputs (OctoWS2811 on Teensy, I2S‑parallel on ESP32) and DMA‑friendly patterns.

How to implement a clockless controller

Clockless controllers generate the one‑wire NRZ waveforms used by WS281x‑class LEDs by toggling a GPIO with precise timings. FastLED’s clockless base controllers accept three timing parameters per bit: T1, T2, T3.

T1/T2/T3 vs T0H/T0L/T1H/T1L

The timing model is:

  • At T=0: line goes high to start a bit
  • At T=T1: drop low to transmit a 0‑bit (T0H just ended)
  • At T=T1+T2: drop low to transmit a 1‑bit (T1H just ended)
  • At T=T1+T2+T3: bit cycle ends; next bit can start

Mapping to datasheet values:

  • T0H = T1
  • T1H = T2
  • T0L = duration − T0H
  • T1L = duration − T1H

Where duration is the max of the two bit periods: max(T0H + T0L, T1H + T1L).

Embedded helper script (from src/chipsets.h) to derive T1/T2/T3 from datasheet T0H/T0L/T1H/T1L:

print("Enter the values of T0H, T0L, T1H, T1L, in nanoseconds: ")
T0H = int(input("  T0H: "))
T0L = int(input("  T0L: "))
T1H = int(input("  T1H: "))
T1L = int(input("  T1L: "))

duration = max(T0H + T0L, T1H + T1L)

print("The max duration of the signal is: ", duration)

T1 = T0H
T2 = T1H
T3 = duration - T0H - T0L

print("T1: ", T1)
print("T2: ", T2)
print("T3: ", T3)

Notes:

  • Some platforms express timings in CPU cycles rather than nanoseconds; FastLED provides converters/macros to derive cycle counts.
  • See the platform‑specific ClocklessController implementation for the required units and conversion helpers.

Multilane output

“Multilane” or “block clockless” controllers send several strips in parallel by transposing pixel data into per‑bit planes and toggling multiple pins simultaneously.

  • Benefits: High aggregate throughput; useful for matrices and large installations.
  • Constraints: All lanes must share the same timing and frame cadence; ISR windows apply across all lanes during output.

Supported in this codebase:

Typically single‑lane only in this codebase:

  • AVR family
  • RP2040 (PIO driver here is single‑lane)
  • nRF51/nRF52
  • STM32/GIGA (clockless single‑lane in this tree)

For Teensy, also consider OctoWS2811 for DMA‑driven parallel output.

How to implement a SPI controller

SPI‑driven LEDs use a clocked data line plus a clock line. Implementation is generally simpler and more ISR‑tolerant than clockless.

Hardware SPI vs software SPI

  • Hardware SPI: Uses the MCU’s SPI peripheral; best performance and CPU efficiency; works with DMA on some platforms.
  • Software SPI (bit‑bang): Uses GPIO toggling when a hardware SPI peripheral or pins aren’t available; slower and more CPU‑intensive but universally portable.

FastLED’s SPIOutput abstracts both; platform headers select efficient implementations where available.

Common SPI LED chipsets

  • APA102 / “DotStar” (and HD variants): Data + clock + per‑pixel global brightness; tolerant of interrupts. See APA102 controller definitions.
  • SK9822: Protocol compatible with APA102 with minor differences; supported.
  • WS2801, LPD8806, LPD6803, P9813, SM16716: Older or niche SPI‑style protocols; supported via specific controllers.

When choosing SPI speed, consult chipset and wiring limits (signal integrity on long runs). Long APA102 runs may require reduced clock rates.

PROGMEM

Some platforms store constant tables and palettes in flash (program) memory rather than RAM. FastLED abstracts PROGMEM usage via macros; support varies by platform.

  • AVR: Full PROGMEM support; default FASTLED_USE_PROGMEM=1. Flash is separate from RAM; use pgm_read_ accessors for reads.
  • ESP8266: PROGMEM supported; see progmem_esp8266.h. Provides FL_PROGMEM, FL_PGM_READ_*, and FL_ALIGN_PROGMEM (4‑byte alignment) helpers.
  • ESP32, ARM (Teensy, SAMD21/51, RP2040, STM32/GIGA, nRF): Typically treat constants as directly addressable; FastLED defaults to FASTLED_USE_PROGMEM=0 on these families to avoid unnecessary indirection.

Aligned reads for PROGMEM:

  • On platforms that require alignment (e.g., ESP8266), use 4‑byte alignment for multibyte table entries to avoid unaligned access traps. FastLED exposes FL_ALIGN_PROGMEM for this purpose.

Platforms without PROGMEM (or where it’s a no‑op in this codebase):

  • Most ARM families (SAMD, STM32, nRF, RP2040) and ESP32 use memory‑mapped flash; PROGMEM macros are disabled here via FASTLED_USE_PROGMEM=0.

Check each platform’s led_sysdefs_* header for the recommended PROGMEM and interrupt policy.

Common feature defines

These are commonly available across multiple platforms. Pass them as build defines (e.g., build_flags in PlatformIO), and define them prior to including FastLED.h.

  • FASTLED_USE_PROGMEM — Control PROGMEM usage (enabled on AVR, typically disabled elsewhere)
  • FASTLED_ALLOW_INTERRUPTS — Allow interrupts during show() (platform defaults vary)
  • FASTLED_INTERRUPT_RETRY_COUNT — Global retry count when timing is disrupted
  • FASTLED_DEBUG_COUNT_FRAME_RETRIES — Enable counters/logging of frame retries due to timing issues

For platform‑specific feature defines (e.g., ESP32 RMT/I2S knobs, RP2040 PIO selection, Teensy/STM32 options), see the README in that platform’s directory: