Version: 2.1.0
Release Date: 2013-11-11
www.pololu.com
This is a library for the Arduino for controlling these addressable RGB LED strips from Pololu:
- Addressable RGB 30-LED Strip, 5V, 1m
- Addressable RGB 60-LED Strip, 5V, 2m
- Addressable RGB 150-LED Strip, 5V, 5m
This library does not support the older low-speed LED strips. If you want to control those, we recommend using version 1.2.0, which can work with either the high-speed or low-speed versions.
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.
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.
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.
The addressable RGB LED strips can be purchased on Pololu’s website using the links above.
The LED strip’s data 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.
The easiest way to learn this library is to take a look at the example code we provide.
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.
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.
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.
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 8 microseconds (which the Arduino has by default), 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. To turn on the interruptFriendly option, add this line to your setup() function:
PololuLedStripBase::interruptFriendly = true;
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.
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
colorsparameter should be a pointer to an array ofrgb_colorstructs in RAM. Thecountparameter 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,countshould be equal to or greater than the number of LEDs in the strip. Ifcountis 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.
static bool interruptFriendly;- This option defaults to
false. Setting this totruechanges the behavior of thewritefunction, making it enable interrupts after each color is sent, about every 36 microseconds. See the discussion above.
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.
- 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.