CircuitPython and Python Usage

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.

Download: file
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:

Download: file
odata = board.MOSI
oclock = board.SCK
Although the driver is capable of using Hardware SPI, we recommend not using it because the timing can vary from microcontroller to microcontroller and isn't reliable on certain boards.

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:

Download: file
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:

Download: file
# 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:

Download: file
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:

Download: file
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:

Download: file
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:

Download: file
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

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

import time
import random
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)
This guide was first published on Jul 29, 2012. It was last updated on Jul 29, 2012.
This page (CircuitPython and Python Usage) was last updated on Jun 25, 2020.