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 Matrix8x8x2.
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.
import board from adafruit_ht16k33.matrix import Matrix8x8x2 i2c = board.I2C() matrix = Matrix8x8x2(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:
matrix = Matrix8x8x2(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 segments. If can be adjusted in 1/16 increments between 0 and 1.0 with 1.0 being the brightest. So to set the display to half brightness, you would use the following:
display.brightness = 0.5
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:
display.blink_rate = 3
Setting Individual Pixels
To set individual pixels to specific colors, you simply treat the matrix object as a multidimensional list and set it to matrix.LED_RED, matrix.LED_GREEN, matrix.LED_YELLOW or matrix.LED_OFF.
matrix[0, 0] = matrix.LED_RED matrix[4, 4] = matrix.LED_GREEN matrix[7, 7] = matrix.LED_YELLOW matrix[7, 0] = matrix.LED_OFF
Filling the Entire Matrix
To fill the entire matrix, just use the fill() function and pass in the color you want to set it to. For instance, if you wanted to set everything to green, you would use:
matrix.fill(matrix.LED_GREEN)
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:
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.
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.
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 and should include pure Green, Red, or Yellow. Anything else will be considered to be off. 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:
import board
from PIL import Image
from adafruit_ht16k33 import matrix
matrix = matrix.Matrix8x8x2(board.I2C())
image = Image.open("myimage.png")
matrix.image(image)
