Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Arduino library for addressable RGB LED strips from Pololu
Arduino C++
tag: 1.1.0

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
PololuLedStrip
LICENSE.txt
README.textile

README.textile

Arduino library for addressable RGB LED strips from Pololu

Version: 1.1.0
Release Date: 2012-12-17
www.pololu.com

Summary

This is a library for the Arduino for controlling the addressable RGB LED strips from Pololu:

It 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 1.0 IDE 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 data input connector for the LED strip is transparent and has two male pins inside. When looking into the connector and orienting it with the flattened side on the bottom, the left pin is the signal wire and the right pin is ground. The LED strip’s ground will need to be connected to one of the Arduino’s GND pins, and the LED strip’s signal 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.

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 2 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 48 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;

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 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 48 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

  • 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.
Something went wrong with that request. Please try again.