ContextQMD
Back to Fastled

ESP32 Platform Architecture

src/platforms/esp/32/ARCHITECTURE.md

3.10.321.2 KB
Original Source

ESP32 Platform Architecture

Overview

The ESP32 platform implementation supports 9+ ESP32 variants (ESP32 classic, S2, S3, C3, C6, H2, P4, etc.) with 6 different LED output driver types, all organized into a clean hierarchical structure.

Directory Structure

src/platforms/esp/32/
├── core/                        # Core platform infrastructure
│   ├── fastled_esp32.h          # Master aggregator (driver dispatcher)
│   ├── led_sysdefs_esp32.h      # System defines
│   ├── fastpin_esp32.h          # Pin mappings (all variants)
│   ├── fastspi_esp32.h          # Hardware SPI abstraction
│   ├── clock_cycles.h           # Timing utilities
│   ├── esp_log_control.h        # Logging control
│   ├── delay.h                  # Xtensa delay
│   ├── delay_riscv.h            # RISC-V delay
│   ├── delaycycles.h            # Xtensa cycle-accurate delay
│   └── delaycycles_riscv.h      # RISC-V cycle-accurate delay
│
├── drivers/                     # LED output drivers (organized by type)
│   ├── rmt/                     # RMT (Remote Control Module)
│   │   ├── clockless_rmt_esp32.h    # RMT dispatcher
│   │   ├── rmt_4/                   # ESP-IDF 4.x implementation (8 files)
│   │   └── rmt_5/                   # ESP-IDF 5.x implementation (13 files)
│   │
│   ├── i2s/                     # I2S parallel output
│   │   ├── clockless_i2s_esp32.h     # I2S driver
│   │   ├── clockless_i2s_esp32s3.*   # S3 variant
│   │   └── i2s_esp32dev.*            # I2S helpers
│   │
│   ├── lcd_cam/                 # LCD_CAM drivers (S3/P4 only)
│   │   ├── clockless_lcd_i80_esp32.*     # I80 interface
│   │   ├── clockless_lcd_rgb_esp32.*     # RGB interface
│   │   ├── lcd_driver_*.h                # Helper files (6 files)
│   │   └── implementation_notes.md       # Implementation docs
│   │
│   ├── parlio/                  # Parallel IO (P4 only)
│   │   ├── clockless_parlio_esp32p4.*    # PARLIO driver
│   │   └── parlio_driver*.h              # Helper files
│   │
│   ├── spi/                     # Hardware SPI (clocked LEDs)
│   │   ├── spi_hw_1_esp32.cpp        # 1-lane SPI
│   │   ├── spi_hw_2_esp32.cpp        # 2-lane SPI
│   │   ├── spi_hw_4_esp32.cpp        # 4-lane SPI
│   │   ├── spi_hw_8_esp32.cpp        # 8-lane SPI (P4 only)
│   │   ├── spi_platform_esp32.cpp    # Platform abstraction
│   │   ├── spi_output_template.h     # SPI output template
│   │   └── spi_device_proxy.h        # SPI device proxy
│   │
│   └── spi_ws2812/              # Clockless SPI (WS2812 over SPI)
│       ├── clockless_spi_esp32.h     # WS2812-over-SPI driver
│       └── strip_spi.*               # SPI strip implementation
│
├── interrupts/                  # Architecture-specific ISRs
│   ├── xtensa_lx6.hpp           # ESP32 classic
│   ├── xtensa_lx7.hpp           # ESP32-S2/S3
│   ├── riscv.hpp                # ESP32-C3/C6/H2/P4
│   ├── riscv.cpp                # RISC-V implementation
│   └── INVESTIGATE.md           # Research notes
│
├── audio/                       # Audio processing subsystem
├── ota/                         # OTA update support
│
└── [Root-level files]           # Platform abstraction
    ├── interrupt.h              # Interrupt control interface
    ├── interrupt.cpp            # Interrupt control implementation
    ├── isr_esp32.cpp            # ISR API implementation (IDF 5.0+)
    └── clockless_block_esp32.h  # Experimental (not in production)

Driver Dispatcher Pattern

