Usb ws2812

The USB_WS2812 board

This is the documentation page for the USB_WS2812 board. That you can buy in the BitWizard shop.

Overview

This board enables you to drive up to 600 WS2812 fullcolor RGB leds. These leds are sometimes called "neopixels". The board can drive up to 75 leds in in 8 strings. Due to the way things are implemented it is not possible to drive a single string of say 600 leds. Furthermore you would not want that: for each led on a string there is a fixed amount of time necessary for sending its data. Too many leds and the refresh rate has to drop!

Assembly instructions

None: the board comes fully assembled.

External resources

Datasheets

The datasheet of the WS2812B chip/led.

Pinout

The USB connector is a standard micro USB connector.

Pinout of the 16-pin header:

function	pin	pin	function
GND	1	2	D0	Data for led-chain 0.
GND	3	4	D1	Data for led-chain 1.
GND	5	6	D2	Data for led-chain 2.
GND	7	8	D3	Data for led-chain 3.
GND	9	10	D4	Data for led-chain 4.
GND	11	12	D5	Data for led-chain 5.
GND	13	14	D6	Data for led-chain 6.
GND	15	16	D7	Data for led-chain 7.

Note, pin one of this connector is bottom-right when the logo is right-side up. Pin 16 is top-left. All the pins on the right are all ground, the pins on the left are the data pins.

Or closer resembling the layout on the board:

function	pin	pin	function
D7	16	15	GND	two pins for led-chain 7.
D6	14	13	GND	two pins for led-chain 6.
D5	12	11	GND	two pins for led-chain 5.
D4	10	9	GND	two pins for led-chain 4.
d3	8	7	GND	two pins for led-chain 3.
D2	6	5	GND	two pins for led-chain 2.
D1	4	3	GND	two pins for led-chain 1.
D0	2	1	GND	two pins for led-chain 0.

Each pin controls a number of leds. On the current version that number is 384. On a previous version it was 75. Let's call that number "N". You can configure the number of leds per string up to the maximum of the board.

pin	leds
D0	0 - N-1
D1	N - 2*N -1
D2	2*N - 3 * N-1
D3	3*N - 4 * N-1
D4	4*N - 5 * N-1
D5	5*N - 6 * N-1
D6	6*N - 7 * N-1
D7	7*N - 8 * N-1

There is also a three-pin test-connector. It has Ground-data-VCC as the pinout. The data pin is "D0" on the big connector. This will use the USB-5V for the leds. As each led consumes up to 60mA, you are only allowed to power up 8 leds through this connector before you hit the USB 500mA currentlimit. But this could be an easy way to quickly test led-strips if they work, by programming for example a walking led, you verify each of the leds in sequence.

Please ignore the other connectors on the board. There is SWD: Single Wire Debug. This helps us develop software. For hacking: pin1 is 3V3 and pin 3 is GND. There is also a connector SPI. This was meant to allow this board to prototype getting the led-data over SPI, or possibly control other modules over SPI.

wiring

Your WS2812 led string has three wires. One is usually marked "GND" or "V-", one is marked "VCC" or "V+" and the last is the data-in, marked "D", "DI", "I", "IN" or "Din".

Our WS2812 board has a three pin ground-data-vcc connector. This is for "quick test" purposes: The usb powersupply of the board is not able to provide current for more than a few leds (about ten). The quick test connector has pinout ground-data-vcc, just like most WS2812 led strips. If you have the board upright, USB on the left, bitwizard logo correctly oriented, pin 1 is on the right. Take care not to reverse your led strip: It kills the leds instantly.

When you are ready to connect longer strips, you need to have a separate 5V supply for the led strip. Connect the 0 and 5V of the powersupply to the GND (V-) and VCC (V+) of the led strip. Then connect the GND (V-) Of the led strip to the GND of the USB_WS2812 board. And connect the Din of the led strip to one of the data pins on the USB_WS2812 board.

The 8 datalines count from bottom to top, D0..D7. The datalines are on the left (next to the resistors), and the GND for each strip is on the right (next to our logo).

LEDs

