Arduino Library Installation
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. 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 we’re not able to provide technical support for any bugs or trouble you might encounter there; it’s some real frontier engineering. Some of these alternative libraries are covered in the “Advanced Coding” section.
Install Adafruit_NeoPixel Library
Recent versions of the Arduino IDE (1.6.2 and later) make library installation super easy via the Library Manager interface. From the “Sketch” menu, select Include Library→Manage Libraries. Enter “NeoPixel” in the filter box to quickly find the Adafruit library, then install it.
If you’re using an older version of the IDE, or just want to set things up manually, “classic” installation of the library is as follows: you can visit the Adafruit_NeoPixel library page at Github and download from there, or just click this button:
Download Adafruit_NeoPixel for Arduino
- Uncompress the ZIP file after it’s finished downloading.
- The resulting folder should contain the files Adafruit_NeoPixel.cpp, Adafruit_NeoPixel.h and an “examples” sub-folder. Sometimes in Windows you’ll get an intermediate-level folder and need to move things around.
- Rename the folder (containing the .cpp and .h files) to Adafruit_NeoPixel (with the underscore and everything), and place it alongside your other Arduino libraries, typically in your (home folder)/Documents/Arduino/Libraries folder. Libraries should never be installed in the “Libraries” folder alongside the Arduino application itself…put them in the subdirectory of your home folder.
- Re-start the Arduino IDE if it’s currently running.
Here’s a tutorial that walks through the process of correctly installing Arduino libraries manually.
A Simple Code Example: strandtest
Launch the Arduino IDE. From the File menu, select Sketchbook→Libraries→Adafruit_NeoPixel→strandtest (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 it’s 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.
Something happens but the LEDs are blinking in a weird way!
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!)
Change this line:
Adafruit_NeoPixel strip = Adafruit_NeoPixel(60, PIN, NEO_GRB + NEO_KHZ800);
to
Adafruit_NeoPixel strip = Adafruit_NeoPixel(60, PIN, NEO_RGBW + NEO_KHZ800);
and reupload the strandtest example.
I don’t have RGBW LEDs and the LEDs are still blinking weird!
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.
Arduino Library Use
It’s assumed at this point that you have the Adafruit_NeoPixel library for Arduino installed and have run the strandtest example sketch successfully. If not, return to the prior page for directions to set that up.
To learn about writing your own NeoPixel sketches, let’s begin by dissecting the strandtest sketch…
All NeoPixel sketches begin by including the header file:
#include <Adafruit_NeoPixel.h>
- #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
// 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 + NEO_KHZ800);
- #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)
10.Adafruit_NeoPixel strip = Adafruit_NeoPixel(60, PIN, NEO_GRB + NEO_KHZ800);
The first line assigns a number to the symbol “PIN” for later reference. It doesn’t 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. We’ll refer to this by name later to control the strip of pixels. There are three parameters or arguments in parenthesis:
- 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 you’re using.
- 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.
- 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
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’
}
- void setup() {
- begin();
- show(); // Initialize all pixels to ‘off’
- }
The second line, strip.show(), isn’t absolutely necessary, it’s just there to be thorough. That function pushes data out to the pixels…since no colors have been set yet, this initializes all the NeoPixels to an initial “off” state in case some were left lit by a prior program.
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);
- 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, they’re numbered 0 through 29. It’s a computer thing. You’ll 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. To set the 12th pixel (#11, counting from 0) to magenta (red + blue), you could write:
strip.setPixelColor(11, 255, 0, 255);
- setPixelColor(11, 255, 0, 255);
An alternate syntax has just two arguments:
strip.setPixelColor(n, color);
- setPixelColor(n, color);
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; you’ll 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);
- 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.
setPixelColor() does not have an immediate effect on the LEDs. To “push” the color data to the strip, call show():
strip.show();
- show();
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);
- 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.numPixels();
- uint16_t n = strip.numPixels();
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);
- 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().
I’m calling setPixel() but nothing’s happening!
There are two main culprits for this:
- forgetting to call strip.begin() in setup().
- forgetting to call strip.show() after setting pixel colors.
Another (less common) possibility is running out of RAM — see the last section below. If the program sort 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);
- 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. 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 don’t 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.
I’m getting the wrong colors. Red and blue are swapped!
When using through-hole 8mm NeoPixels (or V1 Flora pixels), use NEO_RGB for the third parameter in the Adafruit_NeoPixel declaration. For all other types of NeoPixels, use NEO_GRB.
The colors fall apart when I use setBrightness() repeatedly!
See note above; setBrightness() is designed as a one-time setup function, not an animation effect.
Also see the “Advanced Coding” page — there’s an alternative library that includes “nondestructive” brightness adjustment, among other features!
Pixels Gobble RAM
Each NeoPixel requires about 3 bytes of RAM. This doesn’t sound like very much, but when you start using dozens or even hundreds of pixels, and consider that the mainstream Arduino Uno only has 2 kilobytes of RAM (often much less after other libraries stake their claim), this can be a real problem! 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 you’re 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.
NeoMatrix Library
by Technology
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:
If you’ve 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>
- #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 you’re new to the latter, a separate tutorial explains its use. There are also example sketches included with the Adafruit_NeoMatrix library. We’ll just focus on the constructor here — how to declare a two-dimensional display made from NeoPixels. Powering the beast is another matter, covered on the prior page.
The library handles both single matrices — all NeoPixels in a single uniform grid — and tiled matrices — multiple grids combined into a larger display:
Let’s begin with the declaration for a single matrix, because it’s simpler to explain. We’ll be demonstrating the NeoPixel Shield for Arduino in this case — an 8×5 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 isn’t something we decide in code…it’s 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. 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. 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 — 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);
- 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. 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 NEO_MATRIX_LEFT or NEO_MATRIX_RIGHT. The row/column arrangement is indicated by further adding either NEO_MATRIX_COLUMNS or NEO_MATRIX_ROWS to either NEO_MATRIX_PROGRESSIVE or NEO_MATRIX_ZIGZAG. These values are all added to form a single value as in the above code. NEO_MATRIX_TOP + NEO_MATRIX_RIGHT + NEO_MATRIX_COLUMNS + NEO_MATRIX_PROGRESSIVE 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.
View more at: http://yoursmart.mobi
Post a Comment