跳到主要内容

字库应用与制作

字库(字体模块)决定屏幕上文字长什么样。萤火虫T1 固件里内置了三类字库,它们分别对应三个不同的显示接口:等宽点阵配 text()、变宽点阵配 write()、矢量字体配 draw()。固件只内置了 ASCII 字库——想显示汉字必须自己造一个小字库,本页最后一节给出完整步骤。

三类字库不能互换

text() 配 vga*、write() 配 font2bitmap 生成的库、draw() 配矢量字体。用错会不显示或花屏。

汉字要自己生成

固件里的字库都只覆盖 ASCII。用 PC 端的 font2bitmap.py 把你需要的字打包成一个小模块,放进 SD 卡即可。

缺字不会报错

字库里没有的字符会被静默跳过——屏幕上就是空的。所以生成字库时要把用到的字列全。

三类字库,三个接口​

显示接口需要什么格式的字库固件内置在哪特点
text(font, s, x, y[, fg, bg])等宽点阵:WIDTH HEIGHT FIRST LAST FONTvga1_* / vga2_*(共 12 个)每个字符宽度固定,速度快,适合正文
write(font, s, x, y[, fg, bg, bg_tuple, fill])变宽点阵:MAP BPP HEIGHT MAX_WIDTH OFFSET_WIDTH WIDTHS OFFSETS BITMAPSNotoSans_32 / NotoSansMono_32 / NotoSerif_32字符宽度按字形变化,支持中文,能在背景图上写字
draw(font, s, x, y[, color, scale])矢量(Hershey):WIDTH HEIGHT FIRST LAST INDEX FONTvector/ 下 26 个用线段绘制,可任意放大不失真,适合标题

判断方法很简单:打开字库文件看头部有哪些大写常量。有 FIRST/LAST 的是等宽点阵;有 MAP/MAX_WIDTH 的是 font2bitmap 生成的变宽库;有 INDEX/FONT 的是矢量库。

内置位图字库(vga1_* 与 vga2_*)​

两个家族的唯一区别是字符范围,用法完全一样。十二个文件都能直接 import,不用放进 SD 卡。

vga1:ASCII 96 个字形(0x20–0x7F)​

字体文件宽 × 高说明
vga1_8x88 × 8最小,横屏一行能放 30 个字符
vga1_8x168 × 16经典终端比例,最常用
vga1_16x1616 × 16放大一倍的字
vga1_16x3216 × 32大字,适合标题
vga1_bold_16x1616 × 16加粗版
vga1_bold_16x3216 × 32加粗大字

VGA1 8x8 点阵字库预览

VGA1 加粗 16x16 点阵字库预览

vga2:256 个字形(0x00–0xFF)​

除了 ASCII,还包含制表符、框线、块状图形和一些国际字符,做表格线或简单图形很方便。

字体文件宽 × 高说明
vga2_8x88 × 8最小
vga2_8x168 × 16常用尺寸,官方 App 就用它
vga2_16x1616 × 16
vga2_16x3216 × 32
vga2_bold_16x1616 × 16加粗
vga2_bold_16x3216 × 32加粗大字

VGA2 16x16 点阵字库预览

VGA2 加粗 16x16 点阵字库预览

应用示例​

import st7789
import tft_config
import vga2_16x32 as font

tft = tft_config.config(1) # 横屏
tft.init()

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

text() 的 fg(字色)和 bg(字背后的底色)可以省略,默认是白色字、黑色底。注意 text() 是"不透明"的:它会为每个字符写满一整块背景色,所以不适合叠在背景图片上(会盖住背景)。要在背景图上写字请用 图片显示 里的 write()。

vga1_* 的字库只有 0x20–0x7F 这 96 个字形,超出范围的字符会被整个跳过——所以用 vga1_* 显示汉字只会得到一片空白(要汉字就自制字库,见下文)。

内置矢量字库(26 个)​

