Neopixel Uberguide
Neopixel Uberguide
Neopixel Uberguide
Guide Contents 2
The Magic of NeoPixels 5
Important Things to Know About NeoPixels in General 5
Form Factors 7
NeoPixel Strips 8
RGB NeoPixel Strips 8
Mini Skinny RGB NeoPixel Strips 10
RGBW NeoPixel Strips 11
Finer Details About NeoPixel Strips 11
NeoPixel Rings 13
NeoPixel Ring Product Selector (http://adafru.it/3042) 13
Finer Details About NeoPixel Rings 15
NeoPixel Matrices 17
Rigid 8x8 NeoPixel Matrices 17
NeoPixel Matrix Product Selector (http://adafru.it/3052) 17
Flexible NeoPixel Matrices 18
Finer Details About NeoPixel Matrices 19
We also have a few special-purpose matrices on the NeoPixel Shields page! 20
NeoPixel Shields 21
NeoPixel Shield for Arduino 21
NeoPixel Shield Product Selector (http://adafru.it/lCw) 21
NeoPixel FeatherWing 22
Pimoroni Unicorn Hat 23
Particle/Spark NeoPixel Ring Kit 24
Other NeoPixel Shapes 25
NeoPixel Stick 25
NeoPixel Stick Product Selector (http://adafru.it/3039) 25
NeoPixel Jewels 25
NeoPixel Jewel Product Selector (http://adafru.it/3047) 26
1/4 60 NeoPixel Ring 26
NeoPixel Ring Product Selector (http://adafru.it/3042) 26
Individual NeoPixels 28
The WS2812 Integrated Light Source or NeoPixel in Adafruit parlance is the latest advance in the
quest for a simple, scalable and affordable full-color LED. Red, green and blue LEDs are integrated
alongside a driver chip into a tiny surface-mount package controlled through a single wire. They can be
used individually, chained into longer strings or assembled into still more interesting form-factors.
We know youre eager to get startedbut If this is your first time using NeoPixels, please at least read the
Best Practices page before connecting anything!
Not recommended. The refresh rate is relatively low (about 400 Hz), and color displays in fast motion may
appear speckled. They look fine in stationary displays though (signs, decorations, jewelry, etc.). For
POV use, DotStar strips (http://adafru.it/kDg) will look much better (they have about a 20 KHz refresh
rate).
Definitely! The slower movement used for photographic light painting doesnt call attention to the limited
refresh rate; the results look great (http://adafru.it/jTb), especially with a light diffuser.
Theres no inherent limit in the maximum length of a NeoPixel chain, but eventually youll encounter any
of various practical limits:
1. RAM: NeoPixels require some RAM from the host microcontroller; more pixels = more RAM. Its
only a few bytes each, but as most microcontrollers are pretty resource-constrained, this becomes a
very real consideration for large projects.
2. Power: each NeoPixel draws a little bit of current; more pixels = more power. Power supplies
likewise have some upper limit.
3. Time: NeoPixels process data from the host microcontroller at a fixed data rate; more pixels = more
time and lower animation frame rates.
NeoPixel products are available in a zillion form factorsfrom individual tiny pixels to huge matricesplus
strips, rings and everything in-between.
Pick a category from the left column for product links and tips & tricks specific to each type of NeoPixel.
Though strips are described as flexible, they do not tolerate continuous and repeated
bending. Formable might be a better word. A typical application is architecture, where they can be
curved around columns and then stay put. Repeated flexing (as on costumes) will soon crack the
solder connections. For wearable use, either affix shorter segments to a semi-rigid base (e.g. a hat,
BMX armor, etc.), or use the individual sewable NeoPixels shown later.
Watch your power draw. Though each pixel only needs a little current, itadds up fastNeoPixel
strips are so simple to use, one can quickly get carried away! Well explain more on the Powering
NeoPixels page.
NeoPixel strips are just the startweve got shapes too! Rings, grids, shields and more
Rather than list a zillion different links, we have a single landing page for selecting among all the different
NeoPixel ring products:
Outer
Number of Pixels Inner Diameter
Diameter
31.75 mm /
16 44.5 mm / 1.75"
1.25"
60 (4x 15-pixel
158 mm / 6.2" 145 mm / 5.7"
arcs)
All rings are about 3.6 millimeters / 0.15" thick (1.6 mm for PCB, 2 mm for NeoPixels).
RGB NeoPixels are the most affordable and can produce millions of color combinations.
RGBW NeoPixels offer an eye-pleasing true white in addition to RGB. These are available in three
different color temperaures:
320 mm x 80 mm / 12.6" x
8x32 256 77 Watts (15 Amps at 5 Volts)
3"
Though called flexible, these matrices do not tolerate continuous and repeated
bending. Formable might be a better word they can be bent around a rigid or semi-rigid shape, like a
hat. Repeated flexing (as on costumes) will soon crack the solder connections. (The videos on the
product pages are to highlight just how flexible these matrices are, but this really is a dont try this at
home thing.)
Flex matrices are available with RGB pixels only; RGBW is not offered.
If you need a size or shape of NeoPixel matrix thats not offered here, its possible tocreate your own
using sections of NeoPixel strip!
NeoPixel FeatherWing
NeoPixel Jewels
Its very strongly recommended that each NeoPixel have an accompanying 0.1 F capacitor
between +V and ground. This prevents communication problems due to brownout of the on-pixel driver
logic. Its occasionally sufficient to have one capacitor between pairs of pixels; some of our NeoPixel rings
work that way.
Through-Hole NeoPixels
SMT NeoPixels
WS2811 Driver IC
Identify the input end of your NeoPixel strip, pixel(s) or other device. On some, there will be a solder pad
labeled DIN or DI (data input). Others will have an arrow showing the direction that data moves. The
data input can originate from any digital pin on the Arduino, but all the example code is set up fordigital
pin 6 by default. The NeoPixel shield comes wired this way.
For other Arduino boards with a separate +5V DC power supply for the NeoPixels:connect the +5V
input on the strip to the + (positive) terminal on the power supply (dont connect to the Arduino), DIN to
digital pin 6 on the Arduino, and (minus or GND) on the strip must connect to both the minus ()
terminal on the DC supply and a GND pin on the Arduino (there are usually several any will do).
The 144 pixel strips are so tightly packed, theres no room for labels other than , + and the data direction
arrows. Data is the un-labeled pad.
The order of the three pins can vary between different strip densities and batches. ALWAYS use the
labels printed ON THE STRIP. Look closely, NEVER blindly follow a NeoPixel strip wiring diagram; it
might be based on a different strip type!
Sometimes. The Arduino can continuously supply only about 500 milliamps to the 5V pin. Each NeoPixel
can draw up to 60 milliamps at full brightness. So yes, you can skip the separate DC supply and power
directly off the Arduino as long as just a few pixels are used, more if the colors and overall brightness are
low. When in doubt, give the pixels a separate power supply.
Before connecting NeoPixels to any large power source (DC wall wart or even a large battery), add
a capacitor (1000 F, 6.3V or higher) across the + and terminals as shown above. The capacitor
buffers sudden changes in the current drawn by the strip.
Place a 300 to 500 Ohm resistor between the Arduino data output pin and the input to the first
NeoPixel. The resistor should be at the end of the wire closest to the NeoPixel(s), not the
microcontroller. Some products already incorporate this resistorif youre not sure, add one
theres no harm in doubling up!
Try to minimize the distance between the Arduino and first pixel, so the signal is clear. A meter or
two is usually no problem. Much longer and things can become unreliable.
Avoid connecting NeoPixels to a live circuit. If you simply must, always connect ground first,
then +5V, then data. Disconnect in the reverse order.
If powering the pixels with a separate supply, apply power to the pixels before applying power to the
microcontroller.
Observe the same precautions as you would for any static-sensitive part; ground yourself before
handling, etc.
NeoPixels powered by 5v require a 5V data signal. If using a 3.3V microcontroller you must use a
logic level shifter such as a 74AHCT125 (http://adafru.it/e5g) or 74HCT245 (http://adafru.it/1779). (If
you are powering your NeoPixels with 3.7v like from a LiPoly, a 3.3v data signal is OK)
Make sure that your connections are secure. Alligator clips do not make reliable connections to the
tiny solder pads on NeoPixel rings. Better to solder a small pigtail wire to the ring and attach the
alligator clips to that.
Some of our projects dont make the above precautionsthese are typically small battery-powered
devices and power spikes arent a big concern. Any project with a lot pixels or a large power
source should definitely include the power capacitor and data line resistor.
Some (not all) NeoPixel products can work with slightly higher voltages. This depends on the additional
support components around the chip, based on available space, cost and the most likely application.
Refer to the specific product description page for guidance on acceptable voltage limits for each
type. When in doubt, aim for 5 Volts.
Lower voltages are always acceptable, with the caveat that the LEDs will be slightly dimmer. Theres a
limit below which the LED will fail to light, or will start to show the wrong color.
Battery-operated LED project planning is discussed in greater detail inBattery Power for LED
Pixels and Strips (http://adafru.it/cDU).
To estimate power supply needs, multiply the number of pixels by 20, then divide the result by 1,000 for
the rule of thumb power supply rating in Amps. Or use 60 (instead of 20) if you want to guarantee an
absolute margin of safety for all situations. For example:
The choice of overhead in your power supply is up to you. Maximum safety and reliability are achieved
with a more generously-sized power supply, and this is what we recommend. Most power supplies can
briefly push a little extra current for short periods. Many contain a thermal fuse and will simply shut down
if overworked. So they may technically work, but this is the electronics equivalent of abusing a rental car.
Keep in mind, 60 mA is a worst case estimate! Weve written a whole separate tutorial on getting
things under control: Sipping Power with NeoPixels (http://adafru.it/wbm).
I estimate I need a 3.6 Amp power supply. I have a 10 Amp supply on-hand. Will this cause my NeoPixels
to explode?
As long as the output is 5 Volts DC, youre golden. The LEDs will only draw as much current (Amperes)
as they need. So extra Amps are OK in fact, it can be a good thing. The larger power supply will run
cooler because its not being pushed to its limit.
If you go this route, the key is to have all of the ground pins among the strips connected in common, but
the +5V from each power supply should be connected only to one length of NeoPixels those should not
all be joined. Every power supply is a little different not precisely 5 Volts and this keeps some from
back-feeding into others.
One possibility is to repurpose an ATX computer power supply. The nice beefy server types often provide
up to 30 Amps. Some minor modifications are neededGoogle around for ATX power supply hack.
Note that the ATX 5V rail can be very unstable if there's no load on the 12V rail!
Even larger (and scarier, and much more expensive) are laboratory power supplies with ratings into the
hundreds of Amps. Sometimes this is whats needed for architectural scale projects and large stage
productions. And occasionally we get requests for help
Please note that projects of this scale are potentially very dangerous, and the problems of power
distribution are fundamentally different than hobby-scale projects. As much as we enjoy helping our
customers in the forums, they are for product technical support and not full-on engineering services. If
youre developing a project of this scope, hire a professional electrician with experience in high-power,
low-voltage systems such as photovoltaics or large RVs and boats. This is no charade.
Distributing Power
The longer a wire is, the more resistance it has. The more resistance, the more voltage drops along its
length. If voltage drops too far, the color of NeoPixels can be affected.
Consider a full 4 meter reel of NeoPixels. With 5V applied at one end of the strip, for those pixels closest
to this end, power traverses only a few inches of copper. But at the far end of the strip, power traverses 8
meters of copper 4 meters out on the +5V line, 4 meters back on the ground line. Those furthest pixels
will be tinted brown due to the voltage drop (blue and green LEDs require higher voltage than red).
1. Lower the voltage to the NeoPixels so its closer (or equal) to that of the microcontroller. This is why
we recommend LiPo batteries for FLORA projects: 3.7V is enough to run a short length of pixels,
and the microcontroller is comfortable at that voltage as well.
2. Use a logic level shifter (http://adafru.it/e5g) to step up the signal from the microcontroller to the first
pixel.
Because processor-specific assembly language is used, this library does not work on Netduino,
ChipKIT or other advanced Arduino-like boards. Others may have written code and libraries for such
boards, but were not able to provide technical support for any bugs or trouble you might encounter there;
its some real frontier engineering. Some of these alternative libraries are covered in the Advanced
Coding section.
Heres a tutorial (http://adafru.it/aYM) that walks through the process of correctly installing Arduino
libraries manually.
(If the Adafruit_NeoPixel rollover menu is not present, the library has not been correctly installed, or the
IDE needs to be restarted after installation. Check the installation steps above to confirm its properly
named and located.)
Select your board type and serial port from the Tools menu, and try uploading to the board. If the
NeoPixels are connected and powered as previously described, you should see a little light show.
Nothing happens!
Check your connections. The most common mistake is connecting to the output end of a strip rather than
the input.
If you are using an RGBW NeoPixel product (look at the LEDs, are they divided 'in half' with a yellow
semicircle? you have RGBW Neopixels!)
to
99% of the time this is due to not having a shared ground wire connected to the Arduino. Make sure the
Ground wire from the Neopixels connects to BOTH your power supply ground AND the Arduino
ground.
To learn about writing your own NeoPixel sketches, lets begin bydissecting the strandtest sketch
#include <Adafruit_NeoPixel.h>
The block of code that follows is mostly descriptive comments. Only the last line is really doing any work:
#define PIN 6
The first line assigns a number to the symbol PIN for later reference. It doesnt need to be done this
way, but makes it easier to change the pin where the NeoPixels are connected without digging deeper
into the code.
The last line declares a NeoPixel object. Well refer to this by name later to control the strip of pixels.
There are three parameters or arguments in parenthesis:
1. The number of sequential NeoPixels in the strip. In the example this is set to 60, equal to 1 meter of
medium-density strip. Change this to match the actual number youre using.
2. The pin number to which the NeoPixel strip (or other device) is connected. Normally this would be a
number, but we previously declared the symbol PIN to refer to it by name here.
3. A value indicating the type of NeoPixels that are connected.In most cases you can leave this off
and pass just two arguments; the example code is just being extra descriptive. If you have a
supply of classic V1 Flora pixels, those require NEO_KHZ400 + NEO_RGB to be passed here.
For through-hole 8mm NeoPixels, use NEO_RGB instead of NEO_GRB in the strip declaration. For
RGBW LEDs use NEO_RGBW (some RGBW strips use NEO_GRBW, so try that if you're getting
unexpected results!)
Then, in the setup() function, call begin() to prepare the data pin for NeoPixel output:
void setup() {
strip.begin();
strip.show(); // Initialize all pixels to 'off'
}
There are two ways to set the color of a pixel. The first is:
strip.setPixelColor(n, red, green, blue);
The first argument n in this example is the pixel number along the strip, starting from 0 closest to the
Arduino. If you have a strip of 30 pixels, theyre numbered 0 through 29. Its a computer thing. Youll see
various places in the code using a for loop, passing the loop counter variable as the pixel number to this
function, to set the values of multiple pixels.
The next three arguments are the pixel color, expressed as red, green and blue brightness levels, where
0 is dimmest (off) and 255 is maximum brightness. The last optional argument is for white, which will only
be used if the strip was defined during creation as an RGBW type and the strip actually is RGBW type.
To set the 12th pixel (#11, counting from 0) to magenta (red + blue), you could write:
to set the 8th pixel (#7 counting from 0) to half-brightness white, with no light from red/green/blue, use:
strip.setPixelColor(7, 0, 0, 0, 127);
Here, color is a 32-bit type that merges the red, green and blue values into a single number. This is
sometimes easier or faster for some (but not all) programs to work with; youll see the strandtest code
uses both syntaxes in different places.
You can also convert separate red, green and blue values into a single 32-bit type for later use:
uint32_t magenta = strip.Color(255, 0, 255);
Then later you can just pass magenta as an argument to setPixelColor rather than the separate red,
green and blue numbers every time.
You can also (optionally) add a white component to the color at the end, like this:
setPixelColor() does not have an immediate effect on the LEDs. To push the color data to the strip, call
This updates the whole strip at once, and despite the extra step is actually a good thing. If every call to
setPixelColor() had an immediate effect, animation would appear jumpy rather than buttery smooth.
You can query the color of a previously-set pixel using getPixelColor():
uint32_t color = strip.getPixelColor(11);
The overall brightness of all the LEDs can be adjusted using setBrightness(). This takes a single
argument, a number in the range 0 (off) to 255 (max brightness). For example, to set a strip to 1/4
brightness:
strip.setBrightness(64);
Just like setPixel(), this does not have an immediate effect. You need to follow this with a call to show().
setBrightness() was intended to be called once, in setup(), to limit the current/brightness of the LEDs
throughout the life of the sketch. It is not intended as an animation effect itself! The operation of this
function is lossy it modifies the current pixel data in RAM, not in the show() call in order to meet
NeoPixels strict timing requirements. Certain animation effects are better served by leaving the
brightness setting alone, modulating pixel brightness in your own sketch logic and redrawing the full strip
with setPixel().
Another (less common) possibility is running out of RAM see the last section below. If the programsort
of works but has unpredictable results, consider that.
Can I have multiple NeoPixel objects on different pins?
Certainly! Each requires its own declaration with a unique name:
Adafruit_NeoPixel strip_a = Adafruit_NeoPixel(16, 5);
Adafruit_NeoPixel strip_b = Adafruit_NeoPixel(16, 6);
The above declares two distinct NeoPixel objects, one each on pins 5 and 6, each containing 16 pixels
and using the implied default type (NEO_KHZ800 + NEO_GRB).
Can I connect multiple NeoPixel strips to the same Arduino pin?
In many cases, yes. All the strips will then show exactly the same thing. This only works up to a point
thoughfour strips on a single pin is a good and reliable number. If you need more than that, individual
NeoPixels can be used as buffers to fan out to more strips: connect one Arduino pin to the inputs of four
separate NeoPixels, then connect each pixels output to the inputs of four strips (or fewer, if you dont
need quite that many). If the strips are 10 pixels long, declare the NeoPixel object as having 11 pixels.
The extra buffer pixels will be at position #0 just leave them turned off and the strips then run from
positions 1 through 10.
See note above; setBrightness() is designed as a one-time setup function, not an animation effect.
Also see the Advanced Coding page theres an alternative library that includes nondestructive
brightness adjustment, among other features!
For using really large numbers of LEDs, you might need to step up to a more potent board like the
Arduino Mega or Due. But if youre close and need just a little extra space, you can sometimes tweak your
code to be more RAM-efficient. This tutorial has some pointers on memory usage. (http://adafru.it/coj)
The Adafruit_NeoMatrix library builds upon Adafruit_NeoPixel to create two-dimensional graphic displays
using NeoPixels. You can then easily draw shapes, text and animation without having to calculate every
X/Y pixel position. Small NeoPixel matrices are available in the shop. Larger displays can be formed
using sections of NeoPixel strip, as shown in the photo above.
In addition to the Adafruit_NeoPixel library (which was already downloaded and installed in a prior step),
NeoMatrix requires two additional libraries:
1. Adafruit_NeoMatrix (http://adafru.it/cDt)
2. Adafruit_GFX (http://adafru.it/cBB)
If youve previously used any Adafruit LCD or OLED displays, you might already have the latter library
installed.
Installation for both is similar to Adafruit_NeoPixel before: unzip, make sure the folder name matches the
.cpp and .h files within, then move to your Arduino libraries folder and restart the IDE.
Arduino sketches need to include all three headers just to use this library:
#include <Adafruit_GFX.h>
#include <Adafruit_NeoMatrix.h>
#include <Adafruit_NeoPixel.h>
Layouts
Adafruit_NeoMatrix uses exactly the same coordinate system, color functions and graphics commands as
the Adafruit_GFX library. If youre new to the latter, a separate tutorial explains its
use (http://adafru.it/aPe). There are also example sketches included with the Adafruit_NeoMatrix library.
Well just focus on the constructor here how to declare a two-dimensional display made from
Lets begin with the declaration for a single matrix, because its simpler to explain. Well be demonstrating
the NeoPixel Shield for Arduino in this case an 8x5 matrix of NeoPixels. When looking at this shield
with the text in a readable orientation, the first pixel, #0, is at the top left. Each successive pixel is right
one position pixel 1 is directly to the right of pixel 0, and so forth. At the end of each row, the next pixel
is at the left side of the next row. This isnt something we decide in codeits how the NeoPixels are
hard-wired in the circuit board comprising the shield.
We refer to this layout as row major and progressive. Row major means the pixels are arranged in
horizontal lines (the opposite, in vertical lines, is column major). Progressive means each row proceeds in
the same direction. Some matrices will reverse direction on each row, as it can be easier to wire that way.
Howeverfor this example, we want to use the shield in the tall direction, so the Arduino is standing up
on the desk with the USB cable at the top. When we turn the board this way, the matrix layout changes
Now the first pixel is at the top right. Pixels increment top-to-bottom its now column major. The order
of the columns is still progressive though.
The first two arguments 5 and 8 are the width and height of the matrix, in pixels. The third argument
6 is the pin number to which the NeoPixels are connected. On the shield this is hard-wired to digital
pin 6, but standalone matrices are free to use other pins.
The next argument is the interesting one. This indicates where the first pixel in the matrix is positioned
and the arrangement of rows or columns. The first pixel must be at one of the four corners; which corner
is indicated by adding either NEO_MATRIX_TOP or NEO_MATRIX_BOTTOM to either
The last argument is exactly the same as with the NeoPixel library, indicating the type of LED pixels being
used. In the majority of cases with the latest NeoPixel products, you can simply leave this argument off
the example code is just being extra descriptive.
The point of this setup is that the rest of the sketch never needs to think about the layout of the
matrix. Coordinate (0,0) for drawing graphics will always be at the top-left, regardless of the actual
position of the first NeoPixel.
Why not just use the rotation feature in Adafruit_GFX?
Adafruit_GFX only handles rotation. Though it would handle our example above, it doesnt cover every
permutation of rotation and mirroring that may occur with certain matrix layouts, not to mention the zig-
zag capability, or this next bit
Tiled Matrices
A tiled matrix is comprised of multiple smaller NeoPixel matrices. This is sometimes easier for assembly
or for distributing power. All of the sub-matrices need to be the same size, and must be ordered in a
predictable manner. The Adafruit_NeoMatrix() constructor then receives some additional arguments:
Adafruit_NeoMatrix matrix = Adafruit_NeoMatrix(
matrixWidth, matrixHeight, tilesX, tilesY, pin, matrixType, ledType);
The first two arguments are the width and height, in pixels, of each tiled sub-matrix, not the entire display.
The next two arguments are the number of tiles, in the horizontal and vertical direction. The dimensions of
the overall display then will always be a multiple of the sub-matrix dimensions.
The fifth argument is the pin number, same as before and as with the NeoPixel library. The last argument
also follows prior behaviors, and in most cases can be left off.
With a single matrix, there was a starting corner, a major axis (rows or columns) and a line sequence
(progressive or zigzag). This is now doubled similar information is needed both for the pixel order
within the individual tiles, and the overall arrangement of tiles in the display. As before, we add up a list of
symbols to produce a single argument describing the display format.
The NEO_MATRIX_* symbols work the same as in the prior single-matrix case, and now refer to the
individual sub-matrices within the overall display. All tiles must follow the same format. An additional set
of symbols work similarly to then describe the tile order.
Tiles can be arranged in horizontal rows or vertical columns. Again this is independent of the pixel order
within the tiles. Add either NEO_TILE_ROWS or NEO_TILE_COLUMNS.
Finally, rows or columns of tiles may be arranged in progressive or zigzag order; that is, every row or
column proceeds in the same order, or alternating rows/columns switch direction. Add either
NEO_TILE_PROGRESSIVE or NEO_TILE_ZIGZAG to indicate the order. BUTif NEO_TILE_ZIGZAG
order is selected, alternate lines of tiles must be rotated 180 degrees. This is intentional and by design; it
keeps the tile-to-tile wiring more consistent and simple. This rotation is not required for
NEO_TILE_PROGRESSIVE.
Tiles dont need to be square! The above is just one possible layout. The display shown at the top of this
page is three 10x8 tiles assembled from NeoPixel strip.
Once the matrix is defined, the remainder of the project is similar to Adafruit_NeoPixel. Remember to use
matrix.begin() in the setup() function and matrix.show() to update the display after drawing. The
setBrightness() function is also available. The library includes a couple of example sketches for reference.
Other Layouts
For any other cases that are not uniformly tiled, you can provide your own function to remap X/Y
coordinates to NeoPixel strip indices. This function should accept two unsigned 16-bit arguments (pixel X,
Y coordinates) and return an unsigned 16-bit value (corresponding strip index). The simplest row-major
progressive function might resemble this:
uint16_t myRemapFn(uint16_t x, uint16_t y) {
return WIDTH * y + x;
}
Thats a crude example. Yours might be designed for pixels arranged in a spiral (easy wiring), or a Hilbert
curve.
RAM Again
On a per-pixel basis, Adafruit_NeoMatrix is no more memory-hungry than Adafruit_NeoPixel, requiring 3
bytes of RAM per pixel. But the number of pixels in a two-dimensional display takes off exponentiallya
16x16 display requires four times the memory of an 8x8 display, or about 768 bytes of RAM (nearly half
the available space on an Arduino Uno). It can be anywhere from tricky to impossible to combine large
displays with memory-hungry libraries such as SD or ffft.
Gamma Correction
Because the Adafruit_GFX library was originally designed for LCDs (having limited color fidelity), it
handles colors as 16-bit values (rather than the full 24 bits that NeoPixels are capable of). This is not the
big loss it might seem. A quirk of human vision makes bright colors less discernible than dim ones. The
Adafruit_NeoMatrix library uses gamma correction to select brightness levels that are visually (though not
numerically) equidistant. There are 32 levels for red and blue, 64 levels for green.
The Color() function performs the necessary conversion; you dont need to do any math. It accepts 8-bit
red, green and blue values, and returns a gamma-corrected 16-bit color that can then be passed to other
drawing functions.
FastLED works altogether differently; its 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 dont write or maintain FastLED, and cant provide software troubleshooting advice.If requesting help
with a FastLED NeoPixel project in the forums, well usually ask that you try one of the known-working
Adafruit_NeoPixel example sketches to narrow down whether its a hardware or software issue.
Unfortunately the NeoPixel and Servo libraries dont play nice together; one is dependent on periodically
disabling interrupts, the other absolutely requires interrupts. There are a couple of options here:
Just like Servos, the infrared library uses software interrupts to poll the IR LED, while the standard
neopixel library blocks interrupts while neopixels are being updated.
If you don't constantly update the neopixels, IR will work in between updates, but if you update them all
the time, you will need to use another library and a microcontroller better than an Uno, Mega, Leonardo,
or any simple microcontroller. Ideally one with DMA so that NeoPixels don't take up any 'time'
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 (http://adafru.it/xA2)
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 pixels 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, thats (100 * 30) + 50, or 3,050 microseconds. 1,000,000 / 3,050 = 328 updates
per second, approximately.
However
Thats only the time needed to push the bits down the wire. The actual refresh rate will be something less
than this, and cant 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 thats 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 cant 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 drivesmultiple
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, theres often an unreasonable over-emphasis on data rates when the
real bottlenecks lie elsewheredont dwell on this too much unless you can confirm its 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 upanything
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.
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 cant fix bugs or offer technical help. This is Wild West stuff.
OctoWS2811 (http://adafru.it/cDM): 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 (http://adafru.it/cDN): also for Teensy 3.0. Doesnt support as many pixels as
OctoWS2811, but adds dithering and smooth interpolation for color purists.
LEDscape (http://adafru.it/cDO): 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 (http://adafru.it/cDP) for Parallax Propeller.
xCORE NeoPixel test code (http://adafru.it/dcO) for the XMOS xCORE startKIT.
Some of these are 3.3V devices. See the Powering NeoPixel page for notes on controlling 5V NeoPixels
from 3.3V microcontrollers.
WS2811? WS2812? Why do I see two different names mentioned?
The WS2811 is an earlier driver chip separate from the RGB LED. The data signal is similar, but runs at
half the speed. By the time the WS2812 (with integrated LED) was released, a lot of code and projects
had already built up around the WS2811 name. Sometimes code for the WS2811 might actually be for
the newer chip, or for either type. The Adafruit_NeoPixel library supports both.
The WS2812 datasheet (http://adafru.it/cDB) explains the data transmission protocol. This is a self-
clocking signal theres 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 theres nearly 25% wiggle room in the timing. So if your code cant match the recommended
times exactly, its usually okay, as long as its 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!
After all the color data is sent, the data line must be held low for a minimum of 50 microseconds for the
new colors to latch.
You may want to dig through ourArduino library (http://adafru.it/aZU) for insights. The timing-critial parts
are written in AVR assembly language, but its extensively commented with C-like pseudocode.
My Microcontroller Isnt Fast Enough to Do That
The WS2812 appears to be backwardly-compatible with the 400 KHz WS2811 signal. If you can precisely
match the latter chips timing, either type will respond. The WS2811 protocol is not simply a half-speed
WS2812. The duty cycle for the 0 and 1 bits is slightly different. From theWS2811
datasheet (http://adafru.it/cDS):