RGB Pixels are digitally-controllable lights you can set to any color, or animate. Each pixel contains an RGB LED and a controller chip molded into a 'dot' of silicone, with flanges so they can be pushed into holes in thin sheet material. The dots are waterproof and rugged — they're typically used to make outdoor signs.

12mm RGB pixels come in two different shapes: “bullet” (thin) and “square” (flat). Both use the same type of LED, driver chip and data protocols…the main difference is how they can be mounted: bullets fit better into narrow spaces, while squares are better suited to shallow spaces.

Both types use an 8mm diffused RGB LED (“12mm” refers to the size of the mounting hole for installation) — diffused pixels mix colors nicer. At 5 volts, they draw a maximum of 60 milliamps per pixel: 20 mA each for red, green and blue.

The LED pixels are spaced along a strand of ribbon cable, with about 3 inches (75mm) between pixels. If additional distance is needed you can cut the ribbon cable and solder 4 wires to extend the gap to the desired length.

Each pixel contains a small microchip within the silicone dot. The WS2801 LED driver chip is custom designed for this purpose. We provide an Arduino library for communicating with the pixels (explained in subsequent pages), but if you want to write your own code for other microcontrollers, they’re very easy to communicate with using an SPI-like protocol. For each pixel, one “shifts out” 24 bits of color information — the first data out corresponds to the pixel closest to the microcontroller. To write colors to 10 LEDs, you would issue 240 bits (10 * 24). Following the data, a 500 microsecond pause will then “latch” the data and display the new LED colors.

These pixels could be used for stuff like…

An LED coffee table (this one was “hand made” some time ago…now you could simply use a long strand of our LED pixels and skip the complicated wiring and driver parts):

A trippy “light bar”:

Signs and displays:

A ball of LEDs:

When running a lot of LEDs, it’s important to keep track of power usage. Individual LEDs don't get very hot or use tons of power, but they add up fast!

Each single 12mm RGB LED pixel can draw up to 60mA from a 5V supply. That means a strand of 25 can use up to 1.5 Amps. That’s a peak rate, which assumes that all the LEDs are on at full brightness. If most of the LEDs are kept dim or off (as when animating patterns), the power usage can be 1/3 this or less.

As shown in the previous wiring diagram, connect ground to both your power supply and microcontroller. Then connect the 5V line from the power supply to the red wire on the LED strand.

We suggest a nice switching supply for driving LED pixels:

Tips for powering pixel strands:

• When linking multiple strands together, power should be split and applied to each strand. If you try to power too many LEDs from just one end of the strand, they’ll start to “brown out” the further they are from the power supply.
• Strands can be powered from either end — “input” and “output” doesn’t apply to power, only the data signals from the microcontroller.
• If the 10 Amp power supply isn’t large enough for your project, a slightly modified ATX computer power supply can provide 30 Amps to power upwards of 500 pixels!
• Generally speaking, you should not try to power an LED strand from the Arduino’s 5V line. This is okay if just a few pixels are lit, but is not adequate for driving a full strand.
  
• For a standalone application (not USB connected to a computer), you can power the Arduino from the same regulated 5V supply as the LEDs — connect to the 5V pin on the Arduino, not Vin, and don’t use the DC jack on the Arduino.
• Remember to insulate or trim any unused, exposed power wires!

The “magic” of these pixels is that they're digitally controlled…even though there are only two control lines, you can have as many pixels as you’d like in a single long strand, yet each remains independently controllable.

Though it looks like the 4-conductor ribbon cable is continuous, it isn't! The pixels have a distinct “in” and “out” side. Data from the microcontroller arrives on the input side, where it’s received by the driver chip. The output side then connects to the input of the next pixel, all the way down the line.

The way to tell input from output is different among the shape and version of the pixels you’re using:

Our LED pixels now include plugs for joining multiple strands and to simplify connection to a microcontroller:

The extra red and blue wires (the exposed ones not inside a connector) are for power — we’ll explain that in the next section.

Connecting to Arduino

To use our example code for Arduino, connect the yellow wire (serial data) to Arduino pin 2 and the green wire (serial clock) to pin 3. The software can be configured to use other pins, but we recommend using this arrangement when starting out, so that everything is tested in a known configuration. The blue wire (ground) should be connected to any of the Arduino GND pins.

Install Arduino Libraries

