Installation
To download the Arduino library, visit the repository on GitHub . Click the DOWNLOAD ZIP button near the upper left, extract the archive and then rename the uncompressed folder to Adafruit_WS2801. Confirm that this folder contains the files Adafruit_WS2801.cpp and Adafruit_WS2801.h and the examples folder.
Place the Adafruit_WS2801 folder inside your Arduino libraries folder. You may need to create this folder if it does not yet exist. In Windows, this would be (home folder)\My Documents\Arduino\Libraries and for Mac or Linux is (home folder)/Documents/Arduino/Libraries. We also have a tutorial on library installation.
After installing the Adafruit_WS2801 library, restart the Arduino IDE. You should now be able to access the sample code by navigating through menus in this order: File→Sketchbook→Libraries→Adafruit_WS2801→strandtest
Using the Library
Let's look through the strandtest example code. To use the library in an Arduino sketch, you'll first need to globally declare a WS2801 object to talk to the strip. It is invoked with three variables: the number of pixels and the data and clock pins:
int dataPin = 2;
int clockPin = 3;
// Set the first variable to the NUMBER of pixels. 25 = 25 pixels in a row
Adafruit_WS2801 strip = Adafruit_WS2801(25, dataPin, clockPin);
int dataPin = 2;
int clockPin = 3;
// Set the first variable to the NUMBER of pixels. 25 = 25 pixels in a row
Adafruit_WS2801 strip = Adafruit_WS2801(25, dataPin, clockPin);
The example code was written for multiple types of pixels we carry, some of which come in different strand lengths. Since the 36mm strands contain 20 (rather than 25) pixels, feel free to edit the declaration for 20 pixels:
Adafruit_WS2801 strip = Adafruit_WS2801(20, dataPin, clockPin);
Adafruit_WS2801 strip = Adafruit_WS2801(20, dataPin, clockPin);
Next, we initialize the strip in the setup() procedure:
void setup() {
strip.begin();
// Update LED contents, to start they are all 'off'
strip.show();
}
void setup() {
strip.begin();
// Update LED contents, to start they are all 'off'
strip.show();
}
begin() initializes the library, while show() refreshes the displayed colors of the LEDs. You'll need to call show() after changing any pixel colors to see this reflected in the LEDs. This way you can change the entire strip at one time (it takes the same amount of time to change one pixel as it does for an entire strip).
Let's look inside an example function, colorWipe(). This creates a 'chase' sequence that fills the strip with a color. It is basically a loop that increments through every pixel (which you can query with the numPixels() function) and sets the color of each (incremented with i) to the value passed (c — colors are expressed as a 32-bit variable type, though only the bottom 24 bits are used). The strip output is then updated with show(). Finally there is some delay (otherwise this would happen instantly).
Below that is a helper function that converts a color from separate 8-bit red, green and blue values into a combined 24-bit value (suitable for passing to colorWipe()). The brightness range is from 0 (off) to 255 (max brightness).
// fill the dots one after the other with said color
// good for testing purposes
void colorWipe(uint32_t c, uint8_t wait) {
int i;
for (i=0; i < strip.numPixels(); i++) {
strip.setPixelColor(i, c);
strip.show();
delay(wait);
}
}
/* Helper functions */
// Create a 24 bit color value from R,G,B
uint32_t Color(byte r, byte g, byte b)
{
uint32_t c;
c = r;
c <<= 8;
c |= g;
c <<= 8;
c |= b;
return c;
}
// fill the dots one after the other with said color
// good for testing purposes
void colorWipe(uint32_t c, uint8_t wait) {
int i;
for (i=0; i < strip.numPixels(); i++) {
strip.setPixelColor(i, c);
strip.show();
delay(wait);
}
}
/* Helper functions */
// Create a 24 bit color value from R,G,B
uint32_t Color(byte r, byte g, byte b)
{
uint32_t c;
c = r;
c <<= 8;
c |= g;
c <<= 8;
c |= b;
return c;
}
For example, in the loop() function we call colorWipe(Color(255, 0, 0), 50) which will fill the strand with full-brightness red light, pausing about 50 milliseconds between pixels.
colorWipe(Color(255, 0, 0), 50); // red fill
colorWipe(Color(0, 255, 0), 50); // green fill
colorWipe(Color(0, 0, 255), 50); // blue fill
colorWipe(Color(255, 0, 0), 50); // red fill
colorWipe(Color(0, 255, 0), 50); // green fill
colorWipe(Color(0, 0, 255), 50); // blue fill