矢量字库(Hershey 字体)是用线段画出来的字形,放大后依然平滑,所以适合做标题或大字。字符范围同样是 ASCII 0x20–0x7F。

字体文件预览
astrolastrol 字体
cyrilccyrilc 字体
gothenggotheng 字体
gothgergothger 字体
gothitagothita 字体
greekcgreekc 字体
greekcsgreekcs 字体
greekpgreekp 字体
greeksgreeks 字体
italiccitalicc 字体
italiccsitaliccs 字体
italictitalict 字体
lowmatlowmat 字体
markermarker 字体
meteometeo 字体
musicmusic 字体
romancromanc 字体
romancsromancs 字体
romandromand 字体
romanpromanp 字体
romansromans 字体
romantromant 字体
scriptcscriptc 字体
scriptsscripts 字体
symbolsymbol 字体
uppmatuppmat 字体

应用示例​

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 默认是 1.0,可以传小数(1.5)也可以是整数(2)。想知道一段文字画出来有多宽,先用 draw_len(font, s[, scale]) 量一下。

内置 TrueType 字库(已经转成了点阵)​

truetype/ 目录里有三个能直接 import 的库:NotoSans_32、NotoSansMono_32、NotoSerif_32(分别是无衬线、等宽、衬线)。

它们不是运行时渲染的 TrueType,而是已经用 font2bitmap.py 预转好的变宽点阵字库——看模块头部的注释就知道:

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

所以它们和"外置中文字库"是同一类东西,要用 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)
字库字符范围HEIGHTMAX_WIDTH
NotoSans_32ASCII 0x20–0x7F3430
NotoSansMono_32ASCII 0x20–0x7F3419
NotoSerif_32ASCII 0x20–0x7F3430

同目录下的 .ttf 文件是转换用的源字体,供你自己造字库时使用;它们不会在设备上被解析。

外置中文字库(需自制)​

外置中文字库原理图

原理很简单:font2bitmap.py 用指定的字体文件,把你指定的那几句话里的字渲染成点阵,生成一个 Python 模块;把模块放进 SD 卡,import 进来就能显示中文。因为只收录你用到的字,所以字库文件很小。

制作步骤​

  1. 下载转换脚本:font2bitmap.py。它需要 Python 3 和 freetype-py:

    pip install freetype-py
  2. 下载示例字体:NotoSansSC-Regular.zip(解压使用)。字体文件可以换成任何你喜欢的 .ttf / .otf,这里只是举例。

  3. 打开命令行,进入文件所在目录,执行转换命令。

命令格式​

python font2bitmap.py [选项] 字体文件 高度 > 输出.py
选项说明
-s "文字"要收录的字符,直接写字符串,例如 -s "你好世界"
-c 范围用字符码指定,支持十进制和 0x 十六进制,例如 -c 0x20-0x7f、-c "65,66,67" 或 -c "0x30-0x39, 0x41-0x5a"
--font_width N强制字宽,默认与高度相同

-s 和 -c 必须二选一,不能同时使用。

实际操作​

把脚本和字体解压到 D:\font,然后打开命令行(Win + R → 输入 cmd → 回车):

把文件放在 D:\font 目录

打开 CMD

先切到该盘和目录(文件放在哪个盘就进哪个盘):

进入 D 盘

进入 font 文件夹

执行转换,把"你好"做成 16 像素高的字库:

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

执行转换命令

生成 font.py 文件

生成的 font.py 里会有 MAP(字符表)、BPP、HEIGHT、MAX_WIDTH、WIDTHS、OFFSETS、BITMAPS 等字段——正好是 write() 需要的格式。

中英文一起用

-s 和 -c 互斥,只能选一个。要同时包含中文和 ASCII,就把它们写进同一个字符串:-s "你好世界Hello 123"。

应用示例​

  1. 把生成的 font.py 复制到萤火虫T1 的 /sd/sys/font/ 目录(目录名随意,只要和下面代码一致)。
  2. 先把目录加进模块搜索路径,再 import:
