跳到主要内容

显示屏(ST7789)

萤火虫T1 的显示屏由 ST7789 驱动,分辨率 135 × 240。固件里提供了两样东西:tft_config(板级配置,帮你把 SPI、引脚、背光都接好)和 st7789(驱动本体,所有绘图、文字、图片接口都在它上面)。两行代码就能把屏幕点亮。

两行就能用

tft = tft_config.config(0) 拿到对象,tft.init() 点亮屏幕,之后所有绘图都调 tft.xxx()。

引脚已接好

SPI1 / 40MHz、DC / CS / RST 与背光 PWM 都在 config() 里配好了,不用自己接。

135×240 全彩

16 位 RGB565 色,rotation 传 0/1/2/3 切换方向,横屏是 240×135。

硬件与引脚​

tft_config.config() 已经把下面这张表全部接好,你不需要自己写一行硬件配置:

功能值
总线SPI(1),波特率 40 MHz,polarity=0、phase=0
MOSI / SDAGPIO6
SCK / CLKGPIO7
DC(命令/数据)GPIO8
CS(片选)GPIO10
RST(复位)GPIO9
BLK(背光)GPIO11,用 PWM 控制亮度
分辨率135 × 240(rotation=0/2 竖屏;1/3 横屏 240 × 135)
色彩格式RGB565(16 位)

快速开始​

import tft_config
import st7789

tft = tft_config.config(0) # 0 = 竖屏,传 1 就是横屏
tft.init() # 必调:初始化面板并清屏

tft.fill(st7789.BLACK) # 清屏
tft.fill_rect(10, 10, 60, 30, st7789.RED) # 画一块红矩形
tft.text(font, "Hello", 10, 60, st7789.WHITE, st7789.BLACK)

运行现象:屏幕先被清成黑色,然后左上角出现一块红色矩形。init() 本身就会把整屏刷成黑色,所以紧接着再 fill() 一次不是必须的,只是习惯写法。

font 需要先 import,比如 import vga2_16x32 as font。字库的用法见 字库应用与制作。

屏幕方向与坐标系​

config(rotation) 和 tft.rotation(v) 接受的旋转值只有 0 / 1 / 2 / 3(内部会做 v % 4):

rotation方向width() × height()说明
0竖屏135 × 240默认方向
1横屏240 × 135光绘 App 常用
2竖屏翻转135 × 240上下颠倒
3横屏翻转240 × 135上下颠倒

坐标系原点 (0, 0) 永远在当前方向的左上角,x 向右、y 向下。旋转会互换宽高,所以布局代码里不要写死 135 / 240,一律用 tft.width() 和 tft.height():

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

x = (tft.width() - 100) // 2
y = (tft.height() - 100) // 2
tft.fill_rect(x, y, 100, 100, st7789.GREEN)

颜色​

颜色是 16 位 RGB565 整数。三种获取方式:

import st7789

st7789.BLACK # 8 个常用颜色常量:BLACK / BLUE / RED / GREEN
st7789.WHITE # CYAN / MAGENTA / YELLOW / WHITE

st7789.color565(255, 128, 0) # 用 RGB 分量现算(每项 0–255)

st7789.color565(r, g, b) 是模块级函数,不需要实例:它把 8 位 RGB 压成 RGB565。首位色序由构造参数决定,tft_config 用的是默认的 RGB。

屏幕颜色不对(红蓝互换)怎么办

这是色序(RGB/BGR)不匹配。板子出厂配置已按面板调好,正常不需要动;如果自己接屏且颜色跑偏,用 tft.madctl(...) 改 MADCTL 的 BGR 位。

API 参考​

tft_config.config(rotation=0, buffer_size=0, options=0, backlight=300) 返回的就是一个 st7789.ST7789 实例(下面统一叫 tft)。所有方法都挂在它上面。

初始化 tft_config.config()​

import tft_config

