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.

Changes

RevisionDateWhoCommit message
26:c3193bc73cff 2017-11-01 DavidEGrayson Make it be a compile-time error if GPIO_IP_WITHOUT_BRR is set. default tip
25:d72818ba17cc 2016-11-03 DavidEGrayson Change the reset signal from 24 us to 80 us to support the SK6812.
24:5c01a6fa1556 2016-09-09 DavidEGrayson Added a comment about the STM32F303K8.;
23:881d93b8749a 2016-09-08 DavidEGrayson Added a comment.;
22:5368af3ff07d 2016-09-08 DavidEGrayson Updated the mbed library and fixed an incorrect assembly instruction.
21:87fd6273e0ff 2013-11-26 DavidEGrayson fixed a comment
20:656bbcb64e3b 2013-11-13 DavidEGrayson Swapped the order of red and green so it will work with the new WS2812B strips.
19:46d7ab0ba3e7 2013-10-09 DavidEGrayson Changed the timing so that this library only supports the high-speed strips now.
18:34ba573573df 2013-03-01 DavidEGrayson A link in the docs didn't work, so I removed it.
17:91fb934a2166 2013-03-01 DavidEGrayson Not sure.
16:eaed541b08b0 2013-03-01 DavidEGrayson Fine tuned the fudge factors for the M3 at 96 MHz again. I'm not sure why they were not well tuned.
15:d69eebdee025 2013-03-01 DavidEGrayson Cleaned up calculateDelays more. The library might be done now.
14:672baf3cf941 2013-03-01 DavidEGrayson Cleaned up calculateDelays and made it work on the M0 48MHz again.
13:9c72841ec45e 2013-03-01 DavidEGrayson The code is working and I tuned the timings to try to be pretty good on the M3.
12:b6df8ac053c8 2013-03-01 DavidEGrayson Introduced the delay_fudges array. The code still works for the M0.
11:e00ba70ac54c 2013-03-01 DavidEGrayson Simplified the pushing and popping of LR.
10:f1bb84b97788 2013-03-01 DavidEGrayson Saved one cycle per bit by shifting the delays to the left in C.
9:6ffb85d69eaf 2013-03-01 DavidEGrayson Successfully transmitted colors on the M0.
8:1578776ceac5 2013-03-01 DavidEGrayson Changed the registers so that the push and pop commands can work on the Cortex M0 (LPC 11U24). There are still more things to fix though.
7:9a088f042ee0 2013-03-01 DavidEGrayson Things are still working well.
6:9d0530b7dae2 2013-03-01 DavidEGrayson Successfully read the delay amount from a table.
5:690fdfb595de 2013-03-01 DavidEGrayson It looks like the code is transmitting the right number of bits now.
4:d3b60bd43811 2013-02-28 DavidEGrayson Proof of the concept that we can achieve variable delays by jumping into a particular portion of a large subroutine with noops.
3:809dae64a994 2013-02-27 DavidEGrayson Not sure
2:425281517d59 2013-02-27 DavidEGrayson Not sure
1:102307d9b701 2013-02-27 DavidEGrayson Initial commit.;
0:06475317f283 2013-02-27 DavidEGrayson Still working;