Allow other fixed fonts for terminals besides terminalio.FONT

[TheKitty]

Currently calling terminal = Terminal(terminal_area, font) only works of the font passed is terminalio.FONT.

Suggest allowing fixed with .bdf fonts to also work, for example:

font = bitmap_font.load_font(font_file)
terminal = Terminal(terminal_area, font)

This would allow terminals for emulation to use font specific to the emulation, for example IBM PC Code Page 437 fonts.

[FoamyGuy]

I've looked into this a little and found the following:

terminalio.Terminal does support custom fonts, but only ones initialized with lvfontio.OnDiskFont.

Terminal does not currently work with any fonts that are loaded via adafruit_bitmap_font. I tried for a bit to make that work with some modifications on both sides but was unsuccessful in the end. The crux of the problem is that fonts loaded by adafruit_bitmap_font do not have a bitmap property that contains a Bitmap with the font characters in it whereas terminalio.FONT does, and lvfontio.OnDiskFont has a bitmap that gets used as a cache and serves the same purpose as far as Terminal class is concerned. Terminal when created takes both a font instance, and a TileGrid, the TileGrid must have a Bitmap assigned to it when it is created.

A few possible routes that come to mind for me as options for making it work are:

1. Modify adafruit_bitmap_font to (optionally?) have a Bitmap that stores glyph bitmaps as they are used in a way that terminalio.Terminal inside the core could then be updated around here:

   circuitpython/shared-module/terminalio/Terminal.c

   Lines 30 to 59 in e3c5548

   	#if CIRCUITPY_LVFONTIO
   	if (mp_obj_is_type(font, &lvfontio_ondiskfont_type)) {
   	// For LV fonts, we need to cache the glyph first
   	lvfontio_ondiskfont_t *lv_font = MP_OBJ_TO_PTR(font);
   	bool full_width = false;
   	int16_t slot = common_hal_lvfontio_ondiskfont_cache_glyph(lv_font, codepoint, &full_width);
   	if (is_full_width != NULL) {
   	*is_full_width = full_width;
   	}
   	if (slot == -1) {
   	// Not found or couldn't cache
   	return 0xffff;
   	}
   	return (uint16_t)slot;
   	}
   	#endif
   	#if CIRCUITPY_FONTIO
   	if (mp_obj_is_type(font, &fontio_builtinfont_type)) {
   	// Use the standard fontio function
   	fontio_builtinfont_t *fontio_font = MP_OBJ_TO_PTR(font);
   	uint8_t index = fontio_builtinfont_get_glyph_index(fontio_font, codepoint);
   	if (index == 0xff) {
   	return 0xffff;
   	}
   	return index;
   	}
   	#endif

   to handle. This could be tricky because the other types being checked for are core types that exist in the C code, whereas the fonts loaded by adafruit_bitmap_font are Python types that don't exist in the C code as far as I understand.

2. Make a new kind of Terminal class, perhaps in pure python, but maybe in the core if needed. It could be implemented to use a full size single Bitmap that is the size of the display or Terminal rather than a TileGrid with one tile for every character position. With this approach it wouldn't need to have a loaded "master" bitmap that contains all of the glyphs like with terminalio.FONT and faked with lvfontio.OnDiskFont. Instead it could blit from the Glpyh.bitmap into the Terminals bitmap at the appropriate location. It would be "more work" than simply setting a tile index, but would allow it to use get_glyph() instead of relying on that big Bitmap containing all the characters together.

Usage with OnDiskFont:

This example script illustrates how the Terminal can be used with lvfontio.OnDiskFont

import gc

import terminalio
from displayio import Group, TileGrid, Palette
from terminalio import Terminal, FONT
from lvfontio import OnDiskFont

from adafruit_bitmap_font import bitmap_font
import supervisor
print(f"free: {gc.mem_free()}")
l = [1024] * 512

main_group = Group()
display = supervisor.runtime.display
display.root_group = main_group

print(f"free: {gc.mem_free()}")

# font = FONT
# font = OnDiskFont("fonts/terminal.lvfontbin")
font = OnDiskFont("fonts/goorm_sans_code_16px.bin")

char_size = font.get_bounding_box()
print(f"char_size: {char_size}")
screen_size = (display.width // char_size[0], display.height // char_size[1])

terminal_palette = Palette(2)
terminal_palette[0] = 0x000000
terminal_palette[1] = 0xffffff

print(f"free: {gc.mem_free()}")
terminal_area = 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 = f"Hello World\nsomething else"
terminal.write(message)

while True:
    pass

The font format for these .bin files is from LVGL and is documented here: https://github.com/lvgl/lv_font_conv/tree/master/doc and there is an online converter that can be used to change .ttf files into this format here: https://lvgl.io/tools/fontconverter. To use the converter select a .ttf file, enter a name and backup name for it, select the size you want, and enter the character range to include 0x20-0x7f will get all of visible ASCII. Select the binary output format.

The font used in the code as well as a few others I had success with are in this zip:
lvbin_fonts.zip

I think there may still be some issues with the way that OnDiskFont is parsing some font files, or perhaps it's just that not all .ttf files can work with this. I tried a handful of different ones from fontesk.com and found more that weren't working properly than ones that are. Sometimes they fail to load, other times they load but then crash when the Terminal is created with a tile index out of bounds error stemming from the Terminal constructor. Others load, and let the Terminal be created but either do not show anything, or seem to use a width of 1 or 2 pixels which makes them impractical to actually see. It's possible some of these are created for much higher resolution screens and trying to render them down at 16px height is leading to some weird results.

[TheKitty]

Well @FoamyGuy - using a modified version of your code has got me the closest to using an LVGL font in Terminal. I was able to get rid of the large allocation without issues.

# SPDX-FileCopyrightText: Copyright (c) 2025 Tim C for Adafruit Industries
#
# SPDX-License-Identifier: MIT
#
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"free: {gc.mem_free()}")
# l = [1024] * 512

