Arduino library for addressable RGB LED strips from Pololu

Version: 3.0.0
Release Date: 2013-12-05
www.pololu.com

Summary

This is a library for the Arduino for controlling these LED strips from Pololu based on the WS2812B:

This library also supports the older high-speed TM1804 LED strips, which are listed below. However, the red and green channels on the TM1804 are swapped relative to the WS2812B, so you will need to swap those channels in your code.

If you have the high-speed TM1804 LED strips, you might prefer to use version 2.1.0 of the library, which does not require you to swap red and green in your code.

This version of the library does not support the older low-speed TM1804 LED strips. If you want to control those, we recommend using version 1.2.0, which runs slower but can work with any of the low-speed TM1804 LED strips, high-speed TM1804 strips, or WS2812B strips.

This library allows complete control over the color of an arbitrary number of LED strips with an arbitrary number of LEDs. Each LED can be individually controlled, and LED strips can be chained together.

Supported Platforms

This library and the examples are designed to work with the Arduino IDE versions 1.0 and 1.5 and probably will not work with earlier versions.

This library currently supports any board based on the ATmega168, ATmega328P, ATmega32U4, or ATmega2560 which runs at 16 MHz or 20 MHz. This includes the Arduino Uno, the older Arduino Duemilanovae, the Baby Orangutan B-328, the Orangutan SV-328, the Arduino Leonardo and the Arduino Mega. Not all pins on the Arduino Mega are supported (see below).

This library also supports the Arduino Due, which is based on the ATSAM3X8E.

Getting Started

Software

Download the pololu-led-strip-arduino archive from github, decompress it, and drag the “PololuLedStrip” folder into your arduino-x.x/libraries directory. Then restart the Arduino IDE so it can detect the new library.

Hardware

The addressable RGB LED strips can be purchased on Pololu’s website using the links above.

The LED strip’s input connector has two pins that should be connected to the Arduino. The LED strip’s ground will need to be connected to one of the Arduino’s GND pins, and the LED strip’s signal input line will be need to be connected to one of the Arduino’s I/O lines. Our example sketches assume the signal line is connected to pin 12. These connections can be made using two Male-Female Premium Jumper Wires, with the female ends plugging into the LED strip.

You will also need to connect a suitable power supply to the LED strip using one of the power connectors. The power supply must be at the right voltage and provide enough current to meet the LED strip’s requirements.

Example Programs

The easiest way to learn this library is to take a look at the example code we provide.

LedStripGradient

This example code sketch lights up the LED strip with a moving gradient pattern. You can open this example sketch by selecting File→Examples→PololuLedStrip→LedStripGradient. Click the “Upload” button to load it onto your board.

LedStripRainbow

This example is like LedStripGradient, but makes a rainbow pattern instead. You can open this example sketch by selecting File→Examples→PololuLedStrip→LedStripRainbow. Click the “Upload” button to load it onto your board.

LedStripColorTester

This example code sketch allows you to type colors into the Serial Monitor and see them on the LED strip. You can open this example by selecting File→Examples→PololuLedStrip→LedStripColorTester. Click the “Upload” button to load it onto your board. See the comments in the code for more information on how to use it.

Timing Details

This library takes about 1.1 ms to update 30 LEDs (1 meter). The LED strips use a high speed one-wire protocol with relatively strict timing requirements, so this library disables interrupts to ensure reliable color transmission. Unfortunately, disabling the interrupts causes problems in other libraries that uses interrupts, such as the Serial library and the functions like millis() that keep track of time.

This library provides an interruptFriendly option that can let it coexist with interrupt-based libraries. When this option is enabled, the library will temporarily enable interrupts after each color is sent, about every 36 microseconds. If you can keep all of your interrupts short enough, then this option should allow this library to work in conjunction with your interrupt-based libraries. However, if you have an interrupt enabled that takes longer than about 5 microseconds for the WS2812B or 8 microseconds for the TM1804, then this interrupt will sometimes cause an extra long low pulse to emitted, which will be interpreted by the LED strip as a reset command. This can cause visible flickering in the LED strip. By default, many common Arduinos such as the Arduino UNO have an interrupt that runs every millisecond and takes longer than 8 microseconds, so this option will give bad results unless you disable that interrupt. To turn on the interruptFriendly option, add this line to your setup() function:

 PololuLedStripBase::interruptFriendly = true;

Because the library disables interrupts by default, it can cause the timekeeping functions of your Arduino to miss ticks. As a result, the Arduino’s time, which can be accessed from functions like millis(), will appear to be running slower than usual. In our demo code, we get around this by adding a 10 millisecond delay at the end of the loop function; this ensures that the Arduino will only spend a minority of its time updating the LED strip and therefore limits how much the timekeeping will be affected.

Library Reference

rgb_color

The library defines a type named rgb_color which can be used to represent colors. The type is defined like this:

typedef struct rgb_color
{
  unsigned char red, green, blue;
} rgb_color;

The fields red, green, and blue are numbers between 0 and 255 and represent the brightness of the red, green, and blue color components respectively.

PololuLedStrip<pin>

The libary defines a template class named PololuLedStrip<pin>. The pin template parameter is an unsigned char and should be the number of the Arduino pin that the LED strip’s data input line is connected to. For ATmega2560-based boards such as the Arduino Mega, only the following pins are usable: 0–5, 10–13, 18–41, and 50–61 (ports A through G). This template class inherits from the abstract class PololuLedStripBase, which is useful if you want to have pointers to LED strip objects.

This class has no constructor except the default one. This class has one function:

void write(rgb_color * colors, unsigned int count): Writes the specified colors to the LED strip. The colors parameter should be a pointer to an array of rgb_color structs in RAM. The count parameter is the number of colors to write. The first color in the array will be written to the LED closest to the data input connector. To update all the LEDs in the LED strip, count should be equal to or greater than the number of LEDs in the strip. If count is less than the number of LEDs in the strip, then some LEDs near the end of the strip will not be updated. This function disables interrupts temporarily. This function pauses for over 10 us at the end before returning to allow the colors to take effect.

PololuLedStripBase

static bool interruptFriendly;: This option defaults to false. Setting this to true changes the behavior of the write function, making it enable interrupts after each color is sent, about every 36 microseconds. See the discussion above.

Chaining LED Strips together

No special code is required to chain LED strips together. An X-meter LED strip chained to a Y-meter LED strip can be controlled in exactly the same way as a single (X+Y)-meter LED strip.

Version History

3.0.0 (2013-11-20): Switched the red and the green channels and increased the reset time so that this library will work nicely with the new WS2812 and WS2182B LED strips. The high-speed TM1804 LED strips still work if you switch red and green in your code.
2.1.0 (2013-11-11): Added the LedStripRainbow example.
2.0.0 (2013-10-07): Dropped support for the older, slower LED strips in order to make the library faster.
1.2.0 (2013-10-07): Changed the timing so that this library will work the new high-speed strips but also keep working with the old low-speed strips.
1.1.0 (2012-12-17): Added support for ATmega32U4-based boards such as the Arduino Leonardo. Added support for ARM-based boards such as the Arduino Due.
1.0.0 (2012-03-09): Original release.

sashkosnail / pololu-led-strip-arduino