Wikijunior:Raspberry Pi/Raspberry Pi Python Individually Controllable LEDs (ws2811)

Tutorial by Andrew Oakley & Jonathan Teague - Public Domain 2020-03-14 www.cotswoldjam.org

This tutorial will cover using individually controllable strings of LEDs based on the ws2811 controller, also known as 'NeoPixels'.

The kit
In your bag you will find the following components:


 * ×3 M-F Jumper leads (pin to socket)
 * ×1 3-way 3A connector strip
 * ×1 String of 3 5V ws2811 LEDs

Putting it together
Step 1: Take the jumper lead that goes to the WHITE wire to the LEDs and plug the socket (female end) into pin 6 (GND) on the Pi.

Step 2: Take the jumper lead that goes to the RED wire to the LEDs and plug the socket (female end) into pin 2 (5V) on the Pi.

Step 3: Take the jumper lead that goes to the GREEN wire to the LEDs and plug the socket (female end) into pin 12 (GPIO 18) on the Pi.



The program
Power up your Raspberry Pi. From the desktop menu, select Programming – Python 3 (IDLE). Then use File, New File to create a new program.

Type in the following program then use File, Save to save your program as the name of your choice (don't forget to put .py on the end).

You can also find this program in the Pi Home folder

Running your program.

To run the program start a Terminal – click the icon on the top then once the terminal window opens type:

If it's worked you should see the 3 LEDs light up red, green and blue for two seconds and then turn off.

What does the program do?
The imports load the NeoPixels libraries (and time so we can insert a delay).

This tells the library we've connected our LED string to GPIO 18, there are 3 LEDs and  means only update the LEDs when we call. Lastly, we note that the colours are in the order Red, Green, Blue (RGB).

This sets the first LED to RED, the 3 values are (R, G, B) – so each of the 3 LEDs lights up a different colour.

This sets all the pixels to 0 which means off, if we don't do this the LEDs will stay on.

What next?
Now do your own thing! Make a disco sequence!

How about a traffic light sequence? Note that yellow light is a mix of red and green light, e.g: (255,255,0)



Hint: Put it in a  block so it goes on forever. And don’t forget to indent your code within the while block like this line is!

Hold down the CTRL key and press C to stop the  sequence.

You can find an example program in the Pi Home folder.

How about a sequence of lights that measures 20 seconds, the time you need to do a good job of washing your hands?

You can find an example program in the Pi Home folder.

If you stop your program and the lights are still on, you can use the  program to turn them off.

How does it work?
Each LED is connected to a ws2811 integrated circuit (IC) – it's the IC that's called a ws2811, the LED is just a three-colour LED. The Pi generates a long sequence of 0's and 1's. 24 bits for each LED (3 sets of 8-bits for each colour Red|Green|Blue), so for our string of 3 LED the Pi will generate 3 × 24 bits = 72 bits.

The first device in the string takes the fist 24 bits and uses those to set the Red|Green|Blue on its LED. It then passes the remaining 48 bits on to the second LED. That in turn takes what are now the first 24 bits from what it has received as its RGB and passes on the remaning 24 bits to the last LED.

For full details the datasheet is here: http://www.world-semi.com/DownLoadFile/129

Making it work at home
If you're not using our ready-made SD card, you need to do some setup from Raspbian Buster:


 * 1) Raspberry menu – Preferences – Raspberry Pi Configuration – Interfaces – SPI enable – I2C enable – OK
 * 2) Raspberry menu – Shutdown – Reboot

Then install the libraries:

You can download our sample code from: www.cotswoldjam.org/downloads/2020-03

Notes on using ws2811 in the real world
We’ve only given you a short string of LEDs as that’s all the Pi can reliably power. If you're using a long strip of ws2811 or ws2812 then there are two things you'll need to consider.


 * 1) ws2811 strips can be 5V or 12V, ws2812 are 5V. The Pi can only provide 5V at a low current sufficient to drive a few LEDs. To drive long strips at 5V or any at 12V you'll need to provide additional power, possibly at multiple points along the strip. If you're going to run a strip all round your bedroom ceiling 😊 then the Pi is only going to provide the control logic for the LEDs not the power.
 * 2) The control logic for ws2811 & ws2812 is specified at 5V, the Pi GPIO pins are 3.3V. For this tutorial we get away with using GPIO but to be sure it's going to work you would probably want to use a logic level shifter to turn the Pi's 3.3V into 5V.