tft = tft_config.config(rotation=0, buffer_size=0, options=0, backlight=300)
参数类型默认说明
rotationint0屏幕方向,0/1/2/3(见上文表格)
buffer_sizeint0常驻缓冲区字节数。0 = 每次操作临时申请、用完即还
optionsint0驱动选项位掩码,可传 st7789.WRAP / WRAP_H / WRAP_V
backlightint300背光 PWM 占空比,范围 0–1023(300 ≈ 30% 亮度)

它内部做了三件事:新建 SPI(1) 总线、把背光引脚 GPIO11 设成 PWM 并写入 backlight 亮度、构造 st7789.ST7789 对象。

  • config() 只是创建对象,不会点亮屏幕,后面必须自己调 tft.init()。
  • 一个程序里只调一次:每次调用都会新建 SPI 与 PWM 对象,重复调用纯属浪费资源。
  • 背光亮度用 0–1023,不是百分比:想要 50% 亮度就传 512。

点亮屏幕 tft.init()​

tft.init()

无参数、无返回值。它会完成面板初始化流程,并把整屏刷成黑色,最后打开显示。

  • 必须在任何绘图之前调用一次,否则屏幕是白的或花屏。
  • 初始化后屏幕内容被清空,别指望保留上电前的画面。
  • 想改变旋转,可以之后再调 tft.rotation(v),不必重新 init()。

屏幕方向与尺寸​

tft.rotation(v)​

tft.rotation(1)

切换屏幕方向,无返回值。内部对 v 取 % 4,所以传 4 等价于 0;width() / height() 随之互换。

tft.width() / tft.height()​

w = tft.width() # 当前方向下的宽度
h = tft.height() # 当前方向下的高度

返回当前方向下的像素尺寸,无参数。

tft.offset(col, row)​

tft.offset(52, 40)

设置显示窗口相对面板的偏移,无返回值。这个板子每种方向对应的偏移值驱动已经内置好了,一般不用手动改;只有在用别的面板(比如 240×320)时才需要覆盖。

tft.madctl([v])​

tft.madctl() # 读回当前 MADCTL 寄存器值
tft.madctl(0x60) # 写入新的 MADCTL 值

不带参数时返回当前的 MADCTL 字节;带参数时写入并返回。它决定扫描方向、行列交换和 RGB/BGR 色序,属于底层接口。

显示控制​

tft.on() / tft.off()​

tft.on() # 打开背光
tft.off() # 关闭背光

无参数、无返回值。它们操作的是背光引脚,而且只有构造时传了 backlight= 才会生效——tft_config 没有把背光引脚交给驱动(它自己用 PWM 控制 GPIO11),所以在这个板子上这两个调用不会改变亮度。要调亮度请直接用 PWM:

from machine import Pin, PWM

bl = PWM(Pin(11))
bl.duty(0) # 全黑(背光关)
bl.duty(1023) # 最亮

tft.sleep_mode(enable)​

tft.sleep_mode(True) # 进入睡眠(省电,画面关闭)
tft.sleep_mode(False) # 唤醒

写面板的 SLPIN / SLPOUT 命令。睡眠时面板不再刷新,唤醒后需要重新 init() 或重画内容。

tft.inversion_mode(enable)​

tft.inversion_mode(True)

开关显示反色(INVON / INVOFF)。注意这是整屏反色,和 color565 的取反不是一回事。

tft.hard_reset() / tft.soft_reset()​

tft.hard_reset() # 拉低 RST 引脚硬复位
tft.soft_reset() # 发送 SWRESET 软复位

无参数、无返回值。正常情况下 init() 已经处理过复位,这两个一般排障时才用。

tft.vscrdef(tfa, vsa, bfa) / tft.vscsad(vssa)​

tft.vscrdef(40, 160, 40) # 顶部固定 40 行、滚动区 160 行、底部固定 40 行
tft.vscsad(20) # 把滚动区的起始行设为第 20 行

无返回值。vscrdef() 把屏幕纵向切成「顶部固定区 + 可滚动区 + 底部固定区」三段(tfa / vsa / bfa 单位都是行数,三者之和应等于屏幕高度);vscsad() 设定滚动区当前显示的第一行。

