CircuitPython

Adafruit CircuitPython Module Install

To use the LED backpack with your Adafruit CircuitPython board you'll need to install the Adafruit_CircuitPython_HT16K33 module on your board. Remember this module is for Adafruit CircuitPython firmware and not MicroPython.org firmware!

First make sure you are running the latest version of Adafruit CircuitPython for your board.  Next you'll need to install the necessary libraries to use the hardware--read below and carefully follow the referenced steps to find and install these libraries from Adafruit's CircuitPython library bundle.

Bundle Install

For express boards that have extra flash storage, like the Feather/Metro M0 express and Circuit Playground express, you can easily install the necessary libraries with Adafruit's CircuitPython bundle.  This is an all-in-one package that includes the necessary libraries to use the LED backpack display with CircuitPython.  To install the bundle follow the steps in your board's guide, like these steps for the Feather M0 express board.

Remember for non-express boards like the Trinket M0, Gemma M0, and Feather/Metro M0 basic you'll need to manually install the necessary libraries from the bundle:

  • adafruit_ht16k33
  • adafruit_bus_device
  • adafruit_register

If your board supports USB mass storage, like the M0-based boards, then simply drag the files to the board's file system. Note on boards without external SPI flash, like a Feather M0 or Trinket/Gemma M0, you might run into issues on Mac OSX with hidden files taking up too much space when drag and drop copying, see this page for a workaround.

If your board doesn't support USB mass storage, like the ESP8266, then use a tool like ampy to copy the file to the board. You can use the latest version of ampy and its new directory copy command to easily move module directories to the board.

Before continuing make sure your board's lib folder or root filesystem has at least the adafruit_ht16k33adafruit_bus_device, and adafruit_register folders/modules copied over.

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.  As a reference be sure to see the Adafruit HT16K33 module documentation too.

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

I2C Initialization

First you'll need to initialize the I2C bus for your board.  First import the necessary modules:

import board
import busio as io

Note if you're using the ESP8266 or other boards which do not support hardware I2C you need to import from the bitbangio module instead of busio:

import board
import bitbangio as io

Now for either board run this command 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):

i2c = io.I2C(board.SCL, board.SDA)

LED Matrix

