WS2812 Library

1. Intro

WS2812 is a popular RGB LED with built-in controller, easy for use in many projects. The LED can be use singly or a chain. They usually come in strips of 30 or 60 LEDs daisy-chained together.

Data sending to these LED is a bit stream of RGB values. Each LED have 2 data signal, DI and DO. The bit stream comes in DI pin and if more than 24 bits were received, these bits are forward to DO pin, bit by bit, as more data coming into DI pin. Therefore, only 1 signal line is needed to send data to all LEDs in a strip.

The library allows Ansteron Board to send color data to WS2812 from any I/O pin. Data is stored in a buffer (char array), 3 bytes per LED (pixel). User program can manipulate data as needed then buffer reference is passed to library function to send a copy of it to LED(s).

Ansteron Board has enough RAM for about 600 pixels. However, more LEDs can be driven if external memory is added. For example, data can be stored in external EEPROMs. The program will then load data to buffer and send that to each strip. The process is fast enough in most cases since each strip of 60 LEDs is updated in about 2 milliseconds.

Individual WS2812 comes in 6-pin package; W2812b is 4-pin version. Both of them will work with the library. Communication with these LEDs are done at fixed 800Kbps. Ansteron Board must run at 16 MHz to generate correct data signal.

2. Circuit

The circuit below shows typical connection between Ansteron Board and a strip of (or one) WS2812. Be cautioned that each LED will need power supply up to 60 mA at 5V. A strip of 30 LEDs will need 1.8A of total current. External power supply is required for strip of multiple LEDs.

3. Functions

Each strip of W2812 requires a buffer (char array) to hold color data. The size of buffer must be at least 3 times number of LEDs in a strip. The buffer can be either local or global variable but making it global variable to easily access from anywhere in the program.

Note: raw color data stored in buffer is in GRB (Green-Red-Blue) order.


Update data from buffer to LED(s). Input buffer is a char array which holds raw data (3 bytes for each W2812). Input count is the number of WS2812 in the chain (enter 1 if there is only 1 LED connected). Input pin takes the same values as other IO functions (PIN_Bx, PIN_Cx, PIN_Dx).


Fill pixels in buffer with given RGB data. Only data in the buffer is affected. User program should call WS2812_update() after this to sync values in the LEDs with buffer. Color data r, g, and b take values from 0 to 255. Input start is pixel index, counting from 0 (the one closest to Ansteron Board). count is the number of pixel to be filled.


Write color data into a pixel in buffer. index is position of the pixel, counting from 0 (the one closest to Ansteron Board). Color values r, g, and b take values from 0 to 255.


Similar to WS2812_set_pixel() except color value is 32 bit (long). Color format is 0x00RRGGBB.

4. Note

All interrupts are temporally disabled when data is being sent to W2812(s).