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.


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

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 display, you just pass i2c in.

import board
from adafruit_ht16k33.segments import Seg14x4

i2c = board.I2C()
display = Seg14x4(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:

display = Seg14x4(i2c, address=0x71)

If you intend to chain multiple displays together, you will need to alter the address of subsequent boards by bridging the address pins in various combinations. If you have an unsoldered board, and a board with the A0 pad solder-bridged, you would initialize the two displays as follows.

display = Seg14x4(i2c, address=(0x70, 0x71))

To add further displays, ensure the address is different on all of them, and initialize it the same way as above, but add more comma-separated addresses to the address=() tuple.

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 segments. 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

Printing Text

To print text to the display, you just use the print function. So if you want to print ABCD, you would use the following:


Printing Numbers

Printing numbers is done similar to printing text, except without the quotes, though you can still print numbers in a string as well.


Printing Hexidecimal Values

To print hexidecimal values, you use the print_hex function:


Setting Individual Characters

To set individual characters, you simply treat the display object as a list and set it to the value that you would like.

display[0] = '1'
display[1] = '2'
display[2] = 'A'
display[3] = 'B'

Setting Individual Segments

To set individual segments to turn on or off, you would use the set_digit_raw function to pass the digit that you want to change and the bitmask. This can be really useful for creating your own characters. The bitmask corresponds to the following diagram. The highest bit is not used, so an X represents that spot to indicate that.

The bitmask is a 16-bit number that can be passed in as a single Hexidecimal, Decimal, or binary number. It can also be passed in as a list or tuple containing 2 separate 8-bit numbers. Here are some of the ways to set the digits. All of these different methods create a box with an X in the center:

display.set_digit_raw(0, 0x2D3F)
display.set_digit_raw(1, 0b0010110100111111)
display.set_digit_raw(2, (0b00101101, 0b00111111))
display.set_digit_raw(3, [0x2D, 0x3F])

Filling all Segments

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


Scrolling Display Manually

If you want to scroll the displayed data to the left, you can use the scroll() function. You can pass in the number of places that you want to scroll. The right-most digit will remain unchanged and you will need to set that manually. After scrolling, you will need to call the show function. For example if you wanted to print an A and then scroll it over to spaces, you would do the following.

display[3] = " "

Displaying an Automatic Scrolling Marquee

To make displaying long text easier, you can use the marquee function. You just pass it the full string. Optionally, you can pass it the amount of delay between each character:

display.marquee("This is a really long string ")

By default it is 0.25 seconds, but you can change this by providing a second parameter. You can optionally pass False for a third parameter if you would not like to have it loop. So if you wanted each character to display for half a second and didn't want it to loop, you would use the following:

display.marquee('This is a really long string ', 0.5, False)

Full Example

Click Download Project Bundle below to download a full example and necessary libraries to run it.

# SPDX-FileCopyrightText: 2022 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import board
from adafruit_ht16k33 import segments

# Create the display object.
# Display connected to STEMMA QT connector.
display = segments.Seg14x4(board.STEMMA_I2C())
# Display connected to I2C pins.
# display = segments.Seg14x4(board.I2C())  # uses board.SCL and board.SDA

# This section displays four 0's across the display. The code shows four
# different ways to use the set_digit_raw function. Each is labeled below.
# 16-bit Hexadecimal number
display.set_digit_raw(0, 0x2D3F)
# 16-bit Binary number
display.set_digit_raw(1, 0b0010110100111111)
# 8-bit Binary Tuple
display.set_digit_raw(2, (0b00101101, 0b00111111))
# 8-bit Hexadecimal List
display.set_digit_raw(3, [0x2D, 0x3F])

# Delay between.

# Scroll "Hello, world!" across the display. Setting the loop parameter to false allows you to
# tell the marquee function to run only once. By default, marquee loops indefinitely.
display.marquee("Hello, world!", loop=False)

# Delay between.

# Scroll special characters, uppercase and lowercase letters, and numbers across
# the display in a loop. This section will continue to run indefinitely.
display.marquee("".join(chr(character) for character in range(ord("!"), ord("z") + 1)))

This guide was first published on Jul 29, 2012. It was last updated on Sep 28, 2022.

This page (CircuitPython and Python Usage) was last updated on Dec 02, 2023.

Text editor powered by tinymce.