它只负责设定面板的滚动窗口,不会自己产生动画——要滚动得在循环里不断改 vscsad() 的值。日志滚动、状态栏固定 + 内容滚动都靠它。tft_config 里预留了 TFA = 40 / BFA = 40 两个常量,可以拿来当这两段的参考行数。

绘图​

所有绘图方法的坐标都是当前方向下的屏幕坐标。

tft.fill(color)​

tft.fill(st7789.BLACK)

用 color 填满整屏,无返回值。清屏就用它。

tft.fill_rect(x, y, w, h, color)​

tft.fill_rect(x, y, w, h, color)

画一块填充矩形,左上角 (x, y)、宽 w、高 h,无返回值。

tft.rect(x, y, w, h, color)​

tft.rect(x, y, w, h, color)

画矩形边框(不填充),参数同上。边框由 2 条横线 + 2 条竖线组成。

tft.hline(x, y, w, color) / tft.vline(x, y, h, color)​

tft.hline(x, y, w, color) # 从 (x, y) 向右画 w 像素
tft.vline(x, y, h, color) # 从 (x, y) 向下画 h 像素

画水平 / 垂直线段,无返回值。它们比 line() 快得多(只走一个方向的快速路径),画表格线优先用它们。

tft.line(x0, y0, x1, y1, color)​

tft.line(0, 0, 100, 60, st7789.WHITE)

画任意斜线段,无返回值。内部用 Bresenham 算法逐像素描点,比直线慢。

tft.pixel(x, y, color)​

tft.pixel(10, 10, st7789.GREEN)

画一个像素,无返回值。开销较大(每个点都要单独设窗口),不适合大量描点。

tft.circle(x, y, r, color) / tft.fill_circle(x, y, r, color)​

tft.circle(67, 120, 40, st7789.CYAN) # 空心圆(描边)
tft.fill_circle(67, 120, 40, st7789.BLUE) # 实心圆

以 (x, y) 为圆心、r 为半径画圆,无返回值。空心圆逐点描边;实心圆内部用竖线填充,比一排排 pixel() 快得多。

文字​

三个文字接口对应三种字库格式,不能混用:

接口需要的字库说明
tft.text(font, s, x, y[, fg, bg])等宽点阵 vga1_* / vga2_*不透明,速度快
tft.write(font, s, x, y[, fg, bg, bg_tuple, fill])变宽点阵(font2bitmap 生成)支持中文,可叠在背景图上
tft.draw(font, s, x, y[, color, scale])矢量字库(vector/ 下 26 个)用线段描字,可任意放大

tft.text(font, s, x, y[, fg, bg])​

tft.text(font, "Hello", 0, 0) # 白字黑底
tft.text(font, "Hello", 0, 0, st7789.YELLOW) # 黄字黑底
tft.text(font, "Hello", 0, 0, st7789.YELLOW, st7789.BLUE)
参数类型默认说明
font模块—vga1_* / vga2_* 等宽点阵字库
sint / str / bytes—要显示的内容;传 int 就显示这个码位的一个字符
x / yint—起始坐标
fgintWHITE字色
bgintBLACK字底色

无返回值。要点:

  • 不透明:每个字符都会把整块 WIDTH × HEIGHT 填满,bg 就是这块底色,所以不能叠在图片上(会盖住背景)。
  • 字符宽度固定为字库的 WIDTH,x 自动按字符宽度递增。
  • 字库范围外的字符被整个跳过:vga1_* 只覆盖 0x20–0x7F,用它显示汉字就是一片空白。
  • 单个字符如果会超出屏幕右边界(x + WIDTH > width()),这个字符直接不画,也不会换行。

tft.write(font, s, x, y[, fg, bg, bg_tuple, fill])​

