CircuitPython and Python Usage

The following section will show how to control the LED backpack from the board's Python prompt / REPL.  You'll walk through how to control the LED display and learn how to use the CircuitPython module built for the display.

First connect to the board's serial REPL so you are at the CircuitPython >>> prompt.

Initialization

First you'll need to initialize the I2C bus for your board.  It's really easy, first import the necessary modules. In this case, we'll use board and Matrix8x8.

Then just use board.I2C() to create the I2C instance using the default SCL and SDA pins (which will be marked on the boards pins if using a Feather or similar Adafruit board).

Then to initialize the matrix, you just pass i2c in.

Download: file
import board
from adafruit_ht16k33.matrix import Matrix8x8

i2c = board.I2C()
matrix = Matrix8x8(i2c)

If you bridged the address pads on the back of the display, you could pass in the address. The addresses for the HT16K33 can range between 0x70 and 0x77 depending on which pads you have bridged, with 0x70 being used if you haven't bridged any of them. For instance, if you bridge only the A0 pad, you would use 0x71 like this:

Download: file
matrix = Matrix8x8(i2c, address=0x71)

Setting the Brightness

You can set the brightness of the display, but changing it will set the brightness of the entire display and not individual pixels. If can be adjusted in 1/16 increments between 0 and 15 with 15 being the brightest. So to set the display to half brightness, you would use the following:

Download: file
display.brightness = 7

Setting the Blink Rate

You can set the blink rate of the display, but changing it will set the brightness of the entire display and not individual pixels. If can be adjusted in 1/4 increments between 0 and 3 with 3 being the fastest blinking. So to set the display to blink at full speed, you would use the following:

Download: file
display.blink_rate = 3

Setting Individual Pixels

To set individual pixels to on, you simply treat the matrix object as a multidimensional list and set it to 1.

Download: file
matrix[0, 0] = 1
matrix[4, 4] = 1
matrix[7, 7] = 1

Filling the Entire Matrix

To fill the entire matrix, just use the fill() function and pass in either 0 or 1 depending on whether you want all pixels off or on. For instance, if you wanted to set everything to on, you would use:

Download: file
matrix.fill(1)

Shifting the Matrix

To shift the pixels on the matrix, there are 5 functions you can use. The main function, called shift(), is used to shift the pixels, up, down, left, right, or even diagonally. By passing a positive number, it will shift the pixels right/up and passing a negative number will shift them left/down. For instance:

Download: file
matrix.shift(2, 0)	# shift pixels to the right by 2
matrix.shift(-1, 0)	# shift pixels to the left by 1
matrix.shift(0, -3)	# shift pixels down by 3
matrix.shift(-2, 2)	# shift pixels left by 2 and up by 2

You can pass True as a third parameter to loop all the pixels that get shifted off over to the other side.

Download: file
matrix.shift(2, 0, True)	# loop pixels to the right by 2
matrix.shift(-1, 0, True)	# loop pixels to the left by 1
matrix.shift(0, -3, True)	# loop pixels down by 3
matrix.shift(-2, 2, True)	# loop pixels left by 2 and up by 2

Additionally, there are a few convenience functions that will shift the pixels by one. These can also be passed a value of True to loop the pixels.

Download: file
matrix.shift_up()		# Shift pixels up
matrix.shift_left()		# Shift pixels left
matrix.shift_down()		# Shift pixels down
matrix.shift_right()		# Shift pixels right
matrix.shift_up(True)		# Loop pixels up
matrix.shift_left(True)	# Loop pixels left
matrix.shift_down(True)	# Loop pixels down
matrix.shift_right(True)	# Loop pixels right

Displaying an Image (Pillow Only)

Additionally, when using with the Raspberry Pi, you can use the Pillow library to display an image to the Matrix. The image will need to be the same exact size as the Matrix. In this case, it should be 8x8 pixels. As an example, you can save the image below as myimage.png.

Then if you want to display the image called myimage.png, you would use something like this:

Download: file
import board
from PIL import Image
from adafruit_ht16k33 import matrix

matrix = matrix.Matrix8x8(board.I2C())

image = Image.open("myimage.png")
matrix.image(image)
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 Mar 27, 2020.