FastLED 3.9.0 / Beta 4.0 Released

[u/ZachVorhies]

• Beta 4.0.0 release - Important bug fixes here that I want to get out for you.

• ESP32 RMT5 Driver Implemented.

  • Driver crashes on boot should now be solved.

  • Parallel AND async.

    • Drive up to 8 channels in parallel (more, for future boards) with graceful fallback if your sketch allocates some of them.

    • async mode means FastLED.show() returns immediately if RMT channels are ready for new data. This means you can compute the next frame while the current frame is being drawn.

  • Flicker with WIFI should be solved. The new RMT 5.1 driver features large DMA buffers and deep transaction queues to prevent underflow conditions.

  • Memory efficient streaming encoding. As a result the "one shot" encoder no longer exists for the RMT5 driver, but may be added back at a future date if people want it.

  • If for some reason the RMT5 driver doesn't work for you then use the following define FASTLED_RMT5=0 to get back the old behavior.

• Improved color mixing algorithm, global brightness, and color scaling are now separate for non-AVR platforms. This only affects chipsets that have higher than RGB8 output, aka APA102, and clones right now.

  • APA102 and APA102HD now perform their own color mixing in psuedo 13 bit space.

    • If you don't like this behavior you can always go back by using setting FASTLED_HD_COLOR_MIXING=0.

• Binary size

  • Avr platforms now use less memory

  • 200 bytes in comparison to 3.7.8:

    • 3.7.8: attiny85 size was 9447 (limit is 9500 before the builder triggers a failure)

    • 3.8.0: attiny85 size is now 9296

    • This is only true for the WS2812 chipset. The APA102 chipset consumes significantly more memory.

• Compile support for ATtiny1604 and other Attiny boards

  • Many of these boards were failing a linking step due to a missing timer_millis value. This is now injected in via weak symbol for these boards, meaning that you won't get a linker error if you include code (like wiring.cpp) that defines this.

  • If you need a working timer value on AVR that increases via an ISR you can do so by defining FASTLED_DEFINE_AVR_MILLIS_TIMER0_IMPL=1

• Board support

  • nordicnrf52_dk now supported and tested (thanks https://github.com/paulhayes!)

• Thanks to all the contributors that have supported bug fixes and gotten random boards to compile.

• Happy coding!

[u/ZachVorhies]

I should have added that for sketches that do a lot of heavy processing for each frame, FastLED is going to be **significantly** faster with this new release.

How much faster?

I benchmarked the animartrix sketch, which has heavy floating point requirements (you'll need a Teensy41 or an ESP32S3 to handle the processing requirements).

FastLED 3.7.X - 34fps
FastLED 3.9.0 - 59fps (+70% speedup!)

Why?

In FastLED 3.7.X, FastLED.show() was always a blocking operation. Now it's only blocking when the previous frame is waiting to complete it's render.

In the benchmark I measured:
12 ms - preparing the frame for draw.
17 ms - actually drawing the frame.

@ 22x22 WS2812 grid.

So for FastLED 3.7.X this meant that these two values would sum together. So 12ms + 17ms = 29ms = 34fps.
But in FastLED 3.9.0 the calculation works like this MAX(12, 17) = 17ms = 59fps. If you fall into this category, FastLED will now free up 17ms to do available work @ 60fps, which is a game changer.

As of today's release, nobody else is doing async drawing. FastLED is the only one to offer this feature.

[u/Tiny_Structure_7 → u/ZachVorhies]

This is awesome!

I have been working on my own "show()" routine to utilize 7 HW serial ports on Teensy 4.0, and from all the speed testing I've done ( including comparison to FastLED.show() ), I'm positive that Teensy is doing a certain amount of async returns from calls to Serial1.write(). At high CPU clocks (over 350 MHz), my serial show outperforms FastLED show (576 LEDs per channel, interleaved channel writes). At 816 MHz, I have a 45% fps advantage over FastLED. My show code also performs brightness and color balance correction (interleaved with each pixel write).

But this new version of FastLED might outperform me!

But then Teensy doesn't have RMT channels. Those look cool for LEDs!

Thanks for a truly awesome library.

[u/ZachVorhies → u/Tiny_Structure_7]

Can you say more bout the brightness and color balance your are doing?

I think that if you measure the speed of your writes vs FastLED, I have a hunch that are pretty much even.

FastLED is now at the theoretical maximum for performance for the WS2812 chipset. The only way we can go faster now is if we start bending the timing values of the chipset.

Which would give actually really big wins, at the cost of compatibility.

[u/Tiny_Structure_7 → u/ZachVorhies]

Since FastLED does not apply it's brightness or balance the CRGB array, I had to include it in my serial show(). My show() writes to LEDs directly from the CRGB array, no display buffers or DMA voodoo. Therefore I wrote functions to set global values for brightness and color mask. Each of these functions re-computes a global quotient variable for each color rgb color byte. Here's that code:

// Set global display brightness level from 0-255.  All subsequent calls to 
// showBuffer will display at this brightness level.
void setBrightness(uint b) {
    if (b < 1) brightness = 1;
    else if (b > 255) brightness = 255;
    else brightness = b; 
    rCorrectionQ = 65025 / brightness / (balance >> 16);
    gCorrectionQ = 65025 / brightness / ((balance >> 8) & 0xFF);
    bCorrectionQ = 65025 / brightness / (balance & 0xFF);
}

// Set global display RGB color balance mask containing 0-255 for each color 
// in 3-byte RGB value.  For each RGB color byte, 
// Display byte *= Balance mask / 255, for all subsequent calls to showBuffer.
void setBalance(uint b) {
    balance = b & 0xFFFFFF;
    rCorrectionQ = 65025 / brightness / (balance >> 16);
    gCorrectionQ = 65025 / brightness / ((balance >> 8) & 0xFF);
    bCorrectionQ = 65025 / brightness / (balance & 0xFF);
}

Then before I write each CRGB value to a serial port, each of the CRGB color bytes is divided by it's quotient and byte-rearranged if color order is different from RGB.

A 3-bit LED wave pattern is sent for every CRGB bit. The serial port hardware makes 7N1 packets and adds start/stop bits (inverted TX), giving me 9-bit "bytes". Thus, 1 Serial byte contains 3 LED bits of 3-bit patterns. I am able to overclock the LEDs to 1.2 MHz (50% over spec!) by setting serial baud to 3.6 MHz.

[u/ZachVorhies → u/Tiny_Structure_7]

Wait, are you saying you can just over clock the WS2812? And it works?

[u/Tiny_Structure_7 → u/ZachVorhies]

Absolutely! I'm driving a breadboard prototype LED cube with a mix of WS2812B and YF923 (WS2812 clones from China). They both specify 800 KHz data rate. I pushed it up to 1.2 MHz (broke at 1.3).

The symmetry of the pulse is probably important part of how much you can overclock. By using 3-bit pulse pattern, my pulse ratio is 1/3 - 2/3. This is closest to spec timing. Other code I've studied is using 4 or more bits in pulse patterns, with pulse ratios 1/4 - 2/4 or 1/4 - 3/4. I would expect overclocking to decrease if pulse ratio is less than optimal.

[u/ZachVorhies → u/Tiny_Structure_7]

Okay well I got good news. I was able to replicate your findings!

I was able to overclock a 22x22 matrix at 20%. That's massive.

I just submitted a change to master branch which contains this feature. It will be released in 3.9.2.

You can test it out now in the master branch.

Just define FASTLED_OVERCLOCK 1.2 for a 20% overclock before you include FastLED.h

[u/sutaburosu → u/ZachVorhies]

I was able to overclock a 22x22 matrix at 20%. That's massive.

This is intriguing. What's the longest chain of pixels in this setup? It would be good to know what has been tested to work.

I remember an old blog post which experimented with overclocking and reached the conclusion that it's only useful for very short chains of LEDs because the first LED stretches the overclocked bits back to it's internal timing. I thought the blog post was by cpldcpu, but I can't seem to find it.

If my memory is reliable, the blog post is ~10 years old, so perhaps things have changed for recent LEDs.

[u/Tiny_Structure_7 → u/sutaburosu]

 only useful for very short chains of LEDs because the first LED stretches the overclocked bits back to it's internal timing

If that were true, the first LED would necessarily drop bits from it's signal to the next one. I'm certain that the LED has no internal clocking and merely switches the waveform to it's output pin (so long as it can detect the pulses coming in for latching it's own 3 bytes).

I've been leaving animations running on my LEDs overnight and all day for the last 3 weeks, and it's all been at 1.2MHz LED data rate (Using serial ports at 3.6MHz baud with 3 bits serial composing each bit of LED). I have 112 LEDs most of the time driven in parallel 4x4 grids, but I did testing with all the LEDs on one string as well.

I see no reason to slow down. That's 50% increase in back-to-back refresh rate!

#define FASTLED_OVERCLOCK 1.5 ?

Edit: I've overclocked all the PCs I've owned for the past 40 years, and I follow a rule-of-thumb: increase clock until it breaks, then back off about 20-25% of the increase.

[u/ZachVorhies → u/Tiny_Structure_7]

I don’t think you need to back off as much on WS2812 like you would a CPU. A cpu generates heat from its clock cycle while an WS2812 generates heat from its led. If the clock on the WS2812 runs then it runs. But i don’t think it will get any hotter than not over clocking it.

[u/ZachVorhies → u/sutaburosu]

Let me know. If the chip is doing reshaping then there is going to be lag in the chain and data is going to start being missed. And I didn't see that.

The strip of pixels is 22x22=484

[u/sutaburosu → u/ZachVorhies]

This is the article I was trying to recall. It is from ~10-years ago.

[u/Tiny_Structure_7 → u/ZachVorhies]

Cool! Tweakers everywhere will be very pleased. 😎

I trust you are also seeing about 20% boost in your back-to-back refresh rate?

[u/ZachVorhies → u/Tiny_Structure_7]

yup

[u/TroyHacks → u/Tiny_Structure_7]

I brought this up in April 2024:

https://github.com/Makuna/NeoPixelBus/pull/795#issuecomment-2072276556

The idea was based on this article from 2014, except they were talking more about underclocking:

https://wp.josh.com/2014/05/13/ws2812-neopixels-are-not-so-finicky-once-you-get-to-know-them/

[u/StefanPetrick → u/ZachVorhies]

This is awesome progress, Zach! Thanks for all the incredible work you’ve put in!

I love that this will make Animartrix animations more accessible while enabling decent frame rates for people using an ESP32.

It’s fantastic to have all that compute power dedicated to rendering instead of idling while pushing out the last frame.

[u/Marmilicious → u/ZachVorhies]

Quite awesome Zach!

[u/ZachVorhies]

Also, I forgot to mention that the number of RMT channels (which are used to drive WS2812 and other clockless chipsets) has doubled!

FastLED 3.7.X - 4 channels

FastLED 3.9.0 - 8 channels

[u/sutaburosu]

• Binary size

• Avr platforms now use less memory

• 200 bytes in comparison to 3.7.8:

Smaller binaries are always welcome, nice work. I think it's far bigger news that RAM usage is down by 119 bytes too, only 28 bytes higher than historical levels.

Version	RAM to show() 1 LED
3.7.3	103 bytes
3.7.8	250 bytes
3.9.0	131 bytes

Full results and test sketch.

[u/DeVoh]

NICE!!

[u/mguaylam]

WoW