We have example code ready to go for use with the LEDs. It's written for Arduino, which should be portable to any microcontroller by adapting the C++ source.

Only one library need to be installed using the Arduino Library Manager…this is the preferred and modern way. From the Arduino “Sketch” menu, select “Include Library” then “Manage Libraries…”

Type “adafruit ws2801” in the search field to quickly find the library — Adafruit WS2801 Library:

After restarting the Arduino software, you should see a new example folder called Adafruit WS2801 Library, and inside, an example called strandtest.

Example Code

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);

1
2
3
4
5

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);

Next, we initialize the strip in the setup() procedure:

void setup() {
 
  strip.begin();
 
  // Update LED contents, to start they are all 'off'
  strip.show();
}

1
2
3
4
5
6
7

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;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// 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

1
2
3

  colorWipe(Color(255, 0, 0), 50);  // red fill
  colorWipe(Color(0, 255, 0), 50);  // green fill
  colorWipe(Color(0, 0, 255), 50);  // blue fill

It's easy to use the 12mm LED pixels with CircuitPython and the Adafruit CircuitPython WS2801 module.  This module allows you to easily write Python code to control the lights.

You can use these LEDs with any CircuitPython microcontroller board or with a computer that has GPIO.

CircuitPython Wiring

You can wire up the WS2801 strand for CircuitPython and using any two GPIO pins. One will serve as the clock Pin and one as the Data Pin.

Python Wiring

Wiring for Python is pretty simple as well.

Hardware SPI Wiring on the Raspberry Pi

The Raspberry Pi seem to be an exception in that Hardware SPI seems to work pretty well on here.

CircuitPython Setup

To use the 12mm LED Pixels with your Adafruit CircuitPython board you'll need to install the Adafruit CircuitPython WS2801 module on your 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.

If you choose, you can manually install the libraries individually on your board:

• adafruit_ws2801

Before continuing make sure your board's lib folder or root filesystem has the adafruit_ws2801.mpy file copied over. You should now be ready to go!

Python Setup

You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling SPI on your platform and 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!

Python Installation of WS2801 Library

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

• pip3 install adafruit-circuitpython-ws2801

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!

If that complains about pip3 not being installed, then run this first to install it:

• sudo apt-get install python3-pip

The 12mm LED pixels are really easy to use with CircuitPython and the Adafruit CircuitPython WS2801 module.

Initialization

Whether you connected the LED Pixels to your microcontroller through the Hardware SPI or Software SPI, initialization is about the same.

import board
import adafruit_ws2801

odata = board.D5
oclock = board.D6
numleds = 25
bright = 1.0
leds = adafruit_ws2801.WS2801(oclock, odata, numleds, brightness=bright, auto_write=False)

1
2
3
4
5
6
7
8

import board
import adafruit_ws2801

odata = board.D5
oclock = board.D6
numleds = 25
bright = 1.0
leds = adafruit_ws2801.WS2801(oclock, odata, numleds, brightness=bright, auto_write=False)

In this example, we are using D5 and D6, which are for driving it through software. If we were driving it through hardware on the Raspberry Pi, we would use the following Pins:

odata = board.MOSI
oclock = board.SCK

1
2

odata = board.MOSI
oclock = board.SCK

Make sure the number of LEDs corresponds to the actual number that you had. For instance, if you had two strands of 25 LEDs, that's 50 LEDs.

You can adjust the brightness by changing the number between 0 and 1.0. Setting it lower than one requires a little more processor power because to achieve that effect, they need to rapidly turned on and off.

If you didn't want to have to call show() in order to update the strand, you could either set auto_write to True or remove it from the initializer altogether.

Showing Changes

If auto_write is set to False, you will need to call show() in order to show any changes you made to the lights:

leds[0] = 0xff0000
leds.show()

1
2

leds[0] = 0xff0000
leds.show()

Filling All Lights At Once

You can fill all the lights at once with the fill command. The color can either be a tuple of Red, Green, and Blue as a number between 0-255 each, a hexadecimal number in the format of 0xRRGGBB:

# Use an RGB Tuple
leds.fill((255, 0, 0))

# Use a Hexidecimal Value
leds.fill(0xff0000)

1
2
3
4
5

# Use an RGB Tuple
leds.fill((255, 0, 0))

# Use a Hexidecimal Value
leds.fill(0xff0000)

Setting an individual LED