tft.write(font, "你好", 10, 10)
tft.write(font, "Hello", 10, 10, st7789.WHITE, st7789.BLACK, (bg, w, h), 1)
参数类型默认说明
font模块—font2bitmap 生成的变宽字库
sstr—字符串
x / yint—起始坐标
fgintWHITE字模为 1 的像素画成的颜色
bgintBLACK字模为 0 且没有背景图时的颜色
bg_tuple元组无(背景缓冲, 宽, 高),用于把文字叠在背景图上
fillint0传 1 时每个字符按字库最宽字符宽度铺满,配背景图使用

返回实际打印的像素宽度(可用来接着算后面的坐标)。它逐字按各自字形宽度推进,所以中文、英文混排不会出现大空隙。

要把文字叠在背景图片上,原理是把「文字要出现的那块背景」裁出来当 bg_tuple:字模为 1 的像素画成 fg,为 0 的像素保留背景原色。详细写法见 图片显示。

tft.draw(font, s, x, y[, color, scale])​

import romans as font

tft.draw(font, "Hello", 10, 40, st7789.WHITE, 1.5)
参数类型默认说明
font模块—vector/ 下的矢量字库(含 INDEX / FONT)
sint / str—要显示的内容
x / yint—起始坐标
colorintWHITE线段颜色
scalefloat / int1.0放大倍数,可传小数

无返回值。只用线段描字,不画背景色,所以可以直接叠在已有画面上;放大后边缘依然是直线,不会像点阵那样变模糊。字符范围同样是 ASCII 32–127。

tft.write_len(font, s) / tft.draw_len(font, s[, scale])​

w = tft.write_len(font, "你好") # 这段字写完会占多宽
w = tft.draw_len(font, "Hello", 1.5) # 放大 1.5 倍后占多宽

返回这段文字在屏幕上将占用的像素宽度,不实际绘制。用来做居中、右对齐:

s = "Hello"
x = (tft.width() - tft.write_len(font, s)) // 2 # 水平居中
tft.write(font, s, x, 10)

图片与像素缓冲​

图片接口的完整用法(FAST/SLOW 选择、尺寸限制、动画、透明)见 图片显示,这里只列签名。

tft.jpg(src, x, y[, mode])​

tft.jpg('/sd/image/photo.jpg', 0, 0, st7789.SLOW)
参数类型默认说明
srcstr / bytes—文件路径,或内存里的 JPEG 数据
x / yint—图片左上角坐标
modeintst7789.FASTFAST(0) 一次解码整张后整屏刷入;SLOW(1) 分块边解码边刷

无返回值。

tft.png(filename, x, y[, mask])​

tft.png('/sd/image/icon.png', 10, 10)
tft.png('/sd/image/icon.png', 10, 10, True) # 保留透明通道

只接受文件路径,逐行解码,内存占用只需一行像素。mask=True 时 alpha 为 0 的像素跳过不画,屏幕原内容会透出来。

tft.bitmap(module, x, y[, index])​

tft.bitmap(sprites, 30, 88) # 省略 index = 显示第 0 帧
tft.bitmap(sprites, 30, 88, 3) # 显示第 3 帧

显示用转换脚本生成的位图模块(含 WIDTH / HEIGHT / BPP / PALETTE / BITMAP,多帧还含 BITMAPS)。index 超出 BITMAPS 会抛 OSError: index out of range。

tft.blit_buffer(buffer, x, y, w, h)​

buf, w, h = tft.jpg_decode('/sd/image/photo.jpg')
tft.blit_buffer(buf, 10, 10, w, h)

把一块 RGB565 像素缓冲贴到屏幕,必须传满 6 个参数。实际发送的字节数是 min(缓冲区长度, w × h × 2)——缓冲区偏小只会显示一部分,不会报错。

tft.jpg_decode(src[, x, y, w, h])​

buf, w, h = tft.jpg_decode('/sd/image/photo.jpg') # 解码整张
buf, w, h = tft.jpg_decode('/sd/image/photo.jpg', 10, 10, 32, 32) # 只裁 32×32

返回 (bytearray, width, height) 三元组,缓冲是可直接 blit_buffer() 的 RGB565 数据(字节已交换)。传 x, y, w, h 时它们是在源图里裁剪哪一块,不是屏幕坐标。参数个数不是 2 或 6 时抛 TypeError。