The ESP32 platform uses a dispatcher pattern to select the appropriate LED output driver at compile time:

User Code (Arduino/Platform IO sketch)
    ↓
FastLED.h
    ↓
platforms/esp/32/core/fastled_esp32.h (Master Aggregator)
    ↓
    ├─→ drivers/rmt/clockless_rmt_esp32.h (Default driver)
    │       ↓
    │       ├─→ rmt_4/ (ESP-IDF 4.x - legacy)
    │       │     ├── idf4_clockless_rmt_esp32.h (ChannelManager-based)
    │       │     └── channel_engine_rmt4.h / channel_engine_rmt4.cpp
    │       │
    │       └─→ rmt_5/ (ESP-IDF 5.x - default, DMA-backed)
    │             ├── idf5_clockless.h (ChannelManager-based)
    │             ├── idf5_rmt.h / idf5_rmt.cpp
    │             ├── strip_rmt.h / strip_rmt.cpp
    │             └── rmt5_* worker pool implementation (7 files)
    │
    ├─→ drivers/i2s/clockless_i2s_esp32.h (Parallel output)
    │       ↓
    │       ├─→ clockless_i2s_esp32s3.h (ESP32-S3 variant)
    │       └─→ i2s_esp32dev.h (ESP32 classic)
    │
    ├─→ drivers/lcd_cam/clockless_lcd_i80_esp32.h (S3/P4 high-bandwidth)
    │       ↓
    │       └─→ lcd_driver_i80.h / lcd_driver_i80_impl.h
    │
    ├─→ drivers/lcd_cam/clockless_lcd_rgb_esp32.h (P4 RGB interface)
    │       ↓
    │       └─→ lcd_driver_rgb.h / lcd_driver_rgb_impl.h
    │
    ├─→ drivers/parlio/clockless_parlio_esp32p4.h (P4 only)
    │       ↓
    │       └─→ parlio_engine.h / parlio_engine.cpp.hpp
    │
    └─→ drivers/spi_ws2812/clockless_spi_esp32.h (WS2812 over SPI)
            ↓
            └─→ strip_spi.h / strip_spi.cpp

Target-Specific Code Organization

The ESP32 platform supports 9+ chip variants using inline conditional compilation rather than separate directories:

Why No Target Directories?

90% of code is target-agnostic - Most driver code works identically across all ESP32 variants. Only pin definitions, interrupt handlers, and peripheral availability differ.

Example: Pin mappings (core/fastpin_esp32.h):

cpp
#if CONFIG_IDF_TARGET_ESP32
    // ESP32 classic pin definitions
    #define NUM_DIGITAL_PINS 40
    #define FASTLED_HAS_CLOCKLESS 1
#elif CONFIG_IDF_TARGET_ESP32S3
    // ESP32-S3 pin definitions
    #define NUM_DIGITAL_PINS 49
    #define FASTLED_HAS_CLOCKLESS 1
    #define FASTLED_ESP32_S3_USB_JTAG_WORKAROUND 1  // S3-specific
#elif CONFIG_IDF_TARGET_ESP32C3
    // ESP32-C3 pin definitions (RISC-V)
    #define NUM_DIGITAL_PINS 22
    #define FASTLED_HAS_CLOCKLESS 1
    #define FASTLED_RISCV 1
// ... etc for 9+ targets
#endif

Architecture-Specific Code

Architectural differences (Xtensa vs RISC-V) are handled in two ways:

  1. Timing functions: Separate files for Xtensa and RISC-V

    • core/delay.h / core/delay_riscv.h
    • core/delaycycles.h / core/delaycycles_riscv.h

  2. Interrupt handlers: Dedicated interrupts/ directory

    • interrupts/xtensa_lx6.hpp - ESP32 classic (LX6 core)
    • interrupts/xtensa_lx7.hpp - ESP32-S2/S3 (LX7 core)
    • interrupts/riscv.hpp - ESP32-C3/C6/H2/P4 (RISC-V)

IDF Version Branching

The RMT driver has completely separate implementations for ESP-IDF 4.x vs 5.x due to incompatible APIs:

cpp
// drivers/rmt/clockless_rmt_esp32.h
#if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(5, 0, 0)
    // ESP-IDF 4.x path
    #include "rmt_4/idf4_clockless_rmt_esp32.h"
#else
    // ESP-IDF 5.x path
    #include "rmt_5/idf5_clockless.h"  // ChannelManager-based
#endif

Why Separate rmt_4/ and rmt_5/?

Incompatible APIs: ESP-IDF 5.x completely redesigned the RMT peripheral API. The two implementations cannot coexist.

Different architectures:

  • RMT4: ISR-driven, manually refills RMT buffer during transmission
  • RMT5: DMA-backed, asynchronous transmission via led_strip driver
  • RMT5 V2: Worker pool pattern - reusable workers + ephemeral controllers

Cannot be merged: Attempting to unify them would create unmaintainable #ifdef spaghetti.

Driver Selection Logic

Compile-Time Selection

Drivers are selected via preprocessor macros, evaluated in core/fastled_esp32.h:

cpp
// Priority order (first match wins):

#if defined(FASTLED_ESP32_I2S) && FASTLED_ESP32_I2S
    #include "../drivers/i2s/clockless_i2s_esp32.h"  // I2S parallel

#elif defined(FASTLED_ESP32_LCD_I80) && FASTLED_ESP32_LCD_I80
    #include "../drivers/lcd_cam/clockless_lcd_i80_esp32.h"  // LCD I80 (S3/P4)

#elif defined(FASTLED_ESP32_LCD_RGB) && FASTLED_ESP32_LCD_RGB
    #include "../drivers/lcd_cam/clockless_lcd_rgb_esp32.h"  // LCD RGB (P4)

#elif defined(FASTLED_ESP32_PARLIO) && FASTLED_ESP32_PARLIO
    #include "../drivers/parlio/clockless_parlio_esp32p4.h"  // PARLIO (P4)

#elif defined(FASTLED_ESP32_HAS_CLOCKLESS_SPI)
    #include "../drivers/spi_ws2812/clockless_spi_esp32.h"  // Clockless SPI

#elif defined(FASTLED_ESP32_HAS_RMT)
    #include "../drivers/rmt/clockless_rmt_esp32.h"  // RMT (default)

#endif

Runtime Detection

Some features are detected at runtime:

  • SPI lane count: Auto-detected based on pin configuration (1/2/4/8-lane)
  • RMT channel availability: Queries hardware capabilities
  • DMA availability: Automatically enabled when supported

Hardware SPI vs Clockless SPI

The ESP32 platform has two completely different SPI subsystems:

Hardware SPI (drivers/spi/)

Purpose: Drive clocked LED chipsets (APA102, SK9822, LPD8806, etc.)

Key features:

  • Uses physical SPI clock line (SCK/SCLK)
  • DMA-backed parallel transmission
  • Multi-lane support: 1/2/4/8-lane configurations
  • Zero CPU usage during transmission
  • ~40× faster than software bitbang

Files:

  • spi_hw_1_esp32.cpp - 1-lane SPI
  • spi_hw_2_esp32.cpp - 2-lane SPI (dual)
  • spi_hw_4_esp32.cpp - 4-lane SPI (quad)
  • spi_hw_8_esp32.cpp - 8-lane SPI (octal, ESP32-P4 only)
  • spi_platform_esp32.cpp - Platform abstraction
  • spi_output_template.h - Template for SPI output
  • spi_device_proxy.h - SPI device proxy

When to use: LEDs with clock lines (APA102, SK9822, LPD8806, etc.)

Clockless SPI (drivers/spi_ws2812/)

Purpose: Emulate WS2812 timing protocol using SPI peripheral as a timing hack

Key features:

  • SPI clock hidden (not connected externally)
  • Data line creates precisely-timed pulses matching WS2812 protocol
  • Only supports WS2811/WS2812/WS2812B timing
  • Cannot support other clockless LEDs (SK6812, APA106, etc.)

Files:

  • clockless_spi_esp32.h - WS2812-over-SPI driver
  • strip_spi.h / strip_spi.cpp - SPI strip implementation

When to use: WS2812-style LEDs when RMT channels are exhausted

Limitations: Fixed timing (cannot support SK6812, APA106, etc. due to SPI constraints)

Key Design Decisions

1. No Target Directories

Decision: Use inline #ifdef CONFIG_IDF_TARGET_* within files rather than separate directories per target.

Rationale:

  • 90%+ of code is target-agnostic
  • Pin mappings are the primary difference
  • Reduces code duplication
  • Easier to maintain cross-target features

When might this change?: If target-specific code exceeds 100 lines per file, consider extracting to target-specific files.

2. No Environment Directories (Arduino vs ESP-IDF)

Decision: Handle Arduino vs ESP-IDF differences inline with minimal #ifdef ARDUINO.

Rationale:

  • Differences are typically <10 lines per file (e.g., #include <Arduino.h> vs #include "esp_system.h")
  • Arduino-ESP32 framework uses ESP-IDF underneath, so most APIs are identical
  • Separate directories would duplicate 95% of code

When might this change?: If Arduino-specific code becomes substantial (e.g., >50 lines per file).

3. IDF Version Separation (rmt_4/ vs rmt_5/)

Decision: Completely separate implementations for ESP-IDF 4.x and 5.x.

Rationale:

  • ESP-IDF 5.x completely redesigned RMT API (incompatible with 4.x)
  • RMT4 uses manual ISR refill, RMT5 uses DMA + led_strip driver
  • Cannot coexist in the same binary (Espressif runtime abort)
  • Merging would create unmaintainable #ifdef complexity

Not subject to change: This separation is permanent due to API incompatibility.

4. Worker Pool Pattern (RMT5 V2)

Decision: RMT5 V2 uses persistent worker pool + ephemeral controllers.

Rationale:

  • Solves N > K problem (more LED strips than RMT channels)
  • Workers are reused across FastLED.show() calls
  • Controllers are lightweight, created on-demand
  • Eliminates channel exhaustion issues

Files:

  • rmt5_worker_base.h - Base worker interface
  • rmt5_worker.h / rmt5_worker.cpp - Persistent worker
  • rmt5_worker_oneshot.h / rmt5_worker_oneshot.cpp - One-shot worker
  • rmt5_worker_pool.h / rmt5_worker_pool.cpp - Worker pool manager
  • rmt5_controller_lowlevel.h / rmt5_controller_lowlevel.cpp - Controller

5. Logging Control

Decision: Lightweight logging via core/esp_log_control.h to avoid heavy vfprintf dependency.

Rationale:

  • ESP-IDF's esp_log pulls in 10-20KB of printf/vfprintf code
  • Many sketches don't need logging (constrained flash/RAM)
  • Conditional logging: enabled only when SKETCH_HAS_LOTS_OF_MEMORY is true
  • Minimal error handling: FASTLED_ESP32_MINIMAL_ERROR_HANDLING skips logging entirely

6. Interrupt Handlers in Separate Directory

Decision: Move architecture-specific interrupt handlers to interrupts/ directory.

Rationale:

  • Clear separation between Xtensa LX6, LX7, and RISC-V implementations
  • Interrupt handling is orthogonal to driver selection
  • Easier to add new architectures (e.g., future Xtensa LX8)

Driver Characteristics

RMT (Remote Control Module)

  • Supported targets: All ESP32 variants
  • Max strips: 1-8 per channel (depends on variant)
  • Timing precision: Excellent (hardware-timed)
  • DMA: IDF5 only
  • Async: IDF5 only
  • Best for: General-purpose LED control, mixed timing requirements

I2S (Parallel Output)

  • Supported targets: ESP32 classic, ESP32-S3
  • Max strips: Up to 24 simultaneously
  • Timing precision: Excellent (hardware-timed)
  • DMA: Yes
  • Async: Yes
  • Constraint: All strips must use identical timing
  • Best for: High strip count with uniform chipsets (e.g., 20× WS2812 strips)

LCD_CAM (I80/RGB)

The LCD_CAM driver family includes two variants using different peripherals:

LCD_I80 (ESP32-S3/P4)

  • Supported targets: ESP32-S3, ESP32-P4
  • Peripheral: LCD_CAM in I80 mode (Intel 8080 parallel interface)
  • Max strips: Up to 16 parallel data lines
  • Encoding: 3-word per bit (6 bytes/bit, 144 bytes/LED)
  • PCLK Range: 1-80 MHz
  • Control Signals: CS, DC
  • GPIO Constraints: Flexible (avoid GPIO0, GPIO45, GPIO46 strapping pins)
  • Timing precision: Excellent (hardware-timed)
  • DMA: Yes
  • Async: Yes
  • Testing Status: ✅ Production-tested on ESP32-S3
  • Best for: High-bandwidth parallel output on S3/P4

LCD_RGB (ESP32-P4 only)

  • Supported targets: ESP32-P4 only
  • Peripheral: RGB LCD controller (dedicated RGB parallel display peripheral)
  • Max strips: Up to 16 parallel data lines
  • Encoding: 4-pixel per bit (8 bytes/bit, 192 bytes/LED)
  • PCLK Range: 1-40 MHz (optimal: 3.2 MHz for WS2812B)
  • Control Signals: HSYNC, VSYNC, DE, DISP
  • GPIO Constraints: STRICT - GPIO39-54 only (16 pins available)
    • ❌ Rejects GPIO34-38 (strapping pins - cause boot failures)
    • ❌ Rejects GPIO24-25 (USB-JTAG - prevents debugging)
  • Timing precision: Excellent (hardware-timed)
  • DMA: Yes
  • Async: Yes
  • Testing Status: ⚠️ EXPERIMENTAL - Code complete, untested on hardware
  • Memory Usage: 33% higher than LCD_I80 (PSRAM recommended for >240 LEDs)
  • Reset Gap: VSYNC front porch timing (≥50µs between frames)
  • DMA Callback: VSYNC interrupt-driven synchronization
  • Best for: ESP32-P4 parallel output (when hardware becomes available)
  • Documentation: See LCD_I80_vs_RGB_MIGRATION_GUIDE.md for migration details

PARLIO (Parallel IO)

  • Supported targets: ESP32-P4 only
  • Max strips: Parallel output (up to 16 data lines)
  • Timing precision: Excellent (hardware-timed)
  • DMA: Yes
  • Async: Yes
  • Best for: ESP32-P4 high-performance parallel output

Hardware SPI

  • Supported targets: All ESP32 variants (8-lane requires ESP32-P4)
  • Max strips: 1/2/4/8-lane configurations
  • Timing precision: N/A (clocked LEDs use external clock)
  • DMA: Yes
  • Async: Yes
  • Best for: Clocked LEDs (APA102, SK9822, LPD8806) with parallel strips

Clockless SPI (WS2812 over SPI)

  • Supported targets: All ESP32 variants
  • Max strips: Limited (typically 1-2)
  • Timing precision: Good (SPI peripheral timing)
  • DMA: Partial
  • Async: No
  • Constraint: Only WS2811/WS2812 timing supported
  • Best for: WS2812 LEDs when RMT channels are exhausted

File Count Summary

  • Core files: 10 files
  • Driver files: 52 files
    • RMT: 21 files (1 dispatcher + 8 rmt_4 + 12 rmt_5)
    • I2S: 5 files
    • LCD_CAM: 12 files
    • PARLIO: 4 files
    • Hardware SPI: 7 files
    • Clockless SPI: 3 files
  • Interrupt handlers: 5 files
  • Root-level files: 4 files (platform abstraction)
  • Audio/OTA: Pre-existing subdirectories

Total: ~71 files organized into logical hierarchy

Include Path Examples

From User Code (Arduino sketch)

cpp
#include <FastLED.h>  // Top-level include (finds ESP32 automatically)

From Core Aggregator (core/fastled_esp32.h)

cpp
#include "../drivers/rmt/clockless_rmt_esp32.h"  // RMT dispatcher
#include "../drivers/i2s/clockless_i2s_esp32.h"  // I2S driver
#include "../drivers/spi_ws2812/clockless_spi_esp32.h"  // Clockless SPI

From Driver Files (e.g., drivers/rmt/clockless_rmt_esp32.h)

cpp
#include "rmt_4/idf4_clockless_rmt_esp32.h"  // Relative (same parent)
#include "rmt_5/idf5_clockless.h"  // Relative (same parent)

From Global Headers (e.g., src/fastspi.h)

cpp
#include "platforms/esp/32/drivers/spi/spi_device_proxy.h"  // Absolute from src/
#include "platforms/esp/32/drivers/spi/spi_output_template.h"

Backward Compatibility

Old Includes (Before Refactoring)

cpp
#include "platforms/esp/32/fastled_esp32.h"  // ❌ Old path
#include "platforms/esp/32/clockless_rmt_esp32.h"  // ❌ Old path

New Includes (After Refactoring)

cpp
#include "platforms/esp/32/core/fastled_esp32.h"  // ✅ New path
#include "platforms/esp/32/drivers/rmt/clockless_rmt_esp32.h"  // ✅ New path

Migration: All includes were updated during the refactoring. User code remains unchanged (uses #include <FastLED.h>).

Testing & Validation

Compilation Validation

  • ESP32 classic: ✅ Compiles (RMT default)
  • ESP32-S3: ✅ Compiles (RMT default, I2S available, LCD_CAM available)
  • ESP32-C3: ✅ Compiles (RMT default, RISC-V)
  • ESP32-P4: ⚠️ Limited (PARLIO, 8-lane SPI, LCD RGB)

Test Coverage

  • C++ unit tests: All tests pass (driver logic validated)
  • Compilation tests: Multi-platform validation (ESP32, S3, C3)
  • QEMU tests: Runtime validation on ESP32 emulator

Known Limitations

  • ESP32-P4 support limited (hardware not widely available yet)
  • QEMU test infrastructure has path issues (merged.bin location)
  • Some advanced drivers (LCD_CAM, PARLIO) not fully tested in CI

Future Enhancements

Potential Improvements

  1. Common driver utilities: Extract shared code to drivers/common/
  2. Target directories: Only if target-specific code exceeds 100 lines per file
  3. Environment separation: Only if Arduino-specific code becomes substantial
  4. Enhanced testing: Expand QEMU coverage to all drivers

Not Planned

  • Merging rmt_4 and rmt_5: Incompatible APIs, intentionally separate
  • Single-file drivers: Current organization is already maintainable
  • Removing architecture-specific files: Necessary for Xtensa vs RISC-V differences

References

  • ESP32 README: src/platforms/esp/32/README.md - Driver selection, build flags
  • RMT5 Research: src/platforms/esp/32/drivers/rmt/rmt_5/RMT_RESEARCH.md - RMT5 internals
  • LCD Implementation: src/platforms/esp/32/drivers/lcd_cam/implementation_notes.md - LCD_CAM details
  • LCD_RGB Research: src/platforms/esp/32/drivers/lcd_cam/RGB_LCD_RESEARCH.md - RGB LCD peripheral analysis
  • LCD Migration Guide: src/platforms/esp/32/drivers/lcd_cam/LCD_I80_vs_RGB_MIGRATION_GUIDE.md - I80→RGB migration
  • LCD_RGB Release Notes: src/platforms/esp/32/drivers/lcd_cam/LCD_RGB_RELEASE_NOTES.md - Feature announcement
  • PARLIO Design: src/platforms/esp/32/ESP32-P4_PARLIO_DESIGN.md - PARLIO architecture
  • Interrupt Research: src/platforms/esp/32/interrupts/INVESTIGATE.md - ISR implementation notes

Summary

The ESP32 platform architecture uses a hierarchical structure with:

  • Clear separation: Core vs drivers vs interrupt handlers
  • Conditional compilation: Target and IDF version branching
  • Driver diversity: 6 different driver types for different use cases
  • Backward compatibility: Zero functional changes, pure refactoring
  • Maintainability: Easy to find, understand, and modify driver code

This organization makes it straightforward for developers to:

  • Find driver implementations quickly
  • Understand driver selection process
  • Add new drivers or modify existing ones
  • Navigate the codebase efficiently
  • Contribute to the project

Version: 1.1 Last Updated: 2025-11-05 Status: Complete (Post-Refactoring + LCD_RGB Documentation)