Skip to main content

Font Library Usage & Creation

A font library (font module) decides what text looks like on screen. The Firefly T1 firmware ships three font families, and they each map to a different display API: fixed-width bitmap fonts go with text(), variable-width bitmap fonts go with write(), and vector fonts go with draw(). Only ASCII fonts are built in — showing Chinese requires building a small font library of your own, and the last section on this page walks through it.

The three families are not interchangeable

text() takes vga*, write() takes a library generated by font2bitmap, draw() takes a vector font. Mixing them up shows nothing or garbage.

You must generate Chinese fonts yourself

Every built-in font covers ASCII only. Use the PC-side font2bitmap.py to pack just the characters you need into a small module and drop it on the SD card.

Missing glyphs raise no error

Characters absent from a font are silently skipped — the screen simply stays empty. So list every character you use when generating a font.

Three Font Families, Three APIs​

Display APIFont format requiredBuilt into the firmwareCharacteristics
text(font, s, x, y[, fg, bg])Fixed-width bitmap: WIDTH HEIGHT FIRST LAST FONTvga1_* / vga2_* (12 in total)Fixed advance per character, fast, good for body text
write(font, s, x, y[, fg, bg, bg_tuple, fill])Variable-width bitmap: MAP BPP HEIGHT MAX_WIDTH OFFSET_WIDTH WIDTHS OFFSETS BITMAPSNotoSans_32 / NotoSansMono_32 / NotoSerif_32Advance follows the glyph, supports Chinese, can draw over a background image
draw(font, s, x, y[, color, scale])Vector (Hershey): WIDTH HEIGHT FIRST LAST INDEX FONT26 fonts under vector/Drawn from line segments, scales without distortion, good for headings

Telling them apart is easy: open the font file and look at the uppercase constants at the top. FIRST/LAST means a fixed-width bitmap; MAP/MAX_WIDTH means a variable-width library generated by font2bitmap; INDEX/FONT means a vector font.

Built-in Bitmap Fonts (vga1_* and vga2_*)​

The only difference between the two families is the character range; usage is identical. All twelve files can be imported directly, with no need to put them on the SD card.

vga1: 96 Glyphs (ASCII 0x20–0x7F)​

Font fileWidth × HeightNotes
vga1_8x88 × 8Smallest; 30 characters fit on one row in landscape
vga1_8x168 × 16Classic terminal proportions, most commonly used
vga1_16x1616 × 16Double-size text
vga1_16x3216 × 32Large, good for headings
vga1_bold_16x1616 × 16Bold
vga1_bold_16x3216 × 32Bold and large

VGA1 8x8 bitmap font preview

VGA1 bold 16x16 bitmap font preview

vga2: 256 Glyphs (0x00–0xFF)​

Beyond ASCII this also covers tab/box-drawing characters, block graphics and some international characters — handy for drawing table rules or simple shapes.

Font fileWidth × HeightNotes
vga2_8x88 × 8Smallest
vga2_8x168 × 16Common size; the official app uses this one
vga2_16x1616 × 16
vga2_16x3216 × 32
vga2_bold_16x1616 × 16Bold
vga2_bold_16x3216 × 32Bold and large

VGA2 16x16 bitmap font preview

VGA2 bold 16x16 bitmap font preview

Example​

import st7789
import tft_config
import vga2_16x32 as font

tft = tft_config.config(1) # landscape
tft.init()

tft.fill(st7789.BLACK)
tft.text(font, "Hello", 0, 0, st7789.WHITE, st7789.BLACK)

The fg (text color) and bg (block behind the text) arguments of text() can be omitted; they default to white text on a black background. Note that text() is opaque: it writes a full background block for every character, so it is unsuitable for drawing over a background image (it would cover it). To draw text on a background image use write() as described under Image Display.

vga1_* fonts carry only the 96 glyphs from 0x20–0x7F, and characters outside that range are skipped entirely — so displaying Chinese with vga1_* just gives you blank space (for Chinese, build your own font, see below).

Built-in Vector Fonts (26 of Them)​

Vector (Hershey) fonts are glyphs drawn from line segments, so they stay smooth when scaled up, which makes them good for headings or large text. Their character range is also ASCII 0x20–0x7F.

