FastLED Library
If looking to boost your NeoPixel prowess, you may find everything you need in the FastLED library. It’s an alternative to the Adafruit_NeoPixel library, providing more advanced features like HSV color support, nondestructive brightness setting and high-speed mathematical operations. (It works with other LED types too, such as DotStars!)
FastLED works altogether differently; it’s not a drop-in replacement for Adafruit_NeoPixel, and existing sketches will require some rewriting.
Note: FastLED currently works only with RGB NeoPixels; RGBW pixels are not yet supported. At all. You will get incorrect and unpredictable colors.
We don’t write or maintain FastLED, and can’t provide software troubleshooting advice. If requesting help with a FastLED NeoPixel project in the forums, we’ll usually ask that you try one of the known-working Adafruit_NeoPixel example sketches to narrow down whether it’s a hardware or software issue.
Unfortunately the NeoPixel and Servo libraries don’t play nice together; one is dependent on periodically disabling interrupts, the other absolutely requires interrupts. There are a couple of options here:
- Use a dedicated servo control shield or breakout board, offloading that task from the processor so interrupts are a non-issue.
- Use a hardware-PWM-based servo library rather than the stock Arduino Servo library. This can provide rock-steady servo timing without interrupts, but can only control a very limited number of servos (2-3), and only on very specific pins.
Just like servos, the infrared library uses software interrupts to poll the IR LED, while the standard NeoPixel library blocks interrupts while NeoPixel are being updated.
If you don't constantly update the NeoPixel, IR will work in between updates, but if you update them all the time, you will need to use another library and a microcontroller more capable than an Uno or Mega. Ideally one with DMA so that NeoPixels don't take up any CPU cycles.
Marc MERLIN explains how to this depending on what chip you have (Teensy, ESP8266 or ESP32):
http://marc.merlins.org/perso/arduino/post_2017-04-03_Arduino-328P-Uno-Teensy3_1-ESP8266-ESP32-IR-and-Neopixels.html
NeoPixels receive data from a fixed-frequency 800 KHz datastream (except for “V1” Flora pixels, which use 400 KHz). Each bit of data therefore requires 1/800,000 sec — 1.25 microseconds. One pixel requires 24 bits (8 bits each for red, green blue) — 30 microseconds. After the last pixel’s worth of data is issued, the stream must stop for at least 50 microseconds for the new colors to “latch.”
For a strip of 100 pixels, that’s (100 * 30) + 50, or 3,050 microseconds. 1,000,000 / 3,050 = 328 updates per second, approximately.
However…
That’s only the time needed to push the bits down the wire. The actual refresh rate will be something less than this, and can’t be estimated as a single number for all cases. It takes time to process each “frame” of animation. How much time depends on the complexity of the math and the efficiency of the code (for example, floating-point calculations can be relatively slow). The formula above gives a maximum theoretical rate, but that’s just a starting point. Reality in some cases could fall an order of magnitude (or more) below this.
For exploratory benchmarking, you can always write code as if a large number of pixels were present, and time the result. The extra output bits will simply be ignored by the strip (or you can even test with no NeoPixels connected at all).
Because NeoPixels use a fixed-frequency clock, options are limited. You can’t switch out for a faster microcontroller and expect substantially different results.
One option is to use a different LED type, such as our DotStar or LPD8806 strips, or WS2801 pixels. These can be driven at higher data rates, though they do have some other tradeoffs with respect to NeoPixels (cost, color resolution and/or pixel density).
Another is to develop your own code on a more capable microcontroller or an FPGA that drives multiple NeoPixel strips in parallel. One such project — OctoWS2811 for the Teensy 3 microcontroller — is shown later. This sort of thing is a complex undertaking and not recommended for beginners. And even among more experienced programmers, there’s often an unreasonable over-emphasis on data rates when the real bottlenecks lie elsewhere…don’t dwell on this too much unless you can confirm it’s the root of the problem.
We currently only offer an Arduino library. See the links later for other devices. For anything beyond this, if considering writing your own library, understand that some processors are better suited to the task than others. Read through the timing requirements shown below and determine if the chip in question can synthesize a signal meeting those specifications. An 8 MHz AVR can just barely keep up…anything slower may have trouble, though some hardware-specific hacks (like clever use of SPI) might make it possible. In many cases, assembly language is required.
This guide focuses mostly on Arduino and similar microcontroller boards where NeoPixel support is most robust. Raspberry Pi control of NeoPixels is possible, but requires special libraries and/or is limited to specific pins…it’s all a bit beyond the scope of this guide. The wiring and power guidance here is valid for any device though.
We tend toward DotStar LEDs in Raspberry Pi projects, as in this Raspberry Pi light painter.
DMA NeoPixels for ARM Cortex-M0 Boards
If you’re using a recent “M0” development board such as the Adafruit Feather M0, Circuit Playground Express or Arduino Zero, an alternate NeoPixel library exploits these devices’ direct memory access (DMA) feature to operate more smoothly. Advanced Arduino sketches can then use interrupts with impunity, and code that depends on the millis() or micros() functions will not lose time.
There’s a corresponding DMA version of the NeoMatrix library as well.
Plus a super potent 8-way concurrent NeoPixel DMA library. We offer a companion FeatherWing and breakout board to make connections and level-shifting easier!
Third-Party Libraries
In addition to the previously-mentioned FastLED library, NeoPixel-compatible libraries have been developed for devices beyond Arduino. Please keep in mind that Adafruit did not develop any of this code and can’t fix bugs or offer technical help. This is Wild West stuff.
- OctoWS2811: specifically for the PJRC Teensy 3.0 microcontroller board. Uses DMA to drive up to 8 NeoPixel strips concurrently with minimal processor load. Multiple boards can be cascaded for still larger displays.
- FadeCandy: also for Teensy 3.0. Doesn’t support as many pixels as OctoWS2811, but adds dithering and smooth interpolation for color purists.
- LEDscape: specifically for BeagleBone Black. Although the BeagleBone is a multitasking Linux system like the not-NeoPixel-compatible Raspberry Pi, this code exploits hardware features specific to the BeagleBone Black to drive hundreds of meters of NeoPixel strip with virtually no processor load.
- WS2812 LED Driver for Parallax Propeller.
- xCORE NeoPixel test code for the XMOS xCORE startKIT.
- light_ws2812: an alternate Arduino library for AVR and ARM microcontrollers.
NeoPixels have evolved through several generations:
- WS2811 is a driver chip separate from the RGB LED
- WS2812 integrated the driver and RGB LED in a single package
- WS2812B is a newer generation WS2812 — the color balance is slightly different and the data signal “latch” time is longer
- SK6812 is a “WS2812-compatible” part from other manufacturers — we’ve adopted these for most NeoPixel-branded products as they better tolerate different voltages.
On the original WS2811, chip, the data stream runs at half the speed. When the WS2812 came along, a lot of code and projects had already built up around the WS2811 name — so, for instance, you’ll see projects like “OctoWS2811” and others but they’ll really work with all of these!
Writing Your Own Library
The WS2812 datasheet explains the data transmission protocol. This is a self-clocking signal — there’s only one wire, not separate data and clock lines. “1” and “0” bits are indicated by varying the duty cycle of a fixed-frequency square wave.
Note that there’s nearly 25% “wiggle room” in the timing. So if your code can’t match the recommended times exactly, it’s usually okay, as long as it’s close.
There are three bytes of data for each pixel. These should be issued in green, red, blue order, with the most-significant bit first.
The data for pixel #0 (nearest the microcontroller) is issued first, then pixel #1, and so forth to the furthest pixel. This does not operate like a traditional shift register!
All the data for the whole run must be issued. You can’t address individual pixels in the middle of a run.
After all the color data is sent, the data line must be held low for a minimum of 300 microseconds for the new colors to “latch.”
You may want to dig through our Arduino library for insights. The timing-critial parts are written in AVR assembly language, but it’s extensively commented with C-like pseudocode.
Page last edited March 08, 2024
Text editor powered by tinymce.