显示屏(ST7789)
独角仙S1 的显示屏由 ST7789 驱动,分辨率 135 × 240。固件里提供了两样东西:tft_config(板级配置,帮你把 SPI、引脚、背光都接好)和 st7789(驱动本体,所有绘图、文字、图片接口都在它上面)。两行代码就能把屏幕点亮。
tft = tft_config.config(0) 拿到对象,tft.init() 点亮屏幕,之后所有绘图都调 tft.xxx()。
SPI1 / 40MHz、DC / CS / RST 与背光 PWM 都在 config() 里配好了,不用自己接。
16 位 RGB565 色,rotation 传 0/1/2/3 切换方向,横屏是 240×135。
硬件与引脚
tft_config.config() 已经把下面这张表全部接好,你不需要自己写一行硬件配置:
| 功能 | 值 |
|---|---|
| 总线 | SPI(1),波特率 40 MHz,polarity=0、phase=0 |
| MOSI / SDA | GPIO6 |
| SCK / CLK | GPIO7 |
| 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)
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
rotation | int | 0 | 屏幕方向,0/1/2/3(见上文表格) |
buffer_size | int | 0 | 常驻缓冲区字节数。0 = 每次操作临时申请、用完即还 |
options | int | 0 | 驱动选项位掩码,可传 st7789.WRAP / WRAP_H / WRAP_V |
backlight | int | 300 | 背光 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_* 等宽点阵字库 |
s | int / str / bytes | — | 要显示的内容;传 int 就显示这个码位的一个字符 |
x / y | int | — | 起始坐标 |
fg | int | WHITE | 字色 |
bg | int | BLACK | 字底色 |
无返回值。要点:
- 不透明:每个字符都会把整块
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 生成的变宽字库 |
s | str | — | 字符串 |
x / y | int | — | 起始坐标 |
fg | int | WHITE | 字模为 1 的像素画成的颜色 |
bg | int | BLACK | 字模为 0 且没有背景图时的颜色 |
bg_tuple | 元组 | 无 | (背景缓冲, 宽, 高),用于把文字叠在背景图上 |
fill | int | 0 | 传 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) |
s | int / str | — | 要显示的内容 |
x / y | int | — | 起始坐标 |
color | int | WHITE | 线段颜色 |
scale | float / int | 1.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)
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
src | str / bytes | — | 文件路径,或内存里的 JPEG 数据 |
x / y | int | — | 图片左上角坐标 |
mode | int | st7789.FAST | FAST(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 memory | jpg(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,直接生成能在独角仙S1 上运行的完整程序。
比如直接对它说:
横屏画一个仪表盘:上面一条蓝色标题栏,中间一个实心圆会随按键换颜色,底部显示一行状态文字。
它就会把 tft_config、st7789 的绘图与文字接口组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。