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.
text() takes vga*, write() takes a library generated by font2bitmap, draw() takes a vector font. Mixing them up shows nothing or garbage.
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.
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 API | Font format required | Built into the firmware | Characteristics |
|---|---|---|---|
text(font, s, x, y[, fg, bg]) | Fixed-width bitmap: WIDTH HEIGHT FIRST LAST FONT | vga1_* / 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 BITMAPS | NotoSans_32 / NotoSansMono_32 / NotoSerif_32 | Advance 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 FONT | 26 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 file | Width × Height | Notes |
|---|---|---|
vga1_8x8 | 8 × 8 | Smallest; 30 characters fit on one row in landscape |
vga1_8x16 | 8 × 16 | Classic terminal proportions, most commonly used |
vga1_16x16 | 16 × 16 | Double-size text |
vga1_16x32 | 16 × 32 | Large, good for headings |
vga1_bold_16x16 | 16 × 16 | Bold |
vga1_bold_16x32 | 16 × 32 | Bold and large |
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 file | Width × Height | Notes |
|---|---|---|
vga2_8x8 | 8 × 8 | Smallest |
vga2_8x16 | 8 × 16 | Common size; the official app uses this one |
vga2_16x16 | 16 × 16 | |
vga2_16x32 | 16 × 32 | |
vga2_bold_16x16 | 16 × 16 | Bold |
vga2_bold_16x32 | 16 × 32 | Bold and large |
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 file | Preview |
|---|---|
| astrol | |
| cyrilc | |
| gotheng | |
| gothger | |
| gothita | |
| greekc | |
| greekcs | |
| greekp | |
| greeks | |
| italicc | |
| italiccs | |
| italict | |
| lowmat | |
| marker | |
| meteo | |
| music | |
| romanc | |
| romancs | |
| romand | |
| romanp | |
| romans | |
| romant | |
| scriptc | |
| scripts | |
| symbol | |
| uppmat |
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)
| Font | Character range | HEIGHT | MAX_WIDTH |
|---|---|---|---|
NotoSans_32 | ASCII 0x20–0x7F | 34 | 30 |
NotoSansMono_32 | ASCII 0x20–0x7F | 34 | 19 |
NotoSerif_32 | ASCII 0x20–0x7F | 34 | 30 |
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)

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
-
Download the conversion script: font2bitmap.py. It needs Python 3 and
freetype-py:pip install freetype-py -
Download the sample typeface: NotoSansSC-Regular.zip (unzip before use). You can swap the typeface for any
.ttf/.otfyou like — this one is only an example. -
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
| Option | Description |
|---|---|
-s "text" | Characters to include, given directly as a string, e.g. -s "Hello" |
-c range | Characters by code point, decimal or 0x hex, e.g. -c 0x20-0x7f, -c "65,66,67" or -c "0x30-0x39, 0x41-0x5a" |
--font_width N | Force 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):


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


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


The generated font.py contains MAP (the character table), BPP, HEIGHT, MAX_WIDTH, WIDTHS, OFFSETS, BITMAPS and other fields — exactly the format write() expects.
-s and -c are mutually exclusive, so to include both Chinese and ASCII put them all into one string: -s "Hello 123".
Example
- Copy the generated
font.pyto the Firefly T1's/sd/sys/font/directory (any folder name works as long as the code below matches it). - Add that directory to the module search path, then
importit:
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
| Pitfall | Cause and fix |
|---|---|
text() with a custom Chinese font → blank or garbage | text() reads WIDTH / HEIGHT / FIRST / LAST / FONT, and a custom library has none of those fields → use write() |
write() with a vga* font → error | write() reads MAP / MAX_WIDTH / WIDTHS / OFFSETS / BITMAPS → vga* fonts belong with text() |
draw() with a bitmap font → error | draw() needs INDEX / FONT, which only the vector fonts under vector/ provide → bitmap fonts belong with text() / write() |
| Chinese renders as blank | Those 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 show | text() 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 library | freetype-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.append | The 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 Chinese | The 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
| Symptom | Cause / fix |
|---|---|
| Text is completely invisible | The font does not cover those characters (silently skipped) → check FIRST / LAST, or confirm those characters were included at generation time |
| Garbled screen / wrong colors | A 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 text | The 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 lines | The font has no INDEX / FONT → vector fonts live only under the vector/ directory |
| Text is always placed too far right / too low | The y in write() / draw() is the top coordinate of the text, not the baseline → reserve the font's HEIGHT |
| Large text has jagged edges | Bitmap 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.
The entry link will go here. Once it is live, one click takes you straight to describing the app you want.