The Magic of NeoPixels

Incorporating scads of LEDs into an electronic project used to be a hairy prospect, a veritable rat’s nest of wires and code. The arrival of dedicated LED driver chips brought welcome relief, offloading grunt work from the microcontroller and allowing one to focus on the application. Much simpler, but still not “Christmas light” simple.

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 you’re eager to get started…but If this is your first time using NeoPixels, please at least read the “Best Practices” page before connecting anything!

Important Things to Know About NeoPixels in General

  • Not all addressable LEDs are NeoPixels. “NeoPixel” is Adafruit’s brand for individually-addressable RGB color pixels and strips based on the WS2812WS2811 and SK6812 LED/drivers, using a single-wire control protocol. Other LED products we carry — DotStars, WS2801 pixels, LPD8806 and “analog” strips — use different methodologies (and have their own tutorials). When seeking technical support in the forums, a solution can be found more quickly if the correct LED type is mentioned, i.e. avoid calling DotStars “NeoPixels”…similar, but different!
  • NeoPixels don’t just light up on their own; they require a microcontroller (such as Arduino) and some programming. We provide some sample code to get you started. To create your own effects and animation, you’ll need some programming practice. If this is a new experience, work through some of the beginning Arduino tutorials to get a feel for the language.
  • NeoPixels aren’t the answer for every project. The control signal has very strict timing requirements, and some development boards (such as Netduino or Raspberry Pi) can’t reliably achieve this. This is why we continue to offer other LED types; some are more adaptable to certain situations.

Can I use NeoPixels for POV (persistence of vision) displays?

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 will look much better (they have about a 20 KHz refresh rate).

How about for light painting?

Definitely! The slower movement used for photographic light painting doesn’t call attention to the limited refresh rate; the results look great, especially with a light diffuser.

Is there a limit to the number of NeoPixels in a chain?

There’s no inherent limit in the maximum length of a NeoPixel chain, but eventually you’ll encounter any of various practical limits:

  1. RAM: NeoPixels require some RAM from the host microcontroller; more pixels = more RAM. It’s 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.

Form Factors

NeoPixel products are available in a zillion form factors…from individual tiny pixels to huge matrices…plus 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.

Basic Connections

To get started, let’s assume you have some model of Arduino microcontroller connected to the computer’s USB port. We’ll elaborate on the finer points of powering NeoPixels later, but in general you’ll usually be using a 5V DC power supply (e.g. “wall wart”) or — for wearable projects — a 3.7 Volt lithium-polymer battery.


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 for digital pin 6 by default. The NeoPixel shield comes wired this way.