Font filePreview
astrolastrol font
cyrilccyrilc font
gothenggotheng font
gothgergothger font
gothitagothita font
greekcgreekc font
greekcsgreekcs font
greekpgreekp font
greeksgreeks font
italiccitalicc font
italiccsitaliccs font
italictitalict font
lowmatlowmat font
markermarker font
meteometeo font
musicmusic font
romancromanc font
romancsromancs font
romandromand font
romanpromanp font
romansromans font
romantromant font
scriptcscriptc font
scriptsscripts font
symbolsymbol font
uppmatuppmat font

Example​

import st7789
import tft_config
import romans as font

tft = tft_config.config(1)
tft.init()

tft.fill(st7789.BLACK)
tft.draw(font, "Hello", 10, 40, st7789.WHITE, 1.5)

scale defaults to 1.0 and accepts either a float (1.5) or an integer (2). To find out how wide a string will be when drawn, measure it first with draw_len(font, s[, scale]).

Built-in TrueType Fonts (Already Converted to Bitmaps)​

The truetype/ folder holds three directly importable libraries: NotoSans_32, NotoSansMono_32 and NotoSerif_32 (sans-serif, monospace and serif respectively).

They are not TrueType rendered at runtime — they are variable-width bitmap fonts pre-converted with font2bitmap.py, as their own header comment shows:

# Converted from NotoSans-Regular.ttf using:
# ./font2bitmap.py NotoSans-Regular.ttf 32 -c 0x20-0x7f

So they are the same kind of thing as an external Chinese font, and you display them with write():

import st7789
import tft_config
import NotoSans_32 as font

tft = tft_config.config(1)
tft.init()

tft.fill(st7789.BLACK)
tft.write(font, "Hello", 10, 10, st7789.WHITE, st7789.BLACK)
FontCharacter rangeHEIGHTMAX_WIDTH
NotoSans_32ASCII 0x20–0x7F3430
NotoSansMono_32ASCII 0x20–0x7F3419
NotoSerif_32ASCII 0x20–0x7F3430

The .ttf files in the same folder are the source typefaces used for conversion, there for you to build your own font with; they are never parsed on the device.

External Chinese Fonts (Build Your Own)​

How an external Chinese font works

The idea is simple: font2bitmap.py uses the typeface you specify to render the characters from just the phrases you name into bitmaps and emits a Python module. Put that module on the SD card and import it to display Chinese. Because only the characters you use are included, the font file stays small.

Steps​

  1. Download the conversion script: font2bitmap.py. It needs Python 3 and freetype-py:

    pip install freetype-py
  2. Download the sample typeface: NotoSansSC-Regular.zip (unzip before use). You can swap the typeface for any .ttf / .otf you like — this one is only an example.

  3. Open a command prompt, switch to the folder holding the files, and run the conversion command.

Command Format​

python font2bitmap.py [options] font_file height > output.py
OptionDescription
-s "text"Characters to include, given directly as a string, e.g. -s "Hello"
-c rangeCharacters by code point, decimal or 0x hex, e.g. -c 0x20-0x7f, -c "65,66,67" or -c "0x30-0x39, 0x41-0x5a"
--font_width NForce the glyph width; defaults to the same value as the height

-s and -c are mutually exclusive — you must supply exactly one of them.

Doing It​

Unzip the script and the typeface into D:\font, then open a command prompt (Win + R → type cmd → Enter):

Files placed in the D:\font directory

Opening CMD

Switch to that drive and folder first (enter whichever drive holds the files):

Entering drive D

Entering the font folder

Run the conversion to build a 16-pixel-high font from the text you pass in:

python font2bitmap.py -s "Hello" NotoSansSC-Regular.otf 16 > font.py

Running the conversion command

The generated font.py file

The generated font.py contains MAP (the character table), BPP, HEIGHT, MAX_WIDTH, WIDTHS, OFFSETS, BITMAPS and other fields — exactly the format write() expects.

Mixing Chinese and ASCII

-s and -c are mutually exclusive, so to include both Chinese and ASCII put them all into one string: -s "Hello 123".

Example​

  1. Copy the generated font.py to the Firefly T1's /sd/sys/font/ directory (any folder name works as long as the code below matches it).
  2. Add that directory to the module search path, then import it:
import sys
sys.path.append('/sd/sys/font') # the directory holding the font module

import st7789
import tft_config
import font # the font.py generated above

tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)

tft.write(font, "Hello", 0, 0, st7789.WHITE, st7789.BLACK)