内存

源码里 jpg_decode() 每次调用都会新申请 2 × 宽 × 高 字节且不释放。所以不要放在循环里反复调用——正确做法是解码一次、反复 blit_buffer()。

多边形​

多边形用坐标点列表表示(((x0, y0), (x1, y1), ...))。

tft.polygon(poly, x, y, color[, angle, cx, cy])​

triangle = ((0, 0), (60, 0), (30, 50))

tft.polygon(triangle, 20, 20, st7789.WHITE) # 空心(描边)
tft.polygon(triangle, 20, 20, st7789.WHITE, 30, 30, 25) # 绕 (cx, cy) 旋转 30°

在 (x, y) 处画出多边形的边(不填充)。angle 是旋转角度(度),cx / cy 是旋转中心(相对多边形自身的坐标)。

tft.fill_polygon(poly, x, y, color[, angle, cx, cy])​

tft.fill_polygon(triangle, 20, 20, st7789.RED)

同上,但填充内部。

tft.polygon_center(poly)​

cx, cy = tft.polygon_center(triangle)

返回多边形(顶点平均)中心坐标,常用来当旋转中心。

tft.bounding([status, as_rect])​

tft.bounding() # 返回 (min_x, min_y, max_x, max_y)
tft.bounding(1) # 重置边界记录
tft.bounding(1, True) # 返回矩形形式 (min_x, min_y, w, h)

驱动内部会记录「画过哪些像素」的包围盒,用来统计脏区域、做局部刷新。传 status=1 会同时把包围盒复位。

模块级函数​

st7789.color565(r, g, b)​

color = st7789.color565(255, 128, 0)

把 8 位 RGB 分量(各 0–255)压成 RGB565 整数,直接用 int 计算,不需要实例。

st7789.map_bitarray_to_rgb565(bitarray, buffer, width, color, bg_color)​

buf = bytearray(32 * 16 * 2)
st7789.map_bitarray_to_rgb565(bits, buf, 32, st7789.WHITE, st7789.BLACK)
tft.blit_buffer(buf, 0, 0, 32, 16)

把 1 位位图(bitarray)按 width 展开成 RGB565 缓冲:位为 1 的像素用 color,位为 0 的用 bg_color。常见用途是把单色图片或自定义字形快速转成可 blit_buffer() 的数据。

常见坑点​

坑原因与正确做法
屏幕全白 / 花屏忘了调 tft.init() → 任何绘图前先 init()
画面颜色红蓝互换色序(RGB/BGR)不匹配 → 板子默认已调好;自己接屏才需要改 madctl()
改不了背光亮度tft.on() / off() 在这个板子上不控背光 → 用 PWM(Pin(11)).duty(0–1023)
布局写死 135 / 240 结果错位旋转会互换宽高 → 一律用 tft.width() / tft.height() 计算
汉字显示成空白text() 用的是 vga1_*(只覆盖 0x20–0x7F)→ 中文要自制字库并用 write()
字压在图片上变成黑块text() 是不透明的,会填满底色 → 改用 draw(),或 write() 配 bg_tuple
一个字符没显示该字符会超出右边界(x + WIDTH > width())时整字跳过 → 提前算好位置
circle() 画出来是个方块阴影用错了方法:circle() 描边、fill_circle() 实心
大量 pixel() 后画面卡顿每像素都要设一次窗口 → 改用 fill_rect() / hline() / bitmap()
循环里 jpg() 一段时间后 OSError: out of memoryjpg(FAST) 需要 2 × 宽 × 高 连续内存 → 缩小图片,或改用 png()
jpg_decode() 反复调用后内存耗尽它申请的内存不释放 → 解码一次,反复 blit_buffer()
滑屏 / 局部刷新没效果需要先 vscrdef() 设置滚动区域,再用 bounds 统计脏区

更多配方​

画一个仪表盘风格的状态栏​