# Initialize display

main_group = displayio.Group()
display = supervisor.runtime.display
display.root_group = main_group

print(f"free: {gc.mem_free()}")

# font = FONT
# font = OnDiskFont("fonts/terminal.lvfontbin")
font = OnDiskFont("fonts/CP437-8px.bin")

char_size = font.get_bounding_box()
print(f"char_size: {char_size}")
screen_size = (display.width // char_size[0], display.height // char_size[1])

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\nsomething else\r\n "
terminal.write(message)

while True:
    pass

As you can see the line spacing isn't correct/optimal but I had no success tweaking that. In my Terminal test program it works ok.

[FoamyGuy]

@TheKitty can you share the font file? I could try to take a look into this and see if there is a simple fix.

My gut instinct looking at the way it displays is there is some issue with the height measurement, perhaps there are ascender/descender values that aren't being treated properly.

[TheKitty]

Font sent offline

[tannewt]

lvfontio.OnDiskFont is the way to go for this. Regular bitmap fonts don't require them to be monospace. Terminal only works with monospace though.

[tannewt]

Closing this because there is another option besides terminalio.FONT. Please open a new issue for the size problem.

[TheKitty]

@tannewt - @FoamyGuy and I figured out how to write an LVGL font to the screen and then we have explored using that font in a Terminal. My application: A CP437 font in a Terminal for MSDOS emulation. Tim's been doing an IRC client.

The size issue is secondary, fixed with a larger font for now.

Below is a decent Terminal program using such a font. It's very basic but works.

# SPDX-FileCopyrightText: Copyright (c) 2025 Tim C for Adafruit Industries
# SPDX-FileCopyrightText: Copyright (c) 2025 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT
#
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

I was going to wait until you've settled in but you're here so I'll ask:

I'd like to see this example expanded to a full screen bitmap to we can use escape codes to go to any location on screen and write a character or characters in the CP437 font.

Would you have suggestions on where to expand this?

Thanks, Anne

[tannewt]

I'd like to see this example expanded to a full screen bitmap to we can use escape codes to go to any location on screen and write a character or characters in the CP437 font.

I'm not sure what you mean by full screen bitmap. It looks to me like the terminal should be as big as the screen. Terminal should already support escape codes to move the cursor: https://docs.circuitpython.org/en/latest/shared-bindings/terminalio/index.html#terminalio.Terminal

[TheKitty]

Currently I can use escape codes to write at the bottom of the display. The move to x, y code only tends to move horizontally, not vertically.

Would you happen to have a more comprehensive example of using Terminalio.Terminal?

[FoamyGuy]

@TheKitty adding these lines just before the main loop of the example code in your previous message will move the cursor and then write a string at the new location:

move_cursor = chr(27) + "[10;10H"
terminal.write(f"{move_cursor}Moved to somewhere else")

I am not 100% certain of the arguments, I think it's x/y starting from top left of the terminal, so this is 10 characters in from left, and 10 down from top after it moves. But I have not experimented with other values to validate.

[TheKitty]

Most of my time yesterday evening was getting extended characters working. Then I tried to write them at (50,20) and it did the horizontal but not the vertical motion. I tried the fullscreen code with no effect Anne Barela Engineer, Adafruit Industries ***@***.***

…

On Fri, Jul 11, 2025, 12:10 PM foamyguy ***@***.***> wrote: *FoamyGuy* left a comment (adafruit/circuitpython#10448) <#10448 (comment)> @TheKitty <https://github.com/TheKitty> adding these lines just before the main loop of the example code in your previous message will move the cursor and then write a string at the new location: move_cursor = chr(27) + "[10;10H" terminal.write(f"{move_cursor}Moved to somewhere else") I am not 100% certain of the arguments, I think it's x/y starting from top left of the terminal, so this is 10 characters in from left, and 10 down from top after it moves. But I have not experimented with other values to validate. — Reply to this email directly, view it on GitHub <#10448 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOSY4A7JQVHVM5KWJAEW5L3H7VY7AVCNFSM6AAAAACAMYSKLOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTANRTGA4TCOJWGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[FoamyGuy]

I think it may actually be y,x instead of the other way around. "[50;20H" stays at the bottom of the screen because 50 is larger than the number of rows in the terminal.

"[20;50H" moves the cursor to this position: