Skip to content

README.md

Latest commit

 

History

History
95 lines (76 loc) · 3.99 KB

README.md

File metadata and controls

95 lines (76 loc) · 3.99 KB
Raw

FastLED Platform: shared

Common, platform‑agnostic components used by multiple targets (data export, UI, SPI drivers).

Subdirectories

  • active_strip_data/: Zero‑copy strip data export and screenmap tracking across frames. See active_strip_data.h for ActiveStripData manager and JSON helpers.
  • ui/: JSON‑driven UI system. ui/json/ contains JsonUiManager, components (Slider, Button, Checkbox, Dropdown, NumberField, Audio, Title, Description), and integration guide (readme.md).

Multi-Lane SPI Support

Shared platform code includes multi-lane SPI transposer infrastructure supporting 1/2/4/8 parallel data lanes:

Unified SPI Transposer (spi_transposer.*)

NEW: Unified bit-interleaving driver for all parallel SPI widths. Transposes sequential pixel data into parallel bitstreams for simultaneous multi-strip output.

Supported Widths:

  • 1-lane (single-SPI)
  • 2-lane (dual-SPI) via transpose2()
  • 4-lane (quad-SPI) via transpose4()
  • 8-lane (octo-SPI) via transpose8() ✨

Key Features:

  • Single unified API: All transpose operations in SPITransposer class
  • Consistent naming: transpose2(), transpose4(), transpose8() methods
  • Optimized algorithms: Width-specific interleaving for each configuration
  • Platform-agnostic: Used by both hardware and software implementations
  • Zero-copy operation: Efficient memory handling

Legacy Compatibility:

  • spi_transposer_dual.* - Deprecated wrappers for 2-lane (calls transpose2())
  • spi_transposer_quad.* - Deprecated wrappers for 4-lane/8-lane (calls transpose4()/transpose8())

SPI Hardware Interfaces

Platform-independent SPI configuration APIs organized by lane count:

Interfaces:

  • spi_hw_1.h - Single-lane SPI (SpiHw1)
  • spi_hw_2.h - Dual-lane SPI (SpiHw2)
  • spi_hw_4.h - 4-lane SPI (SpiHw4)
  • spi_hw_8.h - 8-lane SPI (SpiHw8) ✨ NEW

Example Configuration:

namespace fl {
struct SpiHw8 {
    struct Config {
        uint8_t data0, data1, data2, data3;  // First 4 data pins
        uint8_t data4, data5, data6, data7;  // Next 4 data pins (8-lane)
        uint8_t clock;                        // Shared clock pin
        // ... other config
    };
};
}

Configuration supports:

  • Explicit lane count per interface (no ambiguity)
  • Clock pin assignment
  • Hardware vs software fallback selection
  • Per-platform capabilities detection

Hardware vs Software

The transposer and interfaces are used by both:

  • Hardware SPI (ESP32-P4 octal, ESP32 quad): DMA-accelerated, ~40× faster
  • Software SPI (bitbang ISR/blocking): Platform-agnostic fallback for all platforms

See platform-specific READMEs for implementation details:

  • src/platforms/esp/32/README.md - ESP32 hardware multi-lane SPI
  • src/platforms/shared/spi_bitbang/README.md - Software multi-width SPI

Behavior and integration

  • ActiveStripData listens to EngineEvents to clear and publish per‑frame data; exposes legacy and new JSON creators and parsing helpers, plus on‑demand screenmap updates.
  • The UI system uses weak pointers for safe component lifecycle, and a manager that batches outbound JSON and applies inbound updates on frame boundaries.

Example export flow (frame lifecycle)

  1. During show(), the driver renders pixels. When the frame completes, EngineEvents::onEndShowLeds fires.
  2. ActiveStripData listens and clears per‑frame accumulators, then snapshots strip/screenmap data for export.
  3. The platform bridge pulls JSON or raw buffers (depending on target) and forwards them to the UI/consumer.
  4. After UI updates arrive, EngineEvents::onEndFrame applies any pending control changes via the UI manager.

Bridge stub outline:

// Pseudocode for a host bridge loop
void pump() {
    if (auto json = ActiveStripData::createLegacyJson(/*alloc*/)) {
        platform_send_json(json.ptr);
        ActiveStripData::freeJson(json.ptr);
    }
    if (auto incoming = platform_recv_ui_json()) {
        JsonUiManager::instance().updateUiComponents(incoming);
    }
}