You can set the value of a single LED by passing a color value as a tuple or hexadecimal value to an index:

leds[0] = (0, 0, 255)	# Set the first LED blue
leds[1] = 0x00ff00	# Set the second LED Green

1
2

leds[0] = (0, 0, 255)	# Set the first LED blue
leds[1] = 0x00ff00	# Set the second LED Green

Setting Multiple Values

You can set multiple values at the same time using a slice. For instance, if you wanted to set the first three LEDs to Red, Green, and Blue, you could type the following:

leds[0:3] = ((255, 0, 0),
             (0, 255, 0),
             (0, 0, 255))

1
2
3

leds[0:3] = ((255, 0, 0),
             (0, 255, 0),
             (0, 0, 255))

Getting a Value

Just like you can set the LEDs, you can also read the current value of the LEDs. The value will be returned as a Tuple:

leds[0] = 0xff0000
leds[1] = 0x00ff00
leds[2] = 0x0000ff

my_color = leds[0] # Returns (255, 0, 0)

my_colors = leds[0:3] # Returns [(255, 0, 0), (0, 255, 0), (0, 0, 255)]

1
2
3
4
5
6
7

leds[0] = 0xff0000
leds[1] = 0x00ff00
leds[2] = 0x0000ff

my_color = leds[0] # Returns (255, 0, 0)

my_colors = leds[0:3] # Returns [(255, 0, 0), (0, 255, 0), (0, 0, 255)]

Setting the Brightness

You can change the brightness of all the lights by changing the brightness property and setting it between 0 and 1.0:

leds.brightness = 0.5    # Set to 50% Brightness

1

leds.brightness = 0.5    # Set to 50% Brightness

With just this handful of commands, you can do some cool effects and animations. Having the auto_write set to False makes adding cool effects even easier because you can change each light and then call show() to make all changes visible at once. You could do some cool animations this way. You could even get values and set other values up the chain for a shifting lights effect.

Full Example Code

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

### Based on example from
### https://github.com/adafruit/Adafruit_CircuitPython_DotStar/tree/master/examples

import random
import time

import board

import adafruit_ws2801

### Example for a Feather M4 driving 25 12mm leds
odata = board.D5
oclock = board.D6
numleds = 25
bright = 1.0
leds = adafruit_ws2801.WS2801(oclock, odata, numleds, brightness=bright, auto_write=False)

######################### HELPERS ##############################


# a random color 0 -> 224
def random_color():
    return random.randrange(0, 7) * 32


######################### MAIN LOOP ##############################
n_leds = len(leds)
while True:
    # fill each led with a random color
    for idx in range(n_leds):
        leds[idx] = (random_color(), random_color(), random_color())

    # show all leds in led string
    leds.show()

    time.sleep(0.25)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

### Based on example from
### https://github.com/adafruit/Adafruit_CircuitPython_DotStar/tree/master/examples

import random
import time

import board

import adafruit_ws2801

### Example for a Feather M4 driving 25 12mm leds
odata = board.D5
oclock = board.D6
numleds = 25
bright = 1.0
leds = adafruit_ws2801.WS2801(oclock, odata, numleds, brightness=bright, auto_write=False)

######################### HELPERS ##############################


# a random color 0 -> 224
def random_color():
    return random.randrange(0, 7) * 32


######################### MAIN LOOP ##############################
n_leds = len(leds)
while True:
    # fill each led with a random color
    for idx in range(n_leds):
        leds[idx] = (random_color(), random_color(), random_color())

    # show all leds in led string
    leds.show()

    time.sleep(0.25)

Many support issues arise from eager users getting ahead of themselves, changing the code and wiring before confirming that all the pieces work in the standard configuration. We recommend always starting out with the examples as shown. Use the pinouts and wiring exactly as in the tutorial, and run the stock, unmodified “strandtest” example sketch. Only then should you start switching things around.

Here are the most common issues and solutions…

There’s a fair amount of variance between pixels due to the rubbery, waterproof coating. The figures given here are just guidelines, rounded up to the next whole millimeter (except for the mounting hole diameter). Allow yourself some extra “wiggle room” for spacing when planning an installation.

For mounting holes, 11.5 millimeters is a good guideline, or might go as narrow as 11 mm for a really firm grip, though at that size pixels will be hard to remove and the mounting flange may take some abuse in the process.

“Bullet” Pixels

“Square” Pixels