In CircuitPython, a terminal refers to a text-based interface used for interacting with the microcontroller. It's a way to send commands to and receive output from your CircuitPython board, often through a serial connection over USB. This interface is essential for tasks like debugging, viewing program output, and interacting with the REPL (Read-Eval-Print Loop).
- Serial Console: The serial console, accessed via a terminal, displays output from your CircuitPython board, including print statements and error messages.
- REPL: The REPL is an interactive environment where you can type and execute CircuitPython code directly on the board. The terminal provides the means to access and interact with the REPL.
-
terminalio Module:The
terminaliomodule in CircuitPython allows you to display text on aTileGrid(a display element) using a specific font, often with ANSI control codes. -
ANSI/VT100 Commands: ANSI/VT100 is a standard for text-based communication, and
terminaliouses it to manage cursor position, text color and other display elements (seeadafruit_color_terminalfor the best ANSI emulation). - Examples: You might use a terminal to view the output of
print()statements in your code, troubleshoot errors, or interact with the REPL for quick testing.
Terminal and terminalio
Writes to the Terminal are done with terminalio.write(). Unlike print or Label.label, write places text at the bottom of the display, unless there are ANSI/VT100 Escape Codes embedded in the text to move the cursor to a desired location. See Read The Docs for additional information.
Note as of version 10.0.0.alpha.8, terminalio.Terminal only accepts the built-in font terminalio.FONT or LVGL fonts.
The code examples below show how to use a Terminal with the terminalio.FONT built-in font and a custom Terminal LVGL font:
terminalio.Terminal.write writes to the bottom of the TileGrid. That is unless an ANSI cursor move code is used prior to writing to move the text location.
The color changing ANSI escape codes in terminalio.Terminal currently allow only one color for the text on screen. If you need more than one color, use the adafruit_color_terminal library.
Below is a simple Terminal program which uses the built-in terminal.FONT.
# SPDX-FileCopyrightText: Copyright (c) 2021 Randall Bohn (dexter)
# SPDX-FileCopyrightText: Copyright (c) 2021 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT
#
# Simple terminalio.Terminal use with the built-in terminalio.FONT
# for a DVI display from an RP2350 HSTX connection
#
# Modeled on https://github.com/circuitpython/CircuitPython_Module_Examples/
# blob/801475f745fe2a61738f1abed3bd01007118efa3/terminalio/
# terminalio_terminal_example.py#L5
import board
import displayio
import terminalio
import picodvi
import framebufferio
displayio.release_displays()
# Set up a 320x240x8 bit display space
fb = picodvi.Framebuffer(320, 240, clk_dp=board.CKP, clk_dn=board.CKN,
red_dp=board.D0P, red_dn=board.D0N,
green_dp=board.D1P, green_dn=board.D1N,
blue_dp=board.D2P, blue_dn=board.D2N,
color_depth=8)
display = framebufferio.FramebufferDisplay(fb)
group = displayio.Group()
display.root_group = group
palette = displayio.Palette(2) # A simple color palette
palette[0] = 0x220000 # not so dark Black
palette[1] = 0x00FFFF # Cyan
ROWS = 12
COLS = 40
w, h = terminalio.FONT.get_bounding_box()
termgrid = displayio.TileGrid(
terminalio.FONT.bitmap,
pixel_shader=palette,
y=20,
width=COLS,
height=ROWS,
tile_width=w,
tile_height=h,
)
group.append(termgrid)
term = terminalio.Terminal(termgrid, terminalio.FONT)
term.write("Terminal %dx%d:\r\n" % (COLS, ROWS))
term.write(" %dx%d pixels.\r\n" % (COLS * w, ROWS * h))
term.write("Both carriage return and line feed \r\n are required.\r\n")
while True:
pass
Here is an example of using an LVGL font in Terminal instead of the built-in font:
# SPDX-FileCopyrightText: Copyright (c) 2025 Tim C for Adafruit Industries
# SPDX-FileCopyrightText: Copyright (c) 2025 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT
#
# Make a simple terminalio.Terminal using an LVGL .bin font
# Shows use of required OnDiskFont function
#
import gc
from terminalio import Terminal
import displayio
from lvfontio import OnDiskFont
from adafruit_fruitjam.peripherals import request_display_config
import supervisor
# Use the easy library call to set the resolution
request_display_config(640, 480)
print(f"\nfree: {gc.mem_free()}")
# Initialize display
main_group = displayio.Group()
display = supervisor.runtime.display
display.root_group = main_group
print(f"free: {gc.mem_free()}")
font = OnDiskFont("fonts/cp437_16h.bin") # LVGL .bin font
char_size = font.get_bounding_box()
print(f"Character size: {char_size}")
screen_size = (display.width // char_size[0], display.height // char_size[1])
print(f"Screen size: {screen_size}")
terminal_palette = displayio.Palette(2)
terminal_palette[0] = 0x000000
terminal_palette[1] = 0xFFFFFF
print(f"free: {gc.mem_free()}")
terminal_area = displayio.TileGrid(
bitmap=font.bitmap,
width=screen_size[0],
height=screen_size[1],
tile_width=char_size[0],
tile_height=char_size[1],
pixel_shader=terminal_palette,
)
main_group.append(terminal_area)
terminal = Terminal(terminal_area, font)
message = " Hello World\n This is LVGL text\r\n "
terminal.write(message)
while True:
pass
Page last edited July 16, 2025
Text editor powered by tinymce.
