espressif__led_strip/NOTE_SPI.md

SPI-based LED Strip Driver Analysis

Overview

This driver emulates RMT (Remote Control) signals for WS2812B/SK6812 LED strips using SPI peripheral. It works by encoding each data bit into multiple SPI bits to achieve the required timing characteristics.

Clock Configuration

• SPI Clock Frequency: 2.5 MHz (LED_STRIP_SPI_DEFAULT_RESOLUTION)
• SPI Bit Period: 1/2.5MHz = 400 nanoseconds
• Tolerance: ±300 KHz (2.2 MHz to 2.8 MHz accepted)

Bit Encoding Scheme

Each 1 RMT data bit is encoded as 3 SPI bits, giving a total symbol period of 1.2 μs.

Encoding Patterns

Data Bit	SPI Pattern (MSB first)	High Time	Low Time	Total Time
0	100 (binary)	400 ns	800 ns	1200 ns
1	110 (binary)	800 ns	400 ns	1200 ns

WS2812B Timing Compatibility

The encoding matches WS2812B specifications:

• T0H (0 high time): ~400ns (spec: 350±150ns)
• T0L (0 low time): ~800ns (spec: 800±150ns)
• T1H (1 high time): ~800ns (spec: 700±150ns)
• T1L (1 low time): ~400ns (spec: 600±150ns)

Why 3 Bits per Symbol?

The choice of 3 SPI bits per data bit is driven by timing requirements:

1. Duty Cycle Ratio: WS2812B needs approximately 1:2 or 2:1 high/low ratios
2. Granularity:
   • 2 bits would only give 50/50 split (insufficient)
   • 3 bits provides 33/66% or 66/33% ratios (optimal)
   • 4+ bits would make the period too long (>1.6μs)
3. Clock Frequency: At 2.5 MHz, 3 bits = 1.2μs matches the ~1.25μs WS2812B bit period

Memory Usage

Each LED color component requires:

• 1 byte of actual data
• 3 bytes of SPI transmission data (3:1 expansion)

For RGB LEDs:

• 3 bytes per pixel → 9 bytes SPI data per pixel

For RGBW LEDs:

• 4 bytes per pixel → 12 bytes SPI data per pixel

Defined as: SPI_BYTES_PER_COLOR_BYTE = 3

Bit Mapping Function

The __led_strip_spi_bit() function expands each 8-bit color value into 24 SPI bits (3 bytes):

static void __led_strip_spi_bit(uint8_t data, uint8_t *buf)

Input: 1 byte of color data (8 bits)
Output: 3 bytes written to buffer (24 SPI bits = 8 RMT symbols)

Bit Order

The function processes bits from LSB to MSB and maps them across 3 bytes:

• Bit 0 (LSB) → buf[2] bits 2:1
• Bit 1 → buf[2] bits 5:4, plus bit 7
• Bit 2 → buf[2] bit 7, buf[1] bit 0
• Bit 3 → buf[1] bits 3:2
• Bit 4 → buf[1] bits 6:5
• Bit 5 → buf[0] bits 1:0
• Bit 6 → buf[0] bits 4:3
• Bit 7 (MSB) → buf[0] bits 7:6

Each data bit becomes a 3-bit pattern:

• 0 → 100 (binary)
• 1 → 110 (binary)

Data Transmission

The led_strip_spi_refresh() function handles transmission with chunking:

1. Total data size: strip_len × bytes_per_pixel × 3
2. Max transfer size: Limited by SPI bus configuration (max_transfer_sz)
3. Chunked transfers: Data sent in chunks if it exceeds max transfer size
4. Transmission mode: spi_device_polling_transmit() used for blocking transfer

Advantages of SPI Emulation

1. No RMT peripheral needed: Frees up RMT channels for other uses
2. DMA support: Can use DMA for efficient transfers
3. Precise timing: Hardware SPI ensures consistent bit timing
4. Scalability: Can drive long LED strips with proper DMA buffer sizing

Limitations

1. 3x memory overhead: Requires 3× the buffer space vs. RMT
2. Fixed clock: Requires SPI clock source with ~2.5 MHz capability
3. No flexibility: Cannot easily adjust timing for non-WS2812B LEDs
4. SPI bus exclusive: Ties up an entire SPI peripheral

Date

Analysis performed: 2025年11月10日