If using a Flora, Feather or other microcontroller board with an attached lithium-polymer battery: connect the +5V input on the strip to the pad labeled VBAT or BAT on the board, GND from the strip to any GND pad on the microcontroller board, and DIN to Flora pin D6. If the board doesn’t have a pin #6, you’ll need to modify the example code to change the pin number.

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 (don’t 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, there’s 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!
When connecting NeoPixels to any LIVE power source or microcontroller, ALWAYS CONNECT GROUND (–) BEFORE ANYTHING ELSE. Conversely, disconnect ground last when separating.
When using a DC power supply, or an especially large battery, we recommend adding a large capacitor (1000 µF, 6.3V or higher) across the + and – terminals. This prevents the initial onrush of current from damaging the pixels. See the photo on the next page for an example.
With through-hole NeoPixels (5mm or 8mm), add a 0.1 µF capacitor between the + and – pins of EACH PIXEL. Individual pixels may misbehave without this “decoupling cap.”
Adding a ~470 ohm resistor between your microcontroller's data pin and the data input on the NeoPixels can help prevent spikes on the data line that can damage your first pixel. Please add one between your micro and NeoPixels! Our NeoPixel rings already have this resistor on there

Can NeoPixels be powered directly from the Arduino’s 5V pin?

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.

Best Practices

Improper use can damage your NeoPixels. Before diving in, be aware of the following:

  • 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 resistor…if you’re not sure, add one…there’s 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 or 74HCT245. (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.
  • If your microcontroller and NeoPixels are powered from two different sources (e.g. separate batteries for each), there must be a ground connection between the two.

Some of our projects don’t make the above precautions…these are typically small battery-powered devices and power spikes aren’t a big concern. Any project with a lot pixels or a large power source should definitely include the power capacitor and data line resistor.

Powering NeoPixels

When connecting NeoPixels to any live power source or microcontroller, ALWAYS CONNECT GROUND (–) BEFORE ANYTHING ELSE. Conversely, disconnect ground last when separating.
Adding a 300 to 500 Ohm resistor between your microcontroller's data pin and the data input on the first NeoPixel can help prevent voltage spikes that might otherwise damage your first pixel. Please add one between your micro and NeoPixels!
NeoPixels are usually described as “5 Volt devices,” but the reality is a little more nuanced than that.

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. There’s a limit below which the LED will fail to light, or will start to show the wrong color.
Before connecting a NeoPixel strip to ANY source of power, we very strongly recommend adding a large capacitor (1000 µF, 6.3V or higher) across the + and – terminals. This prevents the initial onrush of current from damaging the pixels.
For many wearable projects we recommend a lithium-polymer battery. These deliver 3.7 Volts — perfect for directly feeding low-power microcontrollers such as the Adafruit Flora, yet enough voltage to run a short length of NeoPixels.
Three alkaline cells (such as AA batteries) can be installed in a battery holder to provide 4.5 Volts. Though larger and heaver than the fancy lithium-polymer pack, they’re inexpensive and readily available.
Four nickel-metal hydride (NiMH) rechargeable cells can similarly be used in a 4-cell battery holder to provide 4.8 Volts.

Make sure you only use NiMH cells in this configuration. Four alkaline cells (the disposable type) will output 6V total — that’s too high for some NeoPixels, and definitely too much for the microcontroller!
Battery-operated LED project planning is discussed in greater detail in Battery Power for LED Pixels and Strips.
For most non-portable “desktop” projects, a 5V DC switching power supply is ideal. This small 2 Amp supply is good for a a meter or so of NeoPixel strip. We’ll explain larger projects in a moment.
Be extremely cautious with bench power supplies. Some — even reputable, well-regarded brands — can produce a large voltage spike when initially switched on, instantly destroying your NeoPixels!

If you use a bench supply, do not connect NeoPixels directly. Turn on the power supply first, let the voltage stabilize, then connect the pixels (GND first).

Estimating Power Requirements

Each individual NeoPixel draws up to 60 milliamps at maximum brightness white (red + green + blue). In actual use though, it’s rare for all pixels to be turned on that way. When mixing colors and displaying animations, the current draw will be much less. It’s impossible to estimate a single number for all circumstances, but we’ve been using 1/3 this (20 mA per pixel) as a gross rule of thumb with no ill effects. But if you know for a fact that you need every pixel on at maximum brightness, use the full 60 mA figure.

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:

60 NeoPixels × 20 mA ÷ 1,000 = 1.2 Amps minimum
60 NeoPixels × 60 mA ÷ 1,000 = 3.6 Amps minimum

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! We’ve written a whole separate tutorial on getting things under control: Sipping Power with NeoPixels.

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, you’re 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 it’s not being pushed to its limit.

Excessive voltage, however, will definitely kill your LEDs.

Extra Amps = good. Extra Volts = bad.

What about batteries and “Amp hours”?

Amp-hours are current over time. A 2,600 mAh (milliamp-hour) battery can be thought of as delivering 2.6 Amps continuously for one hour, or 1.3 Amps for 2 hours, and so forth. In reality, it’s not quite linear like that; most batteries have disproportionally shorter run times with a heavy load. Also, most batteries won’t take kindly to being discharged in an hour — this can even be dangerous! Select a battery sufficiently large that it will take at least a couple hours to run down. It’s both safer for you and better for the longevity of the battery.

I need to power LOTS of NeoPixels and don’t have a power supply that large. Can I use several smaller ones?

Maybe. There are benefits to using a single supply, and large power supplies are discussed below. “Non-optimal” doesn’t necessarily mean “pessimal” though, and we wouldn’t discourage anyone from using what resources they have.

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.

Giant Power Supplies

Adafruit offers 5V DC power supplies up to 10 Amps. This is usually sufficient for a couple hundred NeoPixels or more. For really large installations, you’ll need to look elsewhere.

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 needed…Google 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 what’s 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 you’re 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).

Pro Tip: NeoPixels don’t care what end they receive power from. Though data moves in only one direction, electricity can go either way. You can connect power at the head, the tail, in the middle, or ideally distribute it to several points. For best color consistency, aim for 1 meter or less distance from any pixel to a power connection. With larger NeoPixel setups, think of power distribution as branches of a tree rather than one continuous line.

Resistance is just as much a concern on tiny projects too!

For wearable electronics we like conductive thread…it’s flexible and withstands hand washing. Downside is that it doesn’t carry much current. Here several strands of conductive thread have been grouped to provide better capacity for the + and – conductors down a pair of suspenders.

(From the Pac Man Pixel Suspenders guide.)

Driving 5V NeoPixels from 3.3V Microcontrollers

Increasingly, microcontrollers are running at 3.3 Volts instead of 5 Volts. That’s great news for efficiency, but can present a communication problem with 5V NeoPixels. The 3.3V signal from the microcontroller may not be “loud” enough to register with the higher-voltage device. The manufacturer recommends a minimum signal voltage of 70% of the NeoPixel voltage.

There are two ways this can be addressed:

  1. Lower the voltage to the NeoPixels so it’s 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 to step up the signal from the microcontroller to the first pixel.

For more info on using a level shifter with your NeoPixels, have a look at this guide.

NeoPixels got their start on Arduino, but have since branched out to other boards and languages.

Pick a category from the left column for information specific to each coding environment.

Python & CircuitPython

It's easy to use NeoPixel LEDs with Python or CircuitPython and the Adafruit CircuitPython NeoPIxel module.  This module allows you to easily write Python code that controls your LEDs.

You can use these LEDs with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.

Of single boards computers, only Raspberry Pi computers have NeoPixel support at this time.

CircuitPython Microcontroller Wiring

First wire up some NeoPixels to your board exactly as shown on the previous pages. Verify your connection is on the DATA INPUT or DIN side. Plugging into the DATA OUT or DOUT side is a common mistake! The connections are labeled and some formats have arrows to indicate the direction the data must flow.

Do not use the USB pin on your microcontroller for powering more than a few LEDs! For more than that, you'll want to use an external power source. For more information, check out the Powering NeoPixels page of this guide: https://learn.adafruit.com/adafruit-neopixel-uberguide/powering-neopixels

Here's an example of wiring a Feather M0 to a NeoPIxel strip:

  • Board USB to LED 5V
  • Board GND to LED GND
  • Board D5 to LED Din

Python Computer Wiring

Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported

Here's the Raspberry Pi wired to a NeoPixel strip:

  • Pi 5V to LED 5V
  • Pi GND to LED GND
  • Pi GPIO18 to LED Din

On the Raspberry Pi, NeoPixels must be connected to GPIO10, GPIO12, GPIO18 or GPIO21 to work!

CircuitPython Installation of NeoPixel Library

You'll need to install the Adafruit CircuitPython NeoPixel library on your CircuitPython board.

First make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle.  Our CircuitPython starter guide has a great page on how to install the library bundle.

For non-express boards like the Trinket M0 or Gemma M0, you'll need to manually install the necessary libraries from the bundle:

  • neopixel.mpy
  • adafruit_bus_device

Before continuing make sure your board's lib folder or root filesystem has the neopixel.mpy, and adafruit_bus_device files and folders copied over.

Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.

Python Installation of NeoPixel Library

You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!

Once that's done, from your command line run the following command:

  • sudo pip3 install adafruit-circuitpython-neopixel

If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!

CircuitPython & Python Usage

To demonstrate the usage of this library with NeoPixel LEDs, we'll use the board's Python REPL.

For NeoPixels to work on Raspberry Pi, you must run the code as root! Root access is required to access the RPi peripherals.

Run the following code to import the necessary modules and initialise a NeoPixel strip with 30 LEDs. Don't forget to change the pin if your NeoPixels are connected to a different pin, and change the number of pixels if you have a different number.

Download: file
import board
import neopixel
pixels = neopixel.NeoPixel(board.D5, 30)    # Feather wiring!
# pixels = neopixel.NeoPixel(board.D18, 30) # Raspberry Pi wiring!

Now you're ready to light up your NeoPixel LEDs using the following properties:

  • brightness - The overall brightness of the LED
  • fill - Color all pixels a given color.
  • show - Update the LED colors if auto_write is set to False.

For example, to light up the first NeoPixel red:

Download: file
pixels[0] = (255, 0, 0)

To light up all the NeoPixels green:

Download: file
pixels.fill((0, 255, 0))

That's all there is to getting started with CircuitPython and NeoPixel LEDs!

Full Example Code

import time
import board
import neopixel


# On CircuitPlayground Express, and boards with built in status NeoPixel -> board.NEOPIXEL
# Otherwise choose an open pin connected to the Data In of the NeoPixel strip, i.e. board.D1
pixel_pin = board.NEOPIXEL

# On a Raspberry pi, use this instead, not all pins are supported
# pixel_pin = board.D18

# The number of NeoPixels
num_pixels = 10

# The order of the pixel colors - RGB or GRB. Some NeoPixels have red and green reversed!
# For RGBW NeoPixels, simply change the ORDER to RGBW or GRBW.
ORDER = neopixel.GRB

pixels = neopixel.NeoPixel(
    pixel_pin, num_pixels, brightness=0.2, auto_write=False, pixel_order=ORDER
)


def wheel(pos):
    # Input a value 0 to 255 to get a color value.
    # The colours are a transition r - g - b - back to r.
    if pos < 0 or pos > 255:
        r = g = b = 0
    elif pos < 85:
        r = int(pos * 3)
        g = int(255 - pos * 3)
        b = 0
    elif pos < 170:
        pos -= 85
        r = int(255 - pos * 3)
        g = 0
        b = int(pos * 3)
    else:
        pos -= 170
        r = 0
        g = int(pos * 3)
        b = int(255 - pos * 3)
    return (r, g, b) if ORDER in (neopixel.RGB, neopixel.GRB) else (r, g, b, 0)


def rainbow_cycle(wait):
    for j in range(255):
        for i in range(num_pixels):
            pixel_index = (i * 256 // num_pixels) + j
            pixels[i] = wheel(pixel_index & 255)
        pixels.show()
        time.sleep(wait)


while True:
    # Comment this line out if you have RGBW/GRBW NeoPixels
    pixels.fill((255, 0, 0))
    # Uncomment this line if you have RGBW/GRBW NeoPixels
    # pixels.fill((255, 0, 0, 0))
    pixels.show()
    time.sleep(1)

    # Comment this line out if you have RGBW/GRBW NeoPixels
    pixels.fill((0, 255, 0))
    # Uncomment this line if you have RGBW/GRBW NeoPixels
    # pixels.fill((0, 255, 0, 0))
    pixels.show()
    time.sleep(1)

    # Comment this line out if you have RGBW/GRBW NeoPixels
    pixels.fill((0, 0, 255))
    # Uncomment this line if you have RGBW/GRBW NeoPixels
    # pixels.fill((0, 0, 255, 0))
    pixels.show()
    time.sleep(1)

    rainbow_cycle(0.001)  # rainbow cycle with 1ms delay per step

We’re got a whole separate guide explaining the use of NeoPixels in Microsoft MakeCode:

Many of the examples work right in your browser with Circuit Playground Express and its 10 built-in NeoPixel LEDs. There’s even a page explaining how to use MakeCode with external strips as well.

Downloads

This guide was first published on Aug 30, 2013. It was last updated on Aug 30, 2013.