There are two leds. One is the power led. It should be lit whenever the USB is connected. The other should blink every two seconds (one second on, one second off).

Button

There is also a button on the board. If you press the button and then power up the board, it will come up in DFU mode, allowing you to upgrade the firmware of the board.

Jumper settings

This board has no jumpers.

Protocol

When you connect the board to your PC or raspberry PI, you will get a virtual com port. You can use your favorite communications program to talk to the device. (I personally use "kermit" because I've been using that for over 30 years. "Minicom" is also a good option)

specifying pixel colors

Adressable leds are starting to appear that have 32 bits driving RGBW 4 different color leds, while the original WS2812 leds have 24 bits driving RGB 3 colored leds.

On a hardware level WS2812 leds want the data in GRB order. Because everybody says "RGB" it is easier to memorize that the order of the colors are RGB. So the board translates this for you.

So when you need to specify a color for a WS2812 (or compatible 24-bit) led, you specify rrggbb: Two hex digits for each color. You may omit leading zeros if you want, to the firmware in your usb-ws2812 it is just a number.

To keep existing software compatible with this, the format for 32-bit leds is WRGB: you specify 8 hex digits, wwrrggbb. Again, leading zeros may be omitted, so when you just specify rrggbb, the white led simply won't be driven.

list of commands

The board supports the following commands:

help

Print a list of supported commands, and also the compilation time of the firmware. You might see a few commands that are there for debugging purposes. Consider those not described here as "do not use".

pix

pix <num> <color>

Set pixel "num" to color "color". Color is specified in 6 hexadecimal digits specifying the color in RGB order. Specifying 102030 will set the red component to 0x10, or about 1/16th of full intensity, the green component to 0x20/0xff or aobut 1/8th of full intensity and blue to about 3/16th.

lshift and rshift

Shift a range of pixels one pixel left (towards the controller) or right (away from the controller).

There are three arguments. The starting position and the number of pixels to involve in the shift and the number of pixels to shift (i.e. shift by 3 pixels). Default is to start at zero and "all pixels", and just one position.

example:

lshift 50 60 3

will shift pixels 50-109 by three pixels. (pixel 50 gets the value from pixel 53, 51 from 54 etc.). The maximum number of pixels you can shift in one go is 10 at the moment.

If you give only one argument, the starting position defaults to zero, if you give two arguments, the first is the starting position the second is the number of pixels.

rainbow

Create a rainbow color effect.

  rainbow [start] [nleds]

will create a rainbow starting at the led "start" and extend over "nleds" leds. The rainbow starts with red, fades via yellow, green, cyan, blue, violet back to red, so it is cyclic.

white

will set all leds to white.

black

will set all leds off (black).

color

sets a fixed color.

 color <color> [start] [nleds]

Sets "nleds" starting at "start" to the color specified by "color".

fade

creates a fade from one color to another color.

 fade <start> <nleds> <color1> <color2>

This is one of the latest commands added. Some of the boards in the field do not have this yet.

uid

print the unique identifier for this board.

Some chips have a Unique identifier on board. This one does. It gets formatted to readable ascii and printed with this command. If you have multiple boards, you can use this to keep them apart.

rbl

Reset to BootLoader.

Should you need to upgrade the firmware, this will Reset the device into the BootLoader. On older versions you had to keep the button pressed while plugging the device into the USB cable. That would still be the recovery procedure if say a firmware is downloaded that crashes before it provides the virtual com port.

bitsperled

Without an argument it will print the current setting. If you provide an argument you can set it. Only 24 and 32 are currently allowed.

write

write the current settings to non volatile memory so that they will apply after the next powercycle. In the past, this module wrote changed settings to flash immediately. However for consistency we're moving to just modifying the active settings with the commands and then requiring a "write" to make these settings permanent.

Currently "bitsperled" is the only setting that requires the write.

Future hardware enhancements

None known yet. (Let us know if you have a request).

Future software enhancements

None known yet.

Changelog

This is the HARDWARE changelog.

1.0

• nov 2015 Initial version

1.1

• dec 2015 minor fixes.

1.2

• dec 2016 added SPI connector.