Adafruit NeoPixel Überguide Created by Phillip Burgess Last updated on 2015-07-27 01:00:14 PM EDT
Guide Contents Guide Contents The Magic of NeoPixels Important Things to Know About NeoPixels in General Adafruit NeoPixels are Available in the Following Products: Important Things to Know About NeoPixel Strips Important Things to Know About NeoPixel Rings Best Practices 2 3 3 4 6 9 13 Improper use can damage your NeoPixels.
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.
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. 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.
maximum brightness) per meter is: 30 LEDs: 9.5 Watts (just under 2 Amps at 5 Volts). 60 LEDs: 18 Watts (about 3.6 Amps at 5 Volts). 144 LEDs : 35 watts (7 Amps at 5 Volts). Mixed colors and lower brightness settings will use proportionally less power. © Adafruit Industries https://learn.adafruit.
The product list continues below. But first… Important Things to Know About NeoPixel Strips NeoPixel strips are sold in one meter lengths. The 144 pixels/meter strips are always separate 1-meter lengths. For 60 and 30 pixels/meter strips, orders for multiple meters will be a single contiguous strip, up to a limit: 4 meters for 60 pixels/meter strip, or 5 meters for 30 pixels/meter strip.
or use the individual sewable NeoPixels shown later. The flex strips are enclosed in a weatherproof silicone sleeve, making them immune to rain and splashes, but are not recommended for continuous submersion. Early 144 pixel/meter strips were not weatherproof, but the latest batches now include this feature. The silicone sleeve can be cut and removed for a slimmer profile, but the strip is no longer weatherproof. Very few glues will adhere to the weatherproof silicone sleeve.
16 NeoPixel Ring (http://adafru.it/1463) — 1.75 inch (44.5 mm) outside diameter. Max 5V @ 1A. 24 NeoPixel Ring (http://adafru.it/1586) — 2.6 inch (66 mm) outside diameter. Max 5V @ 1.4A 8x8 NeoMatrix (http://adafru.it/1487) — 64 LEDs total. The pixel spacing and board size allow seamless tiling. Max 5V @ 4A. NeoPixel Shield for Arduino (http://adafru.it/1430) — 5x8 matrix plugs directly atop an Arduino board (can also be tiled separately if desired).
Important Things to Know About NeoPixel Rings When soldering wires to these rings, you need to be extra vigilant about solder blobs and short circuits. The spacing between components is very tight! If using alligator clips, we recommend first soldering short jumper wires to the ring inputs and connecting the clips to those, for similar reasons. (Some of our tutorials and product photos do show alligator clips directly connected to the rings, but we’ve had a lot of experience using them.
2) (http://adafru.it/1260) — designed specifically for wearables and “soft circuits,” these NeoPixels can be sewn using our stainless conductive thread (http://adafru.it/641) (traditional soldering works too). Sold in packs of 4. Breadboard-Friendly Smart NeoPixel (http://adafru.it/1312) — accommodates pin headers with standard 0.1" spacing. Sold in packs of 4 (headers are sold separately). NeoPixel Mini PCB (http://adafru.it/1612) — the smallest NeoPixel breakout boards have solder pads on the back.
library (http://adafru.it/aZU), which handles either type. All individual NeoPixels can be chained from a single microcontroller pin, with the one caveat that WS2812 and WS2811 (e.g. Flora V2 and V1) types can’t be mixed in a single chain. Each individual NeoPixel requires 60 milliamps max at full brightness. Mixed colors and lower brightness settings will use proportionally less power. © Adafruit Industries https://learn.adafruit.
© Adafruit Industries https://learn.adafruit.
Best Practices Improper use can damage your NeoPixels. Before diving in, be aware of the following: Before connecting NeoPixels to any power source, add a large capacitor (1000 µF, 6.3V or higher) across the + and – terminals as shown above. Place a 300 to 500 Ohm resistor between the Arduino data output pin and the input to the first NeoPixel.
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 NeoPixel project guides fail to mention the above precautions…they were written before these lessons were learned, and will be updated as required. The design changes are usually minimal (e.g. add inline resistor on data pin in circuit diagrams). Smaller, battery-operated projects (e.g.
Arduino Library Controlling NeoPixels “from scratch” is quite a challenge, so we provide a library letting you focus on the fun and interesting bits. The library works with most mainstream Arduino boards and derivatives: Uno, Mega, Leonardo, Micro, Adafruit Flora, etc. — most anything with an Atmel AVR 8-bit processor from 8 to 16 MHz — and also works with the Arduino Due and all varieties of the PJRC Teensy boards.
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).
We also 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. 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.
#define PIN 6 // Parameter 1 = number of pixels in strip // Parameter 2 = pin number (most are valid) // Parameter 3 = pixel type flags, add together as needed: // NEO_KHZ800 800 KHz bitstream (most NeoPixel products w/WS2812 LEDs) // NEO_KHZ400 400 KHz (classic 'v1' (not v2) FLORA pixels, WS2811 drivers) // NEO_GRB Pixels are wired for GRB bitstream (most NeoPixel products) // NEO_RGB Pixels are wired for RGB bitstream (v1 FLORA pixels, not v2) Adafruit_NeoPixel strip = Adafruit_NeoPixel(60, PIN, NEO_GRB +
In the strandtest example, loop() doesn’t set any pixel colors on its own — it calls other functions that create animated effects. So let’s ignore it for now and look ahead, inside the individual functions, to see how the strip is controlled. 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.
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); This returns a 32-bit merged color value. The number of pixels in a previously-declared strip can be queried using numPixels(): uint16_t n = strip.
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 though…four strips on a single pin is a good and reliable number.
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.
Three alkaline cells (such as AA batteries) can be installed in a battery holder (http://adafru.it/771) 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 (http://adafru.it/830) to provide 4.8 Volts. Make sure you only use NiMH cells in this configuration.
Battery-operated LED project planning is discussed in greater detail in Battery Power for LED Pixels and Strips (http://adafru.it/cDU). For most non-portable “desktop” projects, a 5V DC switching power supply (http://adafru.it/276) 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.
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.
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.
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 (http://adafru.it/ciD) guide.) Driving 5V NeoPixels from 3.3V Microcontrollers Increasingly, microcontrollers are running at 3.3 Volts instead of 5 Volts.
NeoMatrix Library 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.
The extra ifdef/define/endif lines are only needed if you’re using an Arduino Due. Otherwise they can be left out. Layouts Adafruit_NeoMatrix uses exactly the same coordinate system, color functions and graphics commands as the Adafruit_GFX library. If you’re 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.
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. We call that a zigzag layout. However…for 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.
Now the first pixel is at the top right. Pixels increment top-to-bottom — it’s now column major. The order of the columns is still progressive though. We declare the matrix thusly: Adafruit_NeoMatrix matrix = Adafruit_NeoMatrix(5, 8, 6, NEO_MATRIX_TOP + NEO_MATRIX_RIGHT + NEO_MATRIX_COLUMNS + NEO_MATRIX_PROGRESSIVE, NEO_GRB + NEO_KHZ800); 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.
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 NEO_MATRIX_LEFT or NEO_MATRIX_RIGHT.
The second-to-last argument though…this gets complicated… 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.
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.
passed to other drawing functions. © Adafruit Industries https://learn.adafruit.
Advanced Coding Help! My Arduino servo code stops working when combined with NeoPixels! 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 (http://adafru.it/1411) or breakout board (http://adafru.it/815), offloading that task from the processor so interrupts are a nonissue.
Another is to develop your own code for a more capable microcontroller or an FPGA that drives multiple NeoPixel strips in parallel. One such project — OctoWS2811 for the Teensy 3.0 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 a problem.
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. Writing Your Own Library The WS2812 datasheet (http://adafru.
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 our Arduino library (http://adafru.it/aZU) for insights. The timing-critial parts are written in AVR assembly language, but it’s extensively commented with C-like pseudocode.
