FastLED Library Tutorial

A quick tutorial on working with the FastLED library, Arduino, and an addressable LED strand.

For a recent Critical Making assignment, I created a simple music visualizer using an Arduino board, a sound detector, and an LED strip. Check it out here.

To program the LEDs, I used the FastLED library, which allowed me to quickly program the entire chain of LEDs and add dynamic movement and radical colors to them. This post provides a quick tutorial on how to set up an LED strip and some of the basics of the library.

What is it?

“FastLED is a fast, efficient, easy-to-use Arduino library for programming addressable LED strips and pixels such as WS2810, WS2811, LPD8806, Neopixel and more. FastLED is used by thousands of developers, in countless art and hobby projects, and in numerous commercial products.

We build FastLED to help you get started faster, develop your code faster, and make your code run faster.”

– FASTLed

Hardware Setup

Before we start coding, let’s get our hardware setup. I chose to use an Arduino Uno R3 for this project, but the library supports numerous boards.

  • Connect the LED Data IN(Din) to one of the digital inputs (I chose 7) with a 300–500 Ω resistor.
  • Connect the ground from the board to the strip.
  • Add a 1000 µF electrolytic capacitor between ground and 5v. (Note, these are polarized, so ensure that the white striped side connects with the ground side)
  • Connect 5v from board to LED strip
  • I used a DC barrel plug to power my Arduino board.

Getting Started

To begin, install the FastLED library in the Arduino IDE. If you did this correctly, you should be able to include the library in your sketch by clicking sketch -> Include Library -> FastLED. This include adds numerous libraries, feel free to delete every line except:

#include <FastLED.h>

Next, we need to define some fixed global variables that help the library understand our hardware setup. Declare the pin position of our LED strip (7 in my case), the type of LED, and the number of LEDs in the strip. Finally, we create a block of data (array) representing each LED holding our color data.

//FIXED GLOBAL VARS
#define DATA_PIN 7  //Define led data pin in
#define LED_TYPE NEOPIXEL  //define type of led
#define NUM_LEDS 30  //num of leds in strip

struct CRGB leds[NUM_LEDS];  // Initialize LED array

Let’s look at our setup function next. Before we do anything, let’s set a delay of 2 seconds, to protect our LEDs from errors or power spikes on startup. Now we need to initialize our LEDs, using the global variable we already set.

void setup() {
  // put your setup code here, to run once:
  delay(2000); //for safe startup
  FastLED.addLeds<LED_TYPE, DATA_PIN>(leds, NUM_LEDS);
}

Light it Up

Let’s light things up! To get an LED to turn on, we need to do two things: tell the LED what color to show, then tell the strip to display it. Each LED is represented in the array, so to access the 7th LED, we would use leds[6] (Array’s initial value is always 0). FastLED has an immense color library built-in, meaning, we don’t need to use RGB values, and can use named colors instead! Let’s make the 7th pixel blue to begin.

void loop() {
leds[7] = CRGB::Blue;  //set the 7th LED to Blue
FastLED.show();       //start the leds
delay(50);
}

Now let’s make the whole strip blue. To achieve this, we use a for loop to iterate through the whole array of LEDs and set each one to the color blue.

void loop() {
for (int i = 0; i < NUM_LEDS; i++) {
  leds[i] = CRGB::Blue;  //set the all leds to blue
}
FastLED.show();       //start the leds
delay(50);
}

Blink

Let’s make the string blink now. To do this, we tell the string what color we want and for how long, and then we tell it to turn black for a specified amount of time. In this case, let’s have them turn teal for 1 second and then off for 1/2 second.

void loop() {
for (int i = 0; i < NUM_LEDS; i++) {
  leds[i] = CRGB::Teal;  //set the all leds to teal
}
FastLED.show();       //start the leds
delay(1000);          //Wait 1 sec

for (int i = 0; i < NUM_LEDS; i++) {
  leds[i] = CRGB::Black;  //set the all leds to Black (off)
}
FastLED.show();       //start the leds
delay(500);           //Wait 1/2 second
}

Movement

Flashing lights are cool and all, but let’s make things move around! For this example, let’s make a single pink dot travel from one side of the strip to the other. Each pixel turns on, then off, then the program moves onto the next pixel.
What happens if you adjust the delay time?

void loop() {
for (int i = 0; i < NUM_LEDS; i++) {
  leds[i] = CRGB::DeepPink;  //set the led to Pink
  FastLED.show();       //start the leds
  leds[i] = CRGB::Black;  //clear the led
  delay(50);          //Wait before moving to next let 
 }
}

Random Strobe

Let’s throw some chaos into the system! For this sketch we are going to light up a random pixel, using FastLED’s random8 function, which generates a random 8-bit number within our defined limit, we use the same function to assign it a random color value using the HSV colors instead of RGB.

void loop() {
  uint8_t color = random8();
  uint8_t num = random8(30);
  leds[num] = CHSV(color, 255, 255);  //set random led to random color
  FastLED.show();       //start the leds
  leds[num] = CRGB::Black;  //clear the led
  delay(5);          //Wait before moving to next led 
}

Gradient

Finally, let’s make a gradient rainbow, and then have the colors shift. To do this, we are going to use the CREGSet utility, which allows us to pre-define a group of pixels, and then assign them all a color without having to use a ‘for loop.’ Also, we employ the built-in fill_rainbow() function to generate a color gradient quickly. Finally, we alter the color by defining and iterating through the starting hue value of the rainbow. 

#include <FastLED.h>

//FIXED GLOBAL VARS
#define DATA_PIN 7  //Define led data pin in
#define LED_TYPE NEOPIXEL  //define type of led
#define NUM_LEDS 30  //num of leds in strip


CRGBArray<NUM_LEDS> leds;  //Define CRGBSET to be entire string, and clal it leds

void setup() {
  // put your setup code here, to run once:
  delay(2000); //for safe startup
  FastLED.addLeds<LED_TYPE, DATA_PIN>(leds, NUM_LEDS);
}

void loop() {
  static uint8_t hue=0;  //define hue variable
  leds.fill_rainbow(hue++); //fill all leds with rainbow, and 
    then iterate through the hue values moving the raindown 
    gradient.
  FastLED.delay(30); //control speed of change
}

This tutorial is just the beginning of what’s possible with this library, and a taste of how easy it is to make compelling LED programs with a simple setup. Hopefully, I’ll get around to writing some new sequences for a future post.

1 Comment

Comments are closed.