import tft_config
import st7789
import vga2_8x16 as font

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

W = tft.width()

tft.fill(st7789.BLACK)
tft.fill_rect(0, 0, W, 20, st7789.BLUE) # 顶栏
tft.text(font, "Socolode", 6, 2, st7789.WHITE, st7789.BLUE)
tft.hline(0, 20, W, st7789.WHITE)
tft.text(font, "Battery 87%", 6, 30, st7789.GREEN, st7789.BLACK)
tft.rect(6, 60, 100, 40, st7789.YELLOW) # 进度框
tft.fill_rect(8, 62, 84, 36, st7789.YELLOW) # 进度条

居中显示一段文字​

import NotoSans_32 as font

s = "Hello"
x = (tft.width() - tft.write_len(font, s)) // 2
y = (tft.height() - font.HEIGHT) // 2
tft.write(font, s, x, y, st7789.WHITE, st7789.BLACK)

用矢量字库画大标题​

import romans as title_font

tft.draw(title_font, "LIGHT", 20, 30, st7789.MAGENTA, 3) # 放大 3 倍

矢量字体放大不会失真,做大字标题比点阵好看。

完整示例​

下面这段放进 /sd/apps/my-draw-app/boot.py:开机清屏、画一个居中的圆和标题、用按键切换配色。

from button import Button
import st7789
import tft_config
import romans as title_font

COLORS = [st7789.RED, st7789.GREEN, st7789.BLUE, st7789.YELLOW]
index = 0
running = True

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

buttons = Button()


def render():
color = COLORS[index]
w = tft.width()
h = tft.height()

tft.fill(st7789.BLACK)
tft.fill_circle(w // 2, h // 2, 40, color) # 中间一个实心圆
tft.draw(title_font, "S1", w // 2 - 18, h // 2 - 10, st7789.WHITE, 1.5)


def on_up():
global index
index = (index - 1) % len(COLORS)
render()


def on_down():
global index
index = (index + 1) % len(COLORS)
render()


def on_center_long():
global running
running = False


buttons.register_callback('up', 'short', on_up)
buttons.register_callback('down', 'short', on_down)
buttons.register_callback('center', 'long', on_center_long)

render()

while running:
pass # render() 都在按键回调里完成

buttons.deinit()
tft.fill(st7789.BLACK)

排错​

现象原因 / 处理
屏幕一直黑背光亮度是 0(config(backlight=0)),或没调 init() → 传 backlight=300 并 init()
屏幕全白init() 没跑完或 SPI 没接好 → 检查接线与 config() 是否只调了一次
画面花屏 / 撕裂SPI 速率过高或接触不良 → 这是板载 40MHz 配置,正常稳定;自制排线要缩短杜邦线
颜色全部相反色序不匹配 → 板子默认已调好;自接屏用 madctl() 调 BGR 位
旋转后坐标全乱写死了 135 / 240 → 改用 width() / height()
画什么都看不见画在了屏幕外 → 用 width() / height() 校验坐标
OSError: out of memory图片或字库太大 → 缩小资源,或改用 png() / bitmap()
OSError: buffer too small. N bytes required.构造时传了偏小的 buffer_size → 改回默认 0
ValueError: must specify dc pin自己直接构造 st7789.ST7789 时忘了 dc= → 用 tft_config.config() 就不会遇到
对象创建两次后行为异常重复调用了 config() → 一个程序只调一次,复用同一个 tft

相关模块:图片显示(含 GIF) · 字库应用与制作 · 蜂鸣器(beep)

AI 用法(即将上线)​

以后你不用记 color565 的参数顺序、也不用算居中坐标:用自然语言描述你想要的画面,Agent 会照着本文档里的 API,直接生成能在萤火虫T1 上运行的完整程序。

比如直接对它说:

横屏画一个仪表盘:上面一条蓝色标题栏,中间一个实心圆会随按键换颜色,底部显示一行状态文字。

它就会把 tft_config、st7789 的绘图与文字接口组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。

Agent 入口(即将上线)

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