h1. Particle Spark library for addressable POLOLU RGB LED strips

Adaptation from Version: 3.2.0 of Pololu-led-strip-arduino By pr0duc3r Release Date: 2015-09-25

h2. Summary

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

• "Addressable RGB 30-LED Strip, 5V, 1m (WS2812B)":http://www.pololu.com/catalog/product/2546
• "Addressable RGB 60-LED Strip, 5V, 2m (WS2812B)":http://www.pololu.com/catalog/product/2547
• "Addressable RGB 150-LED Strip, 5V, 5m (WS2812B)":http://www.pololu.com/catalog/product/2548
• "Addressable RGB 60-LED Strip, 5V, 1m (WS2812B)":http://www.pololu.com/catalog/product/2549
• "Addressable RGB 120-LED Strip, 5V, 2m (WS2812B)":http://www.pololu.com/catalog/product/2550
• "Addressable High-Density RGB 72-LED Strip, 5V, 0.5m (WS2812B)":http://www.pololu.com/product/2551
• "Addressable Through-Hole 5mm RGB LED with Diffused Lens, WS2811 Driver (10-Pack)":http://www.pololu.com/product/2535
• "Addressable Through-Hole 8mm RGB LED with Diffused Lens, WS2811 Driver (10-Pack)":http://www.pololu.com/product/2536
• "Adafruit 16 WS2812 LED NeoPixel Ring":http://www.pololu.com/product/2537
• "Adafruit 24 WS2812 LED NeoPixel Ring":http://www.pololu.com/product/2538
• "Adafruit 15 WS2812 LED NeoPixel 1/4-Ring":http://www.pololu.com/product/2539
• "Adafruit 5×8 WS2812 LED NeoPixel Shield for Arduino":http://www.pololu.com/product/2772
• "Addressable RGB 30-LED Strip, 5V, 1m (High-Speed TM1804)":http://www.pololu.com/catalog/product/2543
• "Addressable RGB 60-LED Strip, 5V, 2m (High-Speed TM1804)":http://www.pololu.com/catalog/product/2544
• "Addressable RGB 150-LED Strip, 5V, 5m (High-Speed TM1804)":http://www.pololu.com/catalog/product/2545

This library is optimized for the WS2812B, so it transmits colors in green-red-blue order.

If you have a WS2811 LED or a high-speed TM1804 LED strip, please note that its red and green channels are swapped relative to the WS2812B, so you will need to swap those channels in your code. You might prefer to use "version 2.1.0":https://github.com/pololu/pololu-led-strip-arduino/releases/tag/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":https://github.com/pololu/pololu-led-strip-arduino/releases/tag/1.2.0, which runs slower but can work with any of the low-speed TM1804 LED strips, high-speed TM1804 strips, WS2812B strips, or WS2811 LEDs.

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.

h2. 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 8 MHz, 16 MHz, or 20 MHz. This includes the "A-Star 32U4 boards":http://www.pololu.com/category/149/a-star-programmable-controllers, the "Arduino Uno":http://www.pololu.com/catalog/product/2191, the older Arduino Duemilanovae, the "Baby Orangutan B-328":http://www.pololu.com/catalog/product/1220, the "Orangutan SV-328":http://www.pololu.com/catalog/product/1227, the "Arduino Leonardo":http://www.pololu.com/catalog/product/2192, the "Arduino Micro":http://www.pololu.com/product/2188, and the "Arduino Mega":http://www.pololu.com/catalog/product/1699. Not all pins on the Arduino Mega are supported (see below).

This library also supports the "Arduino Due":http://www.pololu.com/catalog/product/2193, which is based on the ATSAM3X8E.

h2. Getting Started

h3. Software

Download the "pololu-led-strip-arduino archive from github":https://github.com/pololu/pololu-led-strip-arduino, 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.

h3. 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":http://www.pololu.com/catalog/category/67, 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.

h2. Example Programs

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

h3. 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.

h3. 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.

h3. 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.

h2. 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:

pre. 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.

h2. Library Reference

h3. 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.

h3. PololuLedStrip<pin>

The libary defines a template class named @PololuLedStrip@. 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.

h3. 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.

h2. 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.

h2. Version History

• 3.2.0 (2014-08-27): Added support for AVRs running at 8 MHz (thanks odewdney).
• 3.1.2 (2014-06-10): Fixed a bug in the HSV-to-RGB conversion in the LedStripRainbow example.
• 3.1.1 (2014-01-07): Changed the examples to use @uint16_t@ instead of @byte@ for @i@, making it easier to expand them beyond 254 LEDs.
• 3.1.0 (2013-12-19): Added the LedStripXmas example.
• 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.