FastLED Library

Want to control a strip of leds? Or control 10's of thousands? FastLED has your back.

FastLED is a robust and massively parallel-led driver for Arduino, Esp32, RaspberryPi, Atmega, Teensy, Uno, Apollo3 Arm and more. Also runs on dirt cheap sub $1 devices, due to it's incredibly small compile size. High end devices can drive upto ~30k LEDS (Teensy) and ~20k on ESP32. Supports nearly every single LED chipset in existence. Background rendering (ESP32/Teensy/RaspberriPi) means you can respond to user input while the leds render. FastLED is the third most popular library on Arduino.

FastLED has recently begun to evolve. While before the FastLED codebase was just a highly compatible cross platform LED driver, now it is becoming a cross platform way to generate visualizers that run on AVR, esp32, teensy, Rasperri PI etc

Documentation

Can be found here

Star History

About

This is a driver library for easily & efficiently controlling a wide variety of LED chipsets, like the ones sold by Adafruit (NeoPixel, DotStar, LPD8806), Sparkfun (WS2801), and AliExpress.

The 3.9.x series introduced:

• Massive parallel rendering to drive thousands of LEDs.
• Background rendering of LEDs so that your program/sketch can prepare the next frame and respond to user input without affect frame rate.

In addition to writing to the LEDs, this library also includes a number of functions for high-performing 8-bit math for manipulating your RGB values, as well as low level classes for abstracting out access to pins and SPI hardware, while still keeping things as fast as possible.

We have multiple goals with this library:

• Quick start for new developers - hook up your LEDs and go, no need to think about specifics of the LED chipsets being used
• Zero pain switching LED chipsets - you get some new LEDs that the library supports, just change the definition of LEDs you're using, et. voila! Your code is running with the new LEDs.
• High performance - with features like zero cost global brightness scaling, high performance 8-bit math for RGB manipulation, and some of the fastest bit-bang'd SPI support around, FastLED wants to keep as many CPU cycles available for your LED patterns as possible

Example

This is an Arduino Sketch that will run on Arduino Uno/Esp32/Raspberri Pi

// New feature! Overclocking WS2812
// #define FASTLED_OVERCLOCK 1.2 // 20% overclock ~ 960 khz.
#include <FastLED.h>
#define NUM_LEDS 60
#define DATA_PIN 6
CRGB leds[NUM_LEDS];
void setup() { FastLED.addLeds<NEOPIXEL, DATA_PIN>(leds, NUM_LEDS); }
void loop() {
	leds[0] = CRGB::White; FastLED.show(); delay(30);
	leds[0] = CRGB::Black; FastLED.show(); delay(30);
}

For more examples, see this link. Web compiled examples.

New Feature Announcements

New in 3.10.0: Animartrix out of beta

New in 3.9.16: WaveFx / Multi Layer Compositing / Time-based animation control

Video:

https://github.com/user-attachments/assets/ff8e0432-3e0d-47cc-a444-82ce27f562af

Major release for tech-artists!

Lots of improvements in this release, read the full change list here

Links

• This demo -> FxWave2d
  • Wave Simulation Library
• FireCylinder
  • Wraps around so that (0,y) ~= (width-1,y)
• TimeAlpha
  • Precision control of animations with time-based alpha transition.

New in 3.9.13: HD107 "Turbo" 40Mhz LED Support

New in 3.9.12: WS2816 "HD" LED support

New in 3.9.10: Super Stable WS2812 SPI driver for ESP32

New in 3.9.9: 16-way Yves I2S parallel driver for the ESP32-S3

*Note some users find that newer versions of the ESP32 Arduino core (3.10) don't work very well, but older versions do, see issue 1903

New in 3.9.8 - Massive Teensy 4.1 & 4.0 WS2812 LED output

• Teensy 4.1: 50 parallel pins
• Teensy 4.0: 42 parallel pins

New in 3.9.2 - Overclocking of WS2812

Update: max overclock has been reported at +70%: https://www.reddit.com/r/FastLED/comments/1gkcb6m/fastled_FASTLED_OVERCLOCK_17/

New in 3.7.7 - RGBW LED Strip Support

Supported Platforms

Arduino

The build system is under going optimization and the builds will appear red until that migration is complete. Despite the red status, everything still works

New FastLED 3.9.14! - Very memory limited, so only tested against examples WS2812 Blink and APA102

Now works in 3.9.14!

Teensy

Specific Features

NRF

