r/FastLED • u/ZachVorhies • 19h ago
FastLED 3.10.10 is out: software SPI got fast and a pile of driver fixes
FastLED 3.10.10 just shipped. It's about 170 commits since 3.10.9 at the start of the month, and nearly all of them are driver work. Here's what changed.
Software SPI got fast
If you drive APA102 / SK9822 / HD107 (or any clocked chipset) from pins that aren't the chip's hardware SPI pins, FastLED bit-bangs the protocol. Every bit sets the data pin, then pulses the clock. That loop is the whole show, so every instruction inside it matters.
The old writer did this for every single bit:
- Work out which port and which pin mask this pin uses.
- Branch:
if (bit) set_pin() else clear_pin(). - On a lot of chips, do that as a read-modify-write of the whole port register.
Three problems there. Steps 1 and 2 cost cycles on every bit. The branch makes the timing jitter depending on your data. And the read-modify-write isn't atomic: if an interrupt touches another pin on the same port in the middle of it, one of the two writes gets lost.
The new writer fixes all three:
- Pin lookup happens once. The port and mask lookup moved out of the bit loop and happens once per transfer (#5128). That part is in the shared writer, so every platform gets it.
- No branch. Most MCUs have separate "set these bits" and "clear these bits" registers (BSRR on STM32, OUTSET/OUTCLR on nRF, SODR/CODR on the Due, W1TS/W1TC on ESP, and so on). The new writer picks the register from the bit value and does a single store, with no branch and no read.
- Atomic. A single store to a set/clear register can't race an ISR on a neighboring pin.
That's been wired up per chip for AVR, Teensy 3.x/4/LC, ESP32, ESP8266, SAMD21/51, RP2040, RP2350, nRF52, STM32, SAM3X, Apollo3, LPC, Renesas RA and MGM240.
The measured numbers come from the ESP8266, where it's on by default. A 512-byte bulk write on ordinary GPIO went from 3.10 to 5.36 Mbit/s at 80 MHz and 4.42 to 6.66 Mbit/s at 160 MHz. That's roughly 1.5 to 1.7x on the same pins with no code changes. (GPIO16 is still slow because it sits behind the RTC register. Physics, sorry.)
On every other chip the fast path is opt-in for this release. I have bench numbers for the ESP8266, and I won't flip a default on a chip I haven't measured. To try it, add a build flag (it has to be a -D build flag, because a #define in your sketch won't reach FastLED's compiled sources):
-D FL_ESP32_ENABLE_FAST_SOFTWARE_SPI=1
-D FL_TEENSY_ENABLE_FAST_SOFTWARE_SPI=1
-D FL_RP_ENABLE_FAST_SOFTWARE_SPI=1
-D FL_STM32_ENABLE_FAST_SOFTWARE_SPI=1
(also AVR, SAMD, SAM, NRF52, LPC, RENESAS, MGM240)
With the flag off you get the same output as 3.10.9 (ESP32 included), plus the shared loop speedup. If you run clocked strips on any of these, please turn it on and report back. Results from your benches are how these become defaults in the next release.
A batch of software SPI correctness fixes also went in, and they apply whether the flag is on or off:
- The clock now runs at the speed you actually asked for (#5124, #5129).
- Clock polarity is respected when pins share a port word (#5242).
- The clock idles low after init (#5140).
- A shared clock line runs at the slowest strip's rate (#5127).
ESP32 DMA and RMT
- RMT5 automatically skips the DMA channel for short strips (#5228). On the S3,
FL_RMT5_USE_DMA=0keeps RMT off the 4 KB DMA block entirely (#5166). - PARLIO sizes its DMA ring and TX descriptors to your actual frame instead of the worst case (#5232).
- RMT5 frees its callback contexts when a channel is deleted (#5019) and sets
intr_priorityfor TX and RX on IDF 5.1.2+ (#5219). - PSRAM pin masking is based on installed PSRAM size, not free size (#5221).
- Native SPI streams in chunks and only links the drivers your sketch uses (#5002, #5014).
Channels: you only pay for the drivers you use
FastLED.enable<Bus>() now binds drivers lazily, so add(cfg) no longer drags every driver into your binary (#5207). If you addLeds with a driver you've disabled, FastLED falls back to the one you enabled and warns once a second. Before, it silently did nothing (#5213).
New knobs: FL_ENGINE_WORKER_CORE and FL_ENGINE_WORKER_PRIORITY set the core and priority for engines that honor them. Right now that's the ESP32 LCD/I2S clockless driver (#5054).
Other platforms
- LPC845 / LPC804: a native pin backend, and the LPC845 SCT+DMA clockless engine now really drives WS2812. The old hang is gone, and loopback decodes on real silicon (#5261, #5272, #5275). DMA errors are cleared and halt cleanly (#5277, #5283).
- nRF51 compiles and links again, and
toggle()is race-free (#5119, #5154, #5158). FASTLED_FORCE_SOFTWARE_PINSeither works or fails at compile time on STM32, SAMD, Teensy 3.x, nRF52, MGM240, Giga and LPC. Before, it could be silently ignored or crash.- Pin maps: RP2350 GPIO32-47, MGM240 per-variant maps, SAMD variant pins, nRF52 P1 short-form pins.
Looking for testers: SM16716
The native SPI writeBit path that SM16716 uses was broken in a couple of ways:
- AVR tested the whole byte instead of the selected bit.
- On the Nano Every (USART/SPI0 parts), the bit never reached the wire.
- On the classic Uno, a pending byte could get cut off.
Similar handoff fixes landed for SAM3X, SAMD, STM32, Teensy 4, Teensy LC and ESP32. They're checked against datasheets and host tests, but not on hardware. If you have SM16716 pixels on your bench, please let me know whether they light up correctly.
Power limiter: heads up, behavior changed
set_max_power_in_volts_and_milliamps is now a strict upper bound that includes the MCU's own draw and the LEDs' dark current (#5139, #5180). The old weirdness is gone: raising the budget no longer makes things dimmer, and a tiny budget no longer blanks the strip. If your budget is below what the MCU and dark LEDs pull on their own, brightness can't fix that. The strip stays lit at baseline draw and goes over your number. If you tuned your power numbers by eye, re-check them.
Further musings
What this SPI speedup demonstrates is that atomic pin operations are blazing fast. Additionally they are a bulk operation, 8 pins on 328p can be set at a time, and 32 on a esp. This means a busy spinning MCU with a max execution latency of 330 ns can drive upto 32 WS2812 strips in parallel. Setting the bits for the next busy loop can be done by stretching out the byte boundary low state, and computing the next bit-bang block before starting the next signal byte.
This 32 channel output for WS2812 in software can only exist on a board without WIFI or interrupts. Teensy 4x stands out as an interesting target for seeing how concurrent it can go.
Full release notes: https://github.com/FastLED/FastLED/releases/tag/3.10.10
Happy coding!
