终极指南：如何用st7789py_mpy库轻松驱动ST7789显示屏 🚀

st7789py_mpy是一款专为微Python设计的高效ST7789显示屏驱动库，让你轻松在嵌入式设备上实现绚丽的图形显示效果。无论是新手还是资深开发者，都能通过本指南快速掌握这个强大工具的使用方法。

📋 项目核心功能与目录结构

st7789py_mpy库提供了完整的ST7789显示屏控制功能，包括文本渲染、图形绘制、屏幕旋转等核心能力。项目采用模块化设计，主要目录结构如下：

• lib/：核心驱动代码存放目录，包含lib/st7789py.py驱动实现
• examples/：丰富的示例程序，如hello.py、rotations.py等实用演示
• tft_configs/：多种硬件配置模板，支持不同开发板快速适配
• romfonts/：内置字体库，提供多种尺寸的文本显示支持
• docs/：完整的官方文档，包含详细使用说明和API参考

图：st7789py_mpy项目结构及核心文件分布，展示了主要功能模块的组织方式

🔧 快速安装与环境准备

要开始使用st7789py_mpy，首先需要获取项目源码。通过以下命令克隆仓库：

git clone https://gitcode.com/gh_mirrors/st/st7789py_mpy

项目无需复杂的安装过程，只需将相关文件复制到你的微Python设备中即可。核心依赖包括：

• 支持SPI接口的微Python设备
• ST7789芯片的TFT显示屏
• 必要的杜邦线或开发板

✨ 第一个示例：Hello World显示教程

examples目录下的hello.py是最基础的入门示例，展示了如何初始化显示屏并显示文本：

import random
import st7789py as st7789
import tft_config
import vga2_bold_16x32 as font

def main():
    tft = tft_config.config(tft_config.WIDE)  # 初始化显示屏
    
    while True:
        for rotation in range(4):
            tft.rotation(rotation)  # 旋转屏幕
            tft.fill(0)             # 清屏
            # 在随机位置显示彩色"Hello"文本
            tft.text(
                font, "Hello", 
                random.randint(0, tft.width - font.WIDTH*5),
                random.randint(0, tft.height - font.HEIGHT),
                st7789.color565(random.getrandbits(8), random.getrandbits(8), random.getrandbits(8)),
                st7789.color565(random.getrandbits(8), random.getrandbits(8), random.getrandbits(8))
            )

main()

运行此示例后，你将看到"Hello"文本以随机颜色和位置显示在屏幕上，并自动切换不同的屏幕旋转角度。

图：hello.py示例运行效果，展示了ST7789显示屏上的彩色文本显示

🛠️ 硬件配置与适配方法

tft_configs目录提供了多种硬件配置模板，以esp32_320x240为例，配置文件tft_config.py包含了引脚定义和初始化参数：

from machine import Pin, SPI
import st7789py as st7789

def config(rotation=0):
    return st7789.ST7789(
        SPI(2, baudrate=40000000, sck=Pin(18), mosi=Pin(19)),
        135, 240,  # 屏幕尺寸
        reset=Pin(23, Pin.OUT),
        cs=Pin(5, Pin.OUT),
        dc=Pin(16, Pin.OUT),
        backlight=Pin(4, Pin.OUT),
        rotation=rotation
    )

常见的可配置参数包括：

• SPI参数：波特率、时钟引脚、数据引脚
• 屏幕尺寸：宽度和高度设置
• 控制引脚：复位(reset)、数据/命令(dc)、背光(backlight)引脚
• 旋转角度：0-3共4种旋转方向

🎨 高级功能与实用示例

屏幕旋转与颜色控制

examples/rotations.py演示了如何实现屏幕旋转和颜色控制功能：

def main():
    tft = tft_config.config(tft_config.WIDE)
    colors = (
        ("Red", st7789.RED, st7789.WHITE),
        ("Green", st7789.GREEN, st7789.BLACK),
        # 更多颜色...
    )
    
    while True:
        for rotation in range(4):  # 循环4种旋转角度
            tft.rotation(rotation)
            tft.fill(bg_color)     # 设置背景色
            # 显示旋转角度和颜色信息
            center_on(tft, font, str(rotation), tft.height//2, fg_color, bg_color)
            time.sleep(2)

运行该示例后，屏幕会依次展示0°、90°、180°、270°四种旋转效果，并循环切换不同背景颜色。

图：rotations.py示例演示了ST7789显示屏的四种旋转模式和颜色效果

文本显示与字体选择

st7789py_mpy支持多种字体显示，romfonts目录提供了不同尺寸的字体文件：

• vga1_8x8.py：8x8像素基础字体
• vga2_bold_16x32.py：16x32像素粗体字体
• 更多字体文件位于romfonts/目录

使用不同字体只需导入相应模块并传递给text方法：

import vga1_8x8 as small_font
import vga2_bold_16x32 as large_font

# 显示小字体文本
tft.text(small_font, "Small text", 10, 10)
# 显示大字体文本
tft.text(large_font, "Large text", 10, 30)

📝 常用API功能速查表

lib/st7789py.py提供了丰富的API接口，以下是最常用的几个功能：

• text(font, text, x, y, color, background)：显示文本
• fill(color)：清屏并设置背景色
• rotation(angle)：设置屏幕旋转角度(0-3)
• pixel(x, y, color)：绘制单个像素
• line(x0, y0, x1, y1, color)：绘制直线
• rect(x, y, width, height, color)：绘制矩形
• bitmap(bitmap, x, y, index=0)：显示位图图像

🚀 项目扩展与自定义

st7789py_mpy支持多种高级扩展功能，包括：

1. 自定义字体：通过utils/text_font_converter.py工具转换TrueType字体
2. 图像显示：使用image_converter.py将图片转换为适合显示的格式
3. 硬件按钮：部分配置提供了tft_buttons.py支持触摸或物理按键

所有工具脚本均位于utils/目录，可根据需求进行二次开发和定制。

💡 常见问题与解决方案

• 显示异常：检查SPI引脚连接是否正确，波特率是否匹配硬件要求
• 字体模糊：尝试使用更大字号的字体，或调整显示对比度
• 屏幕闪烁：检查电源稳定性，确保电压符合显示屏要求
• 不支持的旋转角度：确认使用的是最新版本库，旧版本可能支持有限

更多问题和解决方案可参考项目文档docs/目录下的详细说明。

🎯 总结与下一步学习

通过本指南，你已经掌握了st7789py_mpy库的基本使用方法。接下来可以尝试：

1. 探索examples目录下的其他示例程序
2. 尝试修改tft_config.py适配你的硬件
3. 使用utils工具创建自定义字体和图像
4. 开发自己的创意显示项目

st7789py_mpy库为嵌入式显示提供了强大而灵活的解决方案，无论是制作智能手表、环境监测设备还是小型游戏机，它都能满足你的需求。立即开始你的创意项目吧！