In write(), fg is the glyph color and bg is the color of the block behind the text; change them freely:

tft.write(font, "Hello", 40, 100, st7789.YELLOW, st7789.BLUE)

The official light-painting app does exactly this — keep the font library in the app's own directory and add that directory to sys.path:

import sys
sys.path.append('/sd/apps/light-painter/font')
import proverbs_font8x16 as font_C

tft.write(font_C, "Stop:Pause", 5, 90, st7789.BLACK, st7789.WHITE)

Common Pitfalls​

PitfallCause and fix
text() with a custom Chinese font → blank or garbagetext() reads WIDTH / HEIGHT / FIRST / LAST / FONT, and a custom library has none of those fields → use write()
write() with a vga* font → errorwrite() reads MAP / MAX_WIDTH / WIDTHS / OFFSETS / BITMAPS → vga* fonts belong with text()
draw() with a bitmap font → errordraw() needs INDEX / FONT, which only the vector fonts under vector/ provide → bitmap fonts belong with text() / write()
Chinese renders as blankThose characters are not in the font (not included at generation time), or you used vga1_* → list every character you need in -s when you regenerate
Characters past the right edge of the screen never showtext() skips a whole character that would overflow, and never wraps → work out the per-line length yourself from the glyph width
pip install fails when generating a font libraryfreetype-py is missing → run pip install freetype-py before the conversion
The conversion command reports "-s and -c are mutually exclusive"The two options cannot be used at the same time → keep only one, or put all the characters into the -s string
Still an ImportError after sys.path.appendThe path or the filename is wrong → confirm the .py really is in that directory and that the path starts with /sd
NotoSans_32 shows no ChineseThe three built-in TrueType libraries cover ASCII only → Chinese needs a custom font library

More Recipes​

One Line of Chinese, One Line of English​

write() advances by the actual width of each glyph, so mixed scripts leave no big gaps:

import st7789
import tft_config
import NotoSans_32 as font_en
import font_cn # custom Chinese font library

tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)

tft.write(font_cn, "Light Painting", 10, 10, st7789.WHITE, st7789.BLACK)
tft.write(font_en, "LIGHT PAINTING", 10, 50, st7789.YELLOW, st7789.BLACK)

A Scaling Boot Title with a Vector Font​

import st7789
import tft_config
import romans as title

tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)

s = "SOCOLODE"
for scale in (1, 2, 3):
x = (tft.width() - tft.draw_len(title, s, scale)) // 2
tft.draw(title, s, x, 40, st7789.MAGENTA, scale)

Measure the Width, Then Center​

s = "Notice"
x = (tft.width() - tft.write_len(font_cn, s)) // 2
tft.write(font_cn, s, x, tft.height() - 30, st7789.WHITE, st7789.BLACK)

Troubleshooting​

SymptomCause / fix
Text is completely invisibleThe font does not cover those characters (silently skipped) → check FIRST / LAST, or confirm those characters were included at generation time
Garbled screen / wrong colorsA mismatch between the API and the font family (e.g. a bitmap font fed to draw()) → switch the API using the table above
ImportError: no module named 'font'The font file is not on the search path → sys.path.append('/sd/sys/font') and check the filename
Chinese shows as boxes / garbled textThe character was not included at generation time, or -s holds a half-width or variant form → generate in one batch from the same text
draw() produces scattered linesThe font has no INDEX / FONT → vector fonts live only under the vector/ directory
Text is always placed too far right / too lowThe y in write() / draw() is the top coordinate of the text, not the baseline → reserve the font's HEIGHT
Large text has jagged edgesBitmap fonts are blurry when scaled up → switch to a vector font with draw() + scale

Related modules: Display (ST7789) · Image Display (with GIF)

AI usage (coming soon)​

Soon you won't have to remember the differences between the three font families, or assemble the font2bitmap.py command yourself: describe the text you want to display in plain language, and the Agent will follow the APIs in this document to generate the font and write a program that runs on the Firefly T1.

For example, just tell it:

Build a 16-pixel-high Chinese font for the text "Starting up, please wait" and show it centered on the screen at boot.

It will then generate the font with font2bitmap.py, combine write() with the centering calculation, and place the file under /sd/apps/ on the SD card.

Agent entry (coming soon)

The entry link will go here. Once it is live, one click takes you straight to describing the app you want.