(This board has mbed engine but doesn't compile against Arduino.h right now for some unknown reason.)

Apollo3

Beta support in 3.10.2

STM

(PlatformIO doesn't support this board yet and we don't know what the build info is to support this is yet)

Raspberry Pi

Esp

Now supported as of FastLED 3.9.10!

Specific features

Legacy Toolchains

Espressif's current evaluation of FastLED's compatibility with their product sheet can be found here

x86

Wasm

Compiled Library Size Check

Install

Arduino IDE

After the ArduinoIDE is installed then add the library to your IDE

PlatformIO

PlatformIO offers an incredible IDE experience. Setup is easier than you think. Follow our guide here. Our template will allow your project to be compiled by both PlatformIO and ArduinoIDE

https://github.com/FastLED/PlatformIO-Starter

How to maximize the number of parallel WS2812 outputs

Some of the new processors can drive many many WS2812 strips in parallel.

Leader Boards: Stock Setups

Teensy 4.0/4.1

This chipset holds the current record for parallel output in a stock configuration. The theoretical output is 50 strips at a time with Teensy 4.1 and 42 strips with Teensy 4.2.

See this example on how to enable.

ESP32DEV

Surprisingly it's the good old ESP32Dev and not the ESP32S3, which holds the esp record for the amount of parallel outputs at 24 through I2S, and 8 via RMT.

I2S needs special setup as of 3.9.11 and earlier (current version of this writing is 3.9.11) see the example here.

ESP32-S3

The S3 is a CPU beast, but has half the RMT tx channels (4) and 2/3rds the I2S channels (16) of ESPDev. The S3 requires a special driver for I2S which you can find in this example

*Note some users find that newer versions of the ESP32 arduino core (3.10) don't work very well, but older versions do, see issue 1903

RaspberriPi

I (Zach Vorhies) don't use this platform. Help wanted on what the limits of this chip is.

Exotic Setups

If you are willing to make a custom board with shift registers, then the ESp32S3 and ESP32Dev have special "virtual pin" libraries. These libraries will allow you to drive 120 parallel WS2812 outputs. However these are not included in FastLED but are compatible with it.

• Esp32DEV: https://github.com/hpwit/I2SClocklessVirtualLedDriver
• Esp32-S3: https://github.com/hpwit/I2SClockLessLedVirtualDriveresp32s3

Development

Zero pain setup and install/test/run. Can be done from the command line in seconds if uv or python are installed. See our contributing guide guide for more information.

When changes are made then push to your fork to your repo and git will give you a url to trigger a pull request into the master repo.

Testing other devices

• run compile and then select your board

Available boards:
[0]: ATtiny1616
[1]: adafruit_feather_nrf52840_sense
[2]: attiny85
[3]: bluepill
[4]: digix
[5]: esp01
[6]: esp32c2
[7]: esp32c3
[8]: esp32c6
[9]: esp32s3
[10]: esp32dev
[11]: esp32dev_i2s
[12]: esp32dev_idf44
[13]: esp32rmt_51
[14]: nano_every
[15]: rpipico
[16]: rpipico2
[17]: teensy30
[18]: teensy41
[19]: uno
[20]: uno_r4_wifi
[21]: xiaoblesense_adafruit
[22]: yun
[all]: All boards
Enter the number of the board you want to use: 0

Help and Support

If you need help with using the library, please consider visiting the Reddit community at https://reddit.com/r/FastLED. There are thousands of knowledgeable FastLED users in that group and a plethora of solutions in the post history.

If you are looking for documentation on how something in the library works, please see the Doxygen documentation online at http://fastled.io/docs.

If you run into bugs with the library, or if you'd like to request support for a particular platform or LED chipset, please submit an issue at http://fastled.io/issues.

Supported LED Chipsets

Here's a list of all the LED chipsets are supported. More details on the LED chipsets are included on our wiki page

• WS281x Clockless family
  • WS2811 (Old style 400khz & 800khz)
  • WS2812 (NeoPixel)
  • WS2812-V5B (250 uS reset)
  • WS2815
• APA102 / SK9822 / HD107s (turbo->40mhz) / Adafruit DotStars (SPI)
• HD107s, same thing as the APA102, but runs at turbo 40 Mhz
• SmartMatrix panels - needs the SmartMatrix library (https://github.com/pixelmatix/SmartMatrix)
• TM1809/4 - 3 wire chipset, cheaply available on aliexpress.com
• TM1803 - 3 wire chipset, sold by RadioShack
• UCS1903 - another 3-wire LED chipset, cheap
• GW6205 - another 3-wire LED chipset
• SM16824E - another clockless 3 wire.
• LPD8806 - SPI-based chipset, very high speed
• WS2801 - SPI-based chipset, cheap and widely available
• SM16716 - SPI-based chipset
• APA102 - SPI-based chipset
  • APA102HD - Same as APA102 but with a high-definition gamma correction function applied at the driver level.
• P9813 - aka Cool Neon's Total Control Lighting
• DMX - send rgb data out over DMX using Arduino DMX libraries
• LPD6803 - SPI-based chipset, chip CMODE pin must be set to 1 (inside oscillator mode)

APA102 and the 'High Definition' Mode in FastLED

FastLED features driver-level gamma correction for the APA102 and SK9822 chipsets, using our "pseudo-13-bit mixing" algorithm.

Read about it here: https://github.com/FastLED/FastLED/blob/master/APA102.md

Enable it like by using the APA102HD type. Example:

#define LED_TYPE APA102HD  // "HD" suffix for APA102 family enables hardware gamma correction
void setup() {
  FastLED.addLeds<LED_TYPE, DATA_PIN, CLOCK_PIN, RGB>(leds_hd, NUM_LEDS);
}

Check out thr rust port of this algorithm:

https://docs.rs/apa102-spi/latest/apa102_spi/

Getting Started

Arduino IDE / PlatformIO Dual Repo

We've created a custom repo you can try to start your projects. This repo is designed to be used with VSCode + PlatformIO but is also backwards compatible with the Arduino IDE.

PlatformIO is an extension to VSCode and is generally viewed as a much better experience than the Arduino IDE. You get auto completion tools like intellisense and CoPilot and the ability to install tools like crash decoding. Anything you can do in Arduino IDE you can do with PlatformIO.

Get started here:

https://github.com/FastLED/PlatformIO-Starter

ArduinoIDE

When running the Arduino IDE you need to do the additional installation step of installing FastLED in the global Arduino IDE package manager.

Install the library using either the .zip file from the latest release or by searching for "FastLED" in the libraries manager of the Arduino IDE. See the Arduino documentation on how to install libraries for more information.

Porting FastLED to a new platform

Information on porting FastLED can be found in the file PORTING.md.

What about that name?

Wait, what happened to FastSPI_LED and FastSPI_LED2? The library was initially named FastSPI_LED because it was focused on very fast and efficient SPI access. However, since then, the library has expanded to support a number of LED chipsets that don't use SPI, as well as a number of math and utility functions for LED processing across the board. We decided that the name FastLED more accurately represents the totality of what the library provides, everything fast, for LEDs.

For more information

Check out the official site http://fastled.io for links to documentation, issues, and news.

Daniel Garcia, Founder of FastLED

In Memory of Daniel Garcia Daniel Garcia, the brilliant founder of FastLED, tragically passed away in September 2019 in the Conception dive boat fire alongside his partner, Yulia. This heartbreaking loss was felt deeply by the maker and developer community, where Daniel's contributions had left an indelible mark.

Daniel was more than just a talented programmer; he was a passionate innovator who transformed the way creators interacted with LED technology. His work on FastLED brought high-performance LED control to countless projects, empowering developers to craft breathtaking installations.

In his personal life, Daniel was known for his kindness and creativity. His pride in FastLED and the vibrant community it fostered was a testament to his dedication to open-source development and his commitment to helping others bring light into the world.

While Daniel is no longer with us, his legacy continues through the FastLED library and the countless makers who use it. The community he built serves as a living tribute to his ingenuity, generosity, and the joy he found in sharing his work with the world.

About the Current Contributor

Zach Vorhies, the current main contributor to FastLED, briefly worked with Dan in 2014 in San Francisco and was an avid user of the FastLED library for over 13 years. After Daniel Garcia’s untimely passing, Zach stepped up to ensure FastLED’s continued growth and development.

Zach has this to say about FastLED:

"The true power of FastLED lies in its ability to transform programmers into LED artists. Free space becomes their canvas; bending light is their medium. FastLED is a collective effort by programmers who want to manifest the world that science fiction writers promised us. -- To contribute code to FastLED is to leave behind a piece of something immortal."

Contributing

See our easy to use guide here:

https://github.com/FastLED/FastLED/blob/master/CONTRIBUTING.md

To stay updated on the latest feature releases, please click the Watch button in the upper right