字库应用与制作
字库(字体模块)决定屏幕上文字长什么样。独角仙S1 固件里内置了三类字库,它们分别对应三个不同的显示接口:等宽点阵配 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 FONT | vga1_* / vga2_*(共 12 个) | 每个字符宽度固定,速度快,适合正文 |
write(font, s, x, y[, fg, bg, bg_tuple, fill]) | 变宽点阵:MAP BPP HEIGHT MAX_WIDTH OFFSET_WIDTH WIDTHS OFFSETS BITMAPS | NotoSans_32 / NotoSansMono_32 / NotoSerif_32 | 字符宽度按字形变化,支持中文,能在背景图上写字 |
draw(font, s, x, y[, color, scale]) | 矢量(Hershey):WIDTH HEIGHT FIRST LAST INDEX FONT | vector/ 下 26 个 | 用线段绘制,可任意放大不失真,适合标题 |
判断方法很简单:打开字库文件看头部有哪些大写常量。有 FIRST/LAST 的是等宽点阵;有 MAP/MAX_WIDTH 的是 font2bitmap 生成的变宽库;有 INDEX/FONT 的是矢量库。
内置位图字库(vga1_* 与 vga2_*)
两个家族的唯一区别是字符范围,用法完全一样。十二个文件都能直接 import,不用放进 SD 卡。
vga1:ASCII 96 个字形(0x20–0x7F)
| 字体文件 | 宽 × 高 | 说明 |
|---|---|---|
vga1_8x8 | 8 × 8 | 最小,横屏一行能放 30 个字符 |
vga1_8x16 | 8 × 16 | 经典终端比例,最常用 |
vga1_16x16 | 16 × 16 | 放大一倍的字 |
vga1_16x32 | 16 × 32 | 大字,适合标题 |
vga1_bold_16x16 | 16 × 16 | 加粗版 |
vga1_bold_16x32 | 16 × 32 | 加粗大字 |
vga2:256 个字形(0x00–0xFF)
除了 ASCII,还包含制表符、框线、块状图形和一些国际字符,做表格线或简单图形很方便。
| 字体文件 | 宽 × 高 | 说明 |
|---|---|---|
vga2_8x8 | 8 × 8 | 最小 |
vga2_8x16 | 8 × 16 | 常用尺寸,官方 App 就用它 |
vga2_16x16 | 16 × 16 | |
vga2_16x32 | 16 × 32 | |
vga2_bold_16x16 | 16 × 16 | 加粗 |
vga2_bold_16x32 | 16 × 32 | 加粗大字 |
应用示例
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。
| 字体文件 | 预览 |
|---|---|
| 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 |
应用示例
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)
| 字库 | 字符范围 | HEIGHT | MAX_WIDTH |
|---|---|---|---|
NotoSans_32 | ASCII 0x20–0x7F | 34 | 30 |
NotoSansMono_32 | ASCII 0x20–0x7F | 34 | 19 |
NotoSerif_32 | ASCII 0x20–0x7F | 34 | 30 |
同目录下的 .ttf 文件是转换用的源字体,供你自己造字库时使用;它们不会在设备上被解析。
外置中文字库(需自制)

原理很简单:font2bitmap.py 用指定的字体文件,把你指定的那几句话里的字渲染成点阵,生成一个 Python 模块;把模块放进 SD 卡,import 进来就能显示中文。因为只收录你用到的字,所以字库文件很小。
制作步骤
-
下载转换脚本:font2bitmap.py。它需要 Python 3 和
freetype-py:pip install freetype-py -
下载示例字体:NotoSansSC-Regular.zip(解压使用)。字体文件可以换成任何你喜欢的
.ttf/.otf,这里只是举例。 -
打开命令行,进入文件所在目录,执行转换命令。
命令格式
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 → 回车):


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


执行转换,把"你好"做成 16 像素高的字库:
python font2bitmap.py -s "你好" NotoSansSC-Regular.otf 16 > font.py


生成的 font.py 里会有 MAP(字符表)、BPP、HEIGHT、MAX_WIDTH、WIDTHS、OFFSETS、BITMAPS 等字段——正好是 write() 需要的格式。
-s 和 -c 互斥,只能选一个。要同时包含中文和 ASCII,就把它们写进同一个字符串:-s "你好世界Hello 123"。
应用示例
- 把生成的
font.py复制到独角仙S1 的/sd/sys/font/目录(目录名随意,只要和下面代码一致)。 - 先把目录加进模块搜索路径,再
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,直接生成字库并写出能在独角仙S1 上运行的程序。
比如直接对它说:
帮我把"开机中,请稍候"这几个字生成一个 16 像素高的中文字库,开机时居中显示在屏幕上。
它就会用 font2bitmap.py 生成字库、组合 write() 与居中计算,并把文件放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。