Skip to content

adafruit_ht16k33

Works with

Any board with I2C. Drives the HT16K33 LED driver chip used in Adafruit's 8x8 LED matrix backpacks, bicolor 8x8 matrices, 7-segment displays, and 14-segment alphanumeric displays.

What it does

Controls HT16K33-based LED matrix and segment display breakouts over I2C. The library provides separate classes for each display type — dot matrix, 7-segment numeric, and 14-segment alphanumeric — each with a purpose-built API. You can set individual pixels, print strings and numbers directly to segment displays, and control brightness and blink rate over the I2C bus.

Installing the library

Copy the adafruit_ht16k33/ folder and adafruit_bus_device/ folder from the bundle's lib/ folder to your board's lib/ folder.

Quick start

import board
import busio
from adafruit_ht16k33.matrix import Matrix8x8
from adafruit_ht16k33.segments import Seg7x4

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

# --- 8x8 LED Matrix ---
matrix = Matrix8x8(i2c)
matrix.brightness = 0.5          # 0.0 to 1.0
matrix.fill(0)                    # clear all pixels
matrix[0, 0] = 1                  # turn on top-left pixel (col, row)
matrix.pixel(3, 3, 1)             # alternate: pixel(col, row, value)

# --- 7-Segment Display ---
display = Seg7x4(i2c)
display.print(42)                 # show an integer
display.print("3.14")             # show a float string with decimal point
display.show()                    # push buffer to hardware (required after print())

Key things you can do

What you want How to do it
Turn on a matrix pixel matrix[col, row] = 1 or matrix.pixel(col, row, 1)
Fill entire matrix matrix.fill(1) to light all, matrix.fill(0) to clear
Set brightness display.brightness = 0.5 (0.0–1.0, applies to any class)
Set blink rate display.blink_rate = 1 (0=off, 1=2Hz, 2=1Hz, 3=0.5Hz)
Print a number to 7-seg display.print(1234) then display.show()
Print text to 14-seg display.print("HELLO") then display.show()
Scroll text on 14-seg display.marquee("Hello World", delay=0.25)
Use bicolor matrix BicolorMatrix8x8(i2c) — pixel values: 0=off, 1=green, 2=red, 3=yellow

Reading the official docs

https://docs.circuitpython.org/projects/ht16k33/en/latest/

The API reference is organized by class: Matrix8x8, Matrix8x8x2 (bicolor), Seg7x4, and Seg14x4. Look there for the full list of characters supported by each segment display class, for the marquee() scrolling method parameters, and for set_digit_raw() if you need to control individual segments manually.

Projects using this library