To use a LED matrix you'll first need to import the adafruit_ht16k33.matrix module and create an instance of the appropriate Matrix class.  There are three classes currently available to use:

  • Matrix8x8 - This is for a simple 8x8 matrix (square or round pixels, they're both the same driver and code).
  • Matrix16x8 - This is for a 16x8 matrix (i.e. double the width of the 8x8 matrices).  For the LED Matrix FeatherWing you want to use this Matrix16x8 class.
  • Matrix8x8x2 - This is for a 8x8 bi-color matrix.

For example to use the Matrix16x8 class import the module and create an instance with:

import adafruit_ht16k33.matrix 
matrix = adafruit_ht16k33.matrix.Matrix16x8(i2c)

The above command will create the matrix class using the default I2C address of the display (0x70).  If you've changed the I2C address (like when using multiple backpacks or displays) you can override it in the initializer using an optional address keyword argument.

For example to create an instance of the Matrix8x8 class on address 0x74:

matrix2 = adafruit_ht16k33.matrix.Matrix8x8(i2c, address=0x74)

You might notice the matrix turns on to a 'jumbled' collection of random LEDs.  Don't worry!  The display isn't broken, right now the module that controls it doesn't clear the display state on startup so you might see noise from random memory values.

To clear the display and turn all the pixels off you can use the fill command with a color of 0 (off):

matrix.fill(0)
matrix.show()

Notice you must call the show function after calling fill to make the changes visible.  All of the LED backpack library operations operate on a buffer in memory and must be pushed to the display by calling show.  Don't forget any time you want an update to be visible on the display call show!

To turn all the pixels on you can use fill with a color of 1 (on):

matrix.fill(1)
matrix.show()

If you're using the bi-color matrix you can even use a fill color of 2 or 3 to change to different colors of red, green, and yellow (red + green).

Next you can set pixels on the display using the pixel property.  This property has the following parameters:

  • X position - X position of the pixel on the matrix.
  • Y position - Y position of the pixel on the matrix.
  • Color - 0 for off, 1 for on (or one of the LEDs for bi-color display), 2 or 3 for other bi-color display colors.

and the general way to set a pixel is:

matrix.pixel[x,y] = color

For example to set the first pixel at position 0, 0 to on:

matrix.pixel[0, 0] = 1
matrix.show()

Don't forget to call show to make the pixel visible!

Or to set the opposite corner pixel at position 7, 7 to on:

matrix.pixel[7, 7] = 1
matrix.show()

That's all there is to controlling the pixels on a LED matrix!  Right now the matrix library is simple and only exposes basic pixel control.  In the future more advanced drawing commands might be avaialable.

Brightness and Blinking

You can change the brightness of the entire display with the brightness property.  This property has a value from 0 to 15 where 0 is the lowest brightness and 15 is the highest brightness.  Note that you don't need to call show after calling brightness, the change is instant.

For example to set the brightness to the minimum:

matrix.brightness = 0

Or to set it back to maximum:

matrix.brightness = 15

You can also make the entire display blink at 3 different rates using the blink_rate property, which has a value 0 to 3:

  • 0 = no blinking
  • 1 = fast blinking (~once a 1/2 second)
  • 2 = moderate blinking (~once a second)
  • 3 = slow blinking (~once every 2 seconds)

Again you don't need to call show after setting the blink rate, the change will immediately take effect.

For example to blink quickly:

matrix.blink_rate = 1

And to stop blinking:

matrix.blink_rate = 0

LED 7-segment Display

To use a 7-segment display you'll first need to import the adafruit_ht16k33.segments module and create an instance of the Seg7x4 class.

import adafruit_ht16k33.segments
display = adafruit_ht16k33.segments.Seg7x4(i2c)

The above command will create the 7-segment class using the default I2C address of the display (0x70).  If you've changed the I2C address (like when using multiple backpacks or displays) you can override it in the initializer using an optional address keyword argument.

For example to create an instance of the Seg7x4 class on address 0x74:

display = adafruit_ht16k33.Seg7x4(i2c, address=0x74)

You might notice the display turns on to a 'jumbled' collection of random LEDs.  Don't worry!  The display isn't broken, right now the module that controls it doesn't clear the display state on startup so you might see noise from random memory values.

To clear the display and turn all the LEDs off you can use the fill command with a color of 0 (off):

display.fill(0)
display.show()

Put Characters

You can put a numeric value in any of the display's 4 positions with the put function.  For example to set position 0 to the number 1 and position 1 to the number 2 call:

display.put('1', 0)
display.put('2', 1)
display.show()

The put function takes these parameters:

  • The character to display - This needs to be a string and not an integer or number.
  • The position to place the character - This can be a value of 0, 1, 2, or 3.

Remember to call show to make the change visible!

You can also pass some special characters to display to the put function:

  • Colon - Use ':' to turn the colon on, you don't need to specify the position parameter.  To turn the colon off you must currently clear the entire display with fill as shown above.
  • Period / decimal point - Use '.' to turn a decimal point on at the specified position.  To turn the decimal point off set the character at the same position again (the decimal point will not be preserved).
  • Hex character - Use a character 'a' through 'f' to display a high hex character value at a specified position.

Display Numbers and Hex Values

There are also functions to display a number or hex value for convenience.  Remember the display only has 4 digits so a best effort will be made to display the number--you might need to round the number or adjust it to fit!

To display a number call the number function with an integer or floating point value:

display.number(1234)
display.show()
display.number(3.141)
display.show()

Or to display a hex value call the hex function with the value (remember only 4 digits are available so values from 0x0000 to 0xFFFF):

display.hex(0xFEED)
display.show()

You can also adjust the brightness and blinking of the 7-segment display just like with the matrix display above.  See the matrix brightness and blinking section for details on the functions to call.

LED 14-segment Quad Alphanumeric Display

To use a 14-segment quad alphanumeric display it's almost exactly the same as the 7-segment display, but with a slightly different class name.  Import the adafruit_ht16k33.segments module again but this time create an instance of the Seg14x4 class.

import adafruit_ht16k33.segments
display = adafruit_ht16k33.segments.Seg14x4(i2c)

The above command will create the 14-segment class using the default I2C address of the display (0x70).  If you've changed the I2C address (like when using multiple backpacks or displays) you can override it in the initializer using an optional address keyword argument.

For example to create an instance of the Seg14x4 class on address 0x74:

display = adafruit_ht16k33.segments.Seg14x4(i2c, address=0x74)

You might notice the display turns on to a 'jumbled' collection of random LEDs.  Don't worry!  The display isn't broken, right now the module that controls it doesn't clear the display state on startup so you might see noise from random memory values.

To clear the display and turn all the LEDs off you can use the fill command with a color of 0 (off):

display.fill(0)
display.show()

To use the display you can use the put function just like with the 7-segment display.  However the put function for the 14-segment display can take any alphanumeric character.  For example to write 'hi' to the display:

display.put('C', 0)
display.put('I', 1)
display.put('P', 2)
display.put('Y', 3)
display.show()

You can also display numbers and hex values just like with the 7-segment display using the numberand hex function.

However you can also display a text string with the text function.  Remember there are only 4 characters available so keep the message short!  For example to write 'mpy!':

display.text('CPY!')
display.show()

And just like with the 7-segment display you can use the brightness and blink functions just like with the matrices to control those attributes of the display!

Last updated on Jun 19, 2018 Published on May 20, 2016