Skip to content

README.md

Latest commit

 

History

History
57 lines (45 loc) · 4.01 KB

README.md

File metadata and controls

57 lines (45 loc) · 4.01 KB

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.