FastLED Platform: esp

ESP platform support covering ESP8266 and ESP32 (Xtensa and RISC‑V variants), with multiple output backends (RMT, I2S‑parallel, and clockless SPI for WS2812‑class LEDs).

Top‑level files (quick pass)

• compile_test.hpp: Compile‑time assertions for ESP8266/ESP32 flags (PROGMEM usage, interrupts policy, F_CPU, architecture guards, millis availability, driver feature checks).
• esp_assert.h: Lightweight FASTLED_ASSERT macro that prints via fl::sstream without pulling heavy logging.
• esp_version.h: IDF version detection/fallback macros for toolchains lacking esp_idf_version.h.
• int.h: ESP‑friendly integer/pointer typedefs in fl::.
• io_esp.h: Minimal I/O helpers; on ESP32 uses direct fputs to stdout to avoid heavy logging.
• print_esp.h: ESP32 UART helpers using driver/uart.h to uart_write_bytes().
• esp_compile.hpp: Hierarchical include hook for ESP; sources are brought in via build system globs.

Subdirectories

• 32/ (ESP32 family)

  • core/fastled_esp32.h: Aggregator; selects one of the clockless drivers based on IDF features/macros.
  • Clockless drivers:
    • drivers/rmt/clockless_rmt_esp32.h: RMT backend; dispatches to drivers/rmt/rmt_4/ (IDF4) or drivers/rmt/rmt_5/ (IDF5) implementations.
    • drivers/i2s/clockless_i2s_esp32.h: I2S‑parallel backend; can drive up to 24 strips in parallel (same timings).
    • clockless_spi_esp32.h: Clockless over SPI pipeline for WS2812‑class LEDs (uses spi_ws2812/).
  • RMT5 interface: drivers/rmt/rmt_5/idf5_rmt.h and helpers.
  • I2S support: drivers/i2s/ setup and DMA buffer management invoked by the I2S driver.
  • Pin/SPI headers: fastpin_esp32.h, fastspi_esp32.h (included conditionally).

• 8266/ (ESP8266 family)

  • clockless_esp8266.h: Single‑lane clockless controller using cycle counter with interrupt handling and frame retry handling.
  • clockless_block_esp8266.h: Multi‑lane “blockless” controller (transpose + timed output across lanes).
  • fastpin_esp8266.h: Direct GPIO access helpers and pin mappings for ESP8266 variants and NodeMCU/D1 mappings.
  • fastspi_esp8266.h: Hardware SPI helper (where available) for ESP8266.

Backend selection quick guide

Pick one backend explicitly via preprocessor defines, then include fastled_esp32.h:

• RMT (recommended for most projects): define FASTLED_ESP32_HAS_RMT.
  • IDF 4.x uses drivers/rmt/rmt_4/, IDF 5.x uses drivers/rmt/rmt_5/ automatically via ESP_IDF_VERSION.
  • Best choice when strips have differing timings or when you want per‑channel independence.
• I2S parallel (many strips, same timing): define FASTLED_ESP32_I2S.
  • Drives up to 24 strips in parallel with identical WS281x timings. All strips must share the same protocol/timing.
  • Good for LED matrices/walls when memory for DMA buffers is available.
• Clockless over SPI (WS2812‑class only): define FASTLED_ESP32_HAS_CLOCKLESS_SPI.
  • Uses SPI to approximate WS2812 timings; lower CPU overhead than bit‑bang, but limited to WS2812‑compatible LEDs.

IDF version notes:

• esp_version.h provides a robust ESP_IDF_VERSION macro shim so you can write portable conditionals.
• RMT API differs substantially between IDF 4 and 5; the dispatcher inside drivers/rmt/clockless_rmt_esp32.h selects the correct layer.

Typical pitfalls:

• Long ISRs (Wi‑Fi, BLE, heavy logging) can introduce jitter. Prefer RMT or I2S if your application has significant background activity.
• I2S requires uniform timings across lanes. If you mix device types (e.g., WS2812B and SK6812), prefer RMT.
• For high throughput, reduce logging (see esp_log_control.h) and pin RMT tasks to a core with fewer interrupts.

Behavior and constraints

• ESP32 driver selection: FASTLED_ESP32_HAS_RMT vs FASTLED_ESP32_HAS_CLOCKLESS_SPI (or FASTLED_ESP32_I2S) determines backend; fastled_esp32.h chooses based on macros/IDF version.
• ESP8266 path uses cycle‑counter‑based timing; NMIs and interrupt durations can force frame retries or early aborts to maintain signal quality.