import sys
sys.path.append('/sd/sys/font') # 字库模块所在的目录

import st7789
import tft_config
import font # 上面生成的 font.py

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

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

write() 的 fg 是字的颜色,bg 是字背后那块的底色,可以随便换:

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

官方光绘 App 也是这么用的——把字库放在 App 自己的目录里,然后把该目录加进 sys.path:

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

tft.write(font_C, "中:续停", 5, 90, st7789.BLACK, st7789.WHITE)

常见坑点​

坑原因与正确做法
用 text() 显示自制中文字库 → 空白或花屏text() 读的是 WIDTH / HEIGHT / FIRST / LAST / FONT,自制库里没有这些字段 → 改用 write()
用 write() 显示 vga* → 报错write() 读的是 MAP / MAX_WIDTH / WIDTHS / OFFSETS / BITMAPS → vga* 要用 text()
用 draw() 显示点阵库 → 报错draw() 需要 INDEX / FONT,只有 vector/ 下的向量库有 → 点阵库用 text() / write()
汉字是空白字库里没有这个字(生成时没收录),或用了 vga1_* → 重新生成时把用到的字全部列进 -s
字符超出屏幕右边就不显示了text() 单个字符越界会整字跳过,也不换行 → 自己按字宽算好每行长度
生成的字库 pip install 报错缺 freetype-py → 先 pip install freetype-py 再执行转换
转换命令报「-s 与 -c 互斥」两个选项不能同时用 → 只保留一个,或把字符都写进 -s 字符串
sys.path.append 了还是 ImportError路径写错或文件名不对 → 确认目录里确实是那个 .py,且路径以 /sd 开头
用了 NotoSans_32 却不显示中文内置的三个 TrueType 库只有 ASCII → 中文要自制字库

更多配方​

一行中文 + 一行英文混排​

write() 会按每个字的实际宽度推进,所以混排不会出现大片空隙:

import st7789
import tft_config
import NotoSans_32 as font_en
import font_cn # 自制中文字库

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

tft.write(font_cn, "光绘模式", 10, 10, st7789.WHITE, st7789.BLACK)
tft.write(font_en, "Light Painting", 10, 50, st7789.YELLOW, st7789.BLACK)

用矢量字库做会缩放的开机标题​

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)

先量宽度再居中​

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

排错​

现象原因 / 处理
文字完全看不到字库没覆盖这些字符(静默跳过)→ 检查 FIRST / LAST,或确认生成时收录了这些字
屏幕花屏 / 颜色错乱用错了接口与字库的搭配(点阵库喂给 draw() 等)→ 按上文对照表换接口
ImportError: no module named 'font'字库文件不在搜索路径里 → sys.path.append('/sd/sys/font') 且确认文件名
中文显示成方块 / 乱码生成时没收录该字,或 -s 里写的是半角/异体字 → 用同一份文本批量生成
draw() 画出来是乱线字库里没有 INDEX / FONT → 矢量字体只在 vector/ 目录下
文字位置总是偏右 / 偏下write() / draw() 的 y 是文字顶部坐标,不是基线 → 需要留出字体 HEIGHT
大字边缘有锯齿点阵字库放大本来就糊 → 改用矢量字库 draw() + scale

相关模块:显示屏(ST7789) · 图片显示(含 GIF)

AI 用法(即将上线)​

以后你不用记三类字库的区别、也不用自己拼 font2bitmap.py 的命令:用自然语言描述你想显示的文案,Agent 会照着本文档里的 API,直接生成字库并写出能在萤火虫T1 上运行的程序。

比如直接对它说:

帮我把"开机中,请稍候"这几个字生成一个 16 像素高的中文字库,开机时居中显示在屏幕上。

它就会用 font2bitmap.py 生成字库、组合 write() 与居中计算,并把文件放进 SD 卡的 /sd/apps/。

Agent 入口(即将上线)

入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。