WS2811/WS2812/WS2812B/APA104/APA106/SK6812 LED String/Strip

WS2811 LED

These are individually addressable RGB LEDs - this means with just 3 wires, you can make each LED turn any one of 16 million colours. They come in many different forms - LED Strings (like above), LED Strip, Matrices like Adafruit's NeoPixels or the RGB123, or even 5mm LEDs. Note that while physically different (some are built into LEDs, some are separate chips), the WS2811/WS2812/WS2812B/APA104/APA106/SK6812 all work the same way electrically.

Part Number Type
WS2811 a separate SOIC8 LED driver chip - often used in LED strings. LED strip with WS2811 may have separate red, green and blue LEDs (buy string on eBay)
WS2812 All-in-one 5050 (5mm x 5mm) RGB LED - 6 pins (hard to buy now)
WS2812B All-in-one 5050 (5mm x 5mm) RGB LED - 4 pins (this is by far the post popular at the moment) (buy on eBay)
APA104 A clone of the WS2812B. All-in-one 5050 (5mm x 5mm) RGB LED - 4 pins. Lights blue when power first applied (buy on eBay)
APA106 All-in-one 5mm or 8mm diameter leaded LED (buy on eBay)
SK6812 All-in-one 3535 (3.5mm x 3.5mm) RGB LED - 4 pins (buy on eBay)

Single WS2811 LED APA106 5mm LED

Above, you can see a single LED. In the LED strings, the WS2811 controller chip is separate to the LED (you can see it as the black blob encased in plastic).

Wiring Up

WS2811-based LEDs need just 3 wires, however because they're a string (and can be chained together), they have two ends. While you can often peer through the casing to see the letters DI (Data In) or DO (Data Out), if you have the LED Strings from the Espruino Kits then the end you need is the 'Female' end (the one without the visible metal spikes in the plug). Included in the kit should be a matching connector so that you can plug and unplug the LED string.

We'd suggest you wire up as follows. The only condition is that the data wire is connected to an SPI MOSI port on the Espruino Board:

LED String Espruino
White (GND) GND
Green (DI / Data In) B15
Red (5V) VBAT

CHECK YOUR WIRING AND DO NOT WIRE UP THE VOLTAGE BACKWARDS - WS2811 chips are quite delicate and the entire string of lights can be easily blown up by doing this.

Software

Note: This is currently covered in the Individually Addressable LEDs tutorial.

To control the LEDs, just send a series of bytes to them. The first 3 bytes are red, green and blue for the first LED, the second are for the second LED, and so on.

SPI2.setup({baud:3200000, mosi:B15});
SPI2.send4bit([255,0,0], 0b0001, 0b0011); // turn first LED Red
SPI2.send4bit([255,0,0, 0,255,0, 0,0,255], 0b0001, 0b0011); // turn first 3 LEDs, Red, Green, and Blue

If you want to control more LEDs (for instance the whole string), we'd recommend using an ArrayBuffer for speed, and to save on memory. Using Uint8ClampedArray also means that any values greater than 255 or less than 0 are 'clamped'. If you used Uint8Array instead than a value would just have the top bits removed, turning 256 into 0, 257 to 1 and so on.

SPI2.setup({baud:3200000, mosi:B15});
// random colours
var arr = new Uint8ClampedArray(25*3);
var n = 0;
for(var i=0;i<25;i++) {
  arr[n++] = Math.random()*255;
  arr[n++] = Math.random()*255;
  arr[n++] = Math.random()*255;
}
SPI2.send4bit(arr, 0b0001, 0b0011);

If you'd like to animate all the colours, you could do something like this:

SPI2.setup({baud:3200000, mosi:B15});
var arr = new Uint8ClampedArray(25*3);
var pos = 0;

function getPattern() {
  pos++;
  for (var i=0;i<arr.length;i+=3) {
    arr[i  ] = (1 + Math.sin((i+pos)*0.1324)) * 127;
    arr[i+1] = (1 + Math.sin((i+pos)*0.1654)) * 127;
    arr[i+2] = (1 + Math.sin((i+pos)*0.1)) * 127;
  }
}

function onTimer() {
  getPattern();
  SPI2.send4bit(arr, 0b0001, 0b0011);
}

setInterval(onTimer, 50);

Using

Buying

WS2811/WS2812Bs can be purchased from many places, as bare parts (not recommended unless you're making your own PCBs), single lights on a breakout board, matrices, and long flexible strips (not to be confused with very similar strips that are not individually addressable). Although WS2811 and WS2812/2812B are different parts, the numbers are used interchangabley in product advertisements. Some sources:

This page is auto-generated from GitHub. If you see any mistakes or have suggestions, please let us know.