David Grayson / PololuLedStrip

This library lets you control the addressable RGB LED strips from Pololu Robotics & Electronics.

Dependents:   WoYaoChengGOng V2-WoYaoChengGOng STM32_MagneticLight tape_Led_Sample ... more

Summary

This is a library for the mbed that allows you to control these addressable RGB LED products from Pololu:

This library is optimized for the SK6812 and 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 the version of the library from October 2013, which does not require you to swap red and green in your code.

If you need to control the older, low-speed LED strips (items #2540, #2541, and #2542), you will need to use the version of this library from March 2013.

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 should also work with any other LED strip based on the SK6812, WS281x, or TM1804.

Supported Platforms

This library has been tested on the mbed NXP LPC1768 (Cortex-M3 at 96 MHz), the mbed NXP LPC11U24 (Cortex-M0 at 48 MHz), and the NUCLEO-F303K8 (Cortex-M4 at 72 MHz). It will probably work on many other boards without modification.

This library does not work on chips families such as the STM32F4 where there is a single register for setting and clearing the value of an output pin. The library checks for the GPIO_IP_WITHOUT_BRR preprocessor macro and triggers a compile-time error if that macro is set.

Getting Started

Software

Here are two example programs that show how to use the library:

Import programLedStripRainbow

This is an example program for the PololuLedStrip library. It generates a simple moving rainbow pattern.

Last commit 01 Nov 2017 by David Grayson

Import programLedStripGradient

This is an example program for the PololuLedStrip library. It generates a simple moving gradient pattern.

Last commit 01 Nov 2017 by David Grayson

As a first step, you should compile and upload one of these to the mbed. When the program runs, the mbed should output color data on pin p8 dozens of times per second. The expected signal is documented on the Pololu website. The example programs only send colors for 60 LEDs, but they can easily be changed to send more for a longer strip.

Hardware

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 mbed’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 programs assume the signal line is connected to p8. These connections can be made using two Male-Female Premium Jumper Wires, with the female ends plugging into the LED strip and the male ends plugged into a breadboard that houses the mbed.

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.

If everything works properly, you will see a moving pattern of colors on the LED strip.

Timing Details

This library takes about 1.3 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 could cause problems in other libraries that uses interrupts.

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 45 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 too long, 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 the beginning of your main() function:

PololuLedStrip::interruptFriendly = true;

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.

PololuLedStrip.h@26:c3193bc73cff, 2017-11-01 (annotated)

Committer:
DavidEGrayson
Date:
Wed Nov 01 23:11:49 2017 +0000
Revision:
26:c3193bc73cff
Parent:
19:46d7ab0ba3e7 
Make it be a compile-time error if GPIO_IP_WITHOUT_BRR is set.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
DavidEGrayson 0:06475317f283 1 #include "mbed.h"
DavidEGrayson 0:06475317f283 2
DavidEGrayson 0:06475317f283 3 #ifndef _POLOLU_LED_STRIP_H
DavidEGrayson 0:06475317f283 4 #define _POLOLU_LED_STRIP_H
DavidEGrayson 0:06475317f283 5
DavidEGrayson 0:06475317f283 6 namespace Pololu
DavidEGrayson 0:06475317f283 7 {
DavidEGrayson 0:06475317f283 8 #ifndef _POLOLU_RGB_COLOR
DavidEGrayson 0:06475317f283 9 #define _POLOLU_RGB_COLOR
DavidEGrayson 1:102307d9b701 10
DavidEGrayson 1:102307d9b701 11 /** Represents an RGB color. */
DavidEGrayson 0:06475317f283 12 typedef struct rgb_color
DavidEGrayson 0:06475317f283 13 {
DavidEGrayson 1:102307d9b701 14 uint8_t red; /*!< A number between 0 and 255 that represents the brightness of the red component. */
DavidEGrayson 1:102307d9b701 15 uint8_t green; /*!< A number between 0 and 255 that represents the brightness of the green component. */
DavidEGrayson 1:102307d9b701 16 uint8_t blue; /*!< A number between 0 and 255 that represents the brightness of the blue component. */
DavidEGrayson 0:06475317f283 17 } rgb_color;
DavidEGrayson 0:06475317f283 18 #endif
DavidEGrayson 0:06475317f283 19
DavidEGrayson 0:06475317f283 20 extern "C" int led_strip_write_color(rgb_color *, volatile uint32_t * set, volatile uint32_t * clear, uint32_t mask);
DavidEGrayson 0:06475317f283 21
DavidEGrayson 18:34ba573573df 22 /** This class lets you control the addressable RGB LED strips from Pololu</a>,
DavidEGrayson 1:102307d9b701 23 or any other LED strip based on the TM1804 chip. */
DavidEGrayson 0:06475317f283 24 class PololuLedStrip
DavidEGrayson 0:06475317f283 25 {
DavidEGrayson 0:06475317f283 26 gpio_t gpio;
DavidEGrayson 1:102307d9b701 27
DavidEGrayson 0:06475317f283 28 public:
DavidEGrayson 1:102307d9b701 29
DavidEGrayson 1:102307d9b701 30 /** This constructor lets you make an led strip object by specifying the pin name.
DavidEGrayson 1:102307d9b701 31 There are no restrictions on what pin you can choose.
DavidEGrayson 1:102307d9b701 32
DavidEGrayson 1:102307d9b701 33 Example:
DavidEGrayson 1:102307d9b701 34 @code
DavidEGrayson 1:102307d9b701 35 PololuLedStrip ledStrip(p8);
DavidEGrayson 1:102307d9b701 36 @endcode
DavidEGrayson 1:102307d9b701 37 */
DavidEGrayson 0:06475317f283 38 PololuLedStrip(PinName pin);
DavidEGrayson 1:102307d9b701 39
DavidEGrayson 1:102307d9b701 40 /** Writes the specified series of colors to the LED strip.
DavidEGrayson 1:102307d9b701 41 @param colors should be a pointer to an array of rgb_color structs.
DavidEGrayson 1:102307d9b701 42 @param count should be the number of colors to write.
DavidEGrayson 1:102307d9b701 43
DavidEGrayson 1:102307d9b701 44 The first color in the array will be written to the LED closest to the data input connector.
DavidEGrayson 1:102307d9b701 45 To update all the LEDs in the LED strip, count should be equal to or greater than the number of LEDs in the strip.
DavidEGrayson 1:102307d9b701 46 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.
DavidEGrayson 1:102307d9b701 47
DavidEGrayson 19:46d7ab0ba3e7 48 The colors are sent in series and each color takes about 45 microseconds to send.
DavidEGrayson 1:102307d9b701 49 This function disables interrupts temporarily while it is running.
DavidEGrayson 1:102307d9b701 50 This function waits for over 10 us at the end before returning to allow the colors to take effect.
DavidEGrayson 1:102307d9b701 51 */
DavidEGrayson 0:06475317f283 52 void write(rgb_color * colors, unsigned int count);
DavidEGrayson 7:9a088f042ee0 53
DavidEGrayson 1:102307d9b701 54 /** This option defaults to <code>false</code>.
DavidEGrayson 1:102307d9b701 55 Setting this to true changes the behavior of the write function, making it enable interrupts
DavidEGrayson 1:102307d9b701 56 after each color is sent, about every 60 microseconds.
DavidEGrayson 1:102307d9b701 57 This allows your program to respond to interrupts faster, but makes it possible for an interrupt
DavidEGrayson 1:102307d9b701 58 that takes longer than 8 microseconds to screw up the transmission of colors to the LED strip.
DavidEGrayson 1:102307d9b701 59
DavidEGrayson 1:102307d9b701 60 Example:
DavidEGrayson 1:102307d9b701 61 @code
DavidEGrayson 1:102307d9b701 62 PololuLedStrip::interruptFriendly = true;
DavidEGrayson 1:102307d9b701 63 @endcode
DavidEGrayson 1:102307d9b701 64 */
DavidEGrayson 0:06475317f283 65 static bool interruptFriendly;
DavidEGrayson 7:9a088f042ee0 66
DavidEGrayson 7:9a088f042ee0 67 static void calculateDelays();
DavidEGrayson 0:06475317f283 68 };
DavidEGrayson 0:06475317f283 69 }
DavidEGrayson 0:06475317f283 70
DavidEGrayson 0:06475317f283 71 using namespace Pololu;
DavidEGrayson 0:06475317f283 72
DavidEGrayson 0:06475317f283 73 #endif