st7789py_mpy完全开发指南：从入门到精通

在嵌入式开发中，你是否曾为ST7789显示屏的驱动配置而头疼？是否希望找到一个既稳定又易用的MicroPython驱动库？st7789py_mpy就是为解决这些问题而生的开源项目，它提供了一套完整的ST7789显示屏驱动解决方案，让你能够快速实现从简单文本显示到复杂图形绘制的各种功能。本文将带你深入了解这个项目的核心价值，掌握环境搭建方法，解析核心功能，并通过实战案例和进阶技巧，帮助你从入门到精通ST7789显示屏开发。

项目核心价值：为什么选择st7789py_mpy？

你可能会问，市面上已有不少ST7789驱动库，为什么要选择st7789py_mpy？让我们看看它的核心优势：

1. 开箱即用的硬件适配

项目提供了丰富的硬件配置模板，覆盖了Atom S3、ESP32、M5Stack系列、TTGO T-Display等多种主流开发板，无需从零开始编写引脚配置代码。

2. 高效的显示性能

优化的底层驱动实现，支持最高40MHz SPI通信速率，在240x240分辨率下全屏刷新仅需约80ms，满足大多数实时显示需求。

3. 丰富的图形功能

内置完整的图形绘制API，支持点、线、矩形、圆形等基本图形，以及文本渲染、位图显示等高级功能，无需额外依赖。

4. 灵活的字体系统

提供多种内置字体（VGA系列），同时支持自定义字体转换，满足不同场景下的文本显示需求。

5. 完善的文档和示例

详尽的文档和丰富的示例代码，帮助你快速上手，避免踩坑。

环境准备：如何搭建开发环境？

开始使用st7789py_mpy前，你需要准备以下环境和工具：

硬件要求

• 支持MicroPython的开发板（如ESP32、ESP8266、RP2040等）
• ST7789驱动的TFT显示屏（推荐1.3英寸或2.0英寸，分辨率240x240或320x240）
• 杜邦线若干
• USB数据线

软件要求

• Python 3.7+
• MicroPython固件（根据开发板型号选择）
• ampy或rshell（用于文件传输）
• Git（用于获取项目源码）

项目获取与安装

1. 克隆项目源码：

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

2. 项目结构解析：

st7789py_mpy/
├── lib/              # 核心驱动代码
│   └── st7789py.py   # ST7789驱动实现
├── examples/         # 示例代码
├── tft_configs/      # 硬件配置模板
├── romfonts/         # 内置字体
└── utils/            # 辅助工具

3. 安装到开发板： 将lib/st7789py.py和对应开发板的配置文件（如tft_configs/esp32_320x240/tft_config.py）上传到开发板的根目录。

核心功能解析：如何使用st7789py_mpy的核心功能？

1. 显示屏初始化

如何正确初始化ST7789显示屏？以下是基于ESP32开发板的示例：

# 导入必要的模块
from machine import Pin, SPI
import st7789py as st7789

# 配置SPI接口
spi = SPI(2, baudrate=40000000, sck=Pin(18), mosi=Pin(19))

# 初始化显示屏
tft = st7789.ST7789(
    spi,
    240, 240,  # 屏幕宽度和高度
    reset=Pin(23, Pin.OUT),
    cs=Pin(5, Pin.OUT),
    dc=Pin(16, Pin.OUT),
    backlight=Pin(4, Pin.OUT),
    rotation=0  # 旋转角度：0, 1, 2, 3 分别对应0°, 90°, 180°, 270°
)

# 打开背光
tft.backlight_on()

# 清屏（黑色）
tft.fill(st7789.BLACK)

适用场景：所有基于st7789py_mpy的显示项目，这是使用显示屏的第一步。

常见误区：忘记设置正确的屏幕尺寸和旋转角度，导致显示内容错位或颠倒。

2. 文本显示

如何在屏幕上显示文本？st7789py_mpy提供了便捷的文本显示功能：

# 导入字体
import vga2_bold_16x32 as font

# 显示文本
tft.text(
    font,  # 字体对象
    "Hello World!",  # 文本内容
    20, 100,  # x, y坐标
    st7789.WHITE,  # 文本颜色
    st7789.BLACK   # 背景颜色
)

# 显示不同大小的文本
import vga1_8x8 as small_font
tft.text(small_font, "Small text", 20, 140, st7789.RED, st7789.BLACK)

图：ST7789显示屏上显示的多彩文本效果，展示了不同颜色和大小的文字

适用场景：显示标题、状态信息、数据数值等文本内容。

字体选择建议：

字体名称	尺寸	适用场景
vga1_8x8	8x8	显示大量小文本
vga1_16x16	16x16	中等大小文本
vga2_bold_16x32	16x32	标题或重点内容

3. 图形绘制

st7789py_mpy提供了丰富的图形绘制功能，让你可以轻松绘制各种图形：

# 绘制像素点
tft.pixel(120, 120, st7789.RED)  # 在中心位置绘制红色像素

# 绘制直线
tft.line(0, 0, 239, 239, st7789.GREEN)  # 从左上角到右下角的绿色直线

# 绘制矩形
tft.rect(50, 50, 100, 80, st7789.BLUE)  # 左上角(50,50)，宽100，高80的蓝色矩形

# 绘制填充矩形
tft.fill_rect(70, 70, 60, 40, st7789.YELLOW)  # 填充黄色矩形

# 绘制圆形
tft.circle(120, 120, 40, st7789.PURPLE)  # 中心(120,120)，半径40的紫色圆形

适用场景：绘制界面元素、数据可视化、简单游戏等。

4. 屏幕旋转

如何根据设备安装方向调整显示方向？st7789py_mpy支持四种旋转模式：

# 设置旋转角度
tft.rotation(0)  # 0°（默认）
# tft.rotation(1)  # 90°
# tft.rotation(2)  # 180°
# tft.rotation(3)  # 270°

# 获取当前旋转角度
current_rotation = tft.rotation()
print(f"Current rotation: {current_rotation * 90} degrees")

图：ST7789显示屏的旋转效果展示，当前为0°旋转状态

适用场景：需要根据设备安装方向调整显示的场景，如智能手表、便携式设备等。

5. 颜色控制

如何使用不同的颜色显示内容？st7789py_mpy支持16位RGB565颜色格式：

# 预定义颜色
red = st7789.RED
green = st7789.GREEN
blue = st7789.BLUE

# 自定义颜色（RGB565格式）
# 红色分量（5位），绿色分量（6位），蓝色分量（5位）
purple = st7789.color565(255, 0, 255)  # 紫色
orange = st7789.color565(255, 165, 0)  # 橙色

# 绘制彩色条
tft.fill_rect(0, 0, 48, 240, st7789.RED)
tft.fill_rect(48, 0, 48, 240, st7789.YELLOW)
tft.fill_rect(96, 0, 48, 240, st7789.GREEN)
tft.fill_rect(144, 0, 48, 240, st7789.CYAN)
tft.fill_rect(192, 0, 48, 240, st7789.BLUE)

图：ST7789显示屏上的彩色条效果，展示了不同颜色的显示效果

适用场景：界面美化、状态指示、数据可视化等需要使用多种颜色的场景。

实战案例：如何实现一个温湿度监控显示？

让我们通过一个实际案例来综合运用st7789py_mpy的功能：实现一个温湿度监控显示系统。

硬件准备

• ESP32开发板
• ST7789显示屏（240x240）
• DHT11温湿度传感器

接线说明

• DHT11 DATA引脚 -> ESP32 GPIO4
• 显示屏SCL -> ESP32 GPIO18
• 显示屏SDA -> ESP32 GPIO19
• 显示屏DC -> ESP32 GPIO16
• 显示屏RST -> ESP32 GPIO23
• 显示屏CS -> ESP32 GPIO5
• 显示屏BL -> ESP32 GPIO4

代码实现

import time
from machine import Pin
import dht
import st7789py as st7789
import vga1_16x16 as font16
import vga2_bold_16x32 as font32

# 初始化DHT11传感器
dht_sensor = dht.DHT11(Pin(4))

# 初始化显示屏
spi = SPI(2, baudrate=40000000, sck=Pin(18), mosi=Pin(19))
tft = st7789.ST7789(
    spi, 240, 240,
    reset=Pin(23, Pin.OUT),
    cs=Pin(5, Pin.OUT),
    dc=Pin(16, Pin.OUT),
    backlight=Pin(4, Pin.OUT),
    rotation=1  # 横向显示
)
tft.backlight_on()
tft.fill(st7789.BLACK)

# 显示标题
tft.text(font32, "Temp & Hum", 10, 10, st7789.WHITE, st7789.BLACK)

# 绘制分隔线
tft.line(0, 50, 239, 50, st7789.WHITE)

while True:
    try:
        # 读取温湿度数据
        dht_sensor.measure()
        temp = dht_sensor.temperature()
        hum = dht_sensor.humidity()
        
        # 清除之前的读数
        tft.fill_rect(0, 60, 240, 180, st7789.BLACK)
        
        # 显示温度
        tft.text(font32, "Temp:", 20, 70, st7789.RED, st7789.BLACK)
        tft.text(font32, f"{temp}C", 120, 70, st7789.RED, st7789.BLACK)
        
        # 显示湿度
        tft.text(font32, "Hum:", 20, 120, st7789.BLUE, st7789.BLACK)
        tft.text(font32, f"{hum}%", 120, 120, st7789.BLUE, st7789.BLACK)
        
        # 显示更新时间
        current_time = time.localtime()
        time_str = f"{current_time[3]:02d}:{current_time[4]:02d}:{current_time[5]:02d}"
        tft.text(font16, time_str, 60, 180, st7789.GREEN, st7789.BLACK)
        
        # 等待2秒
        time.sleep(2)
        
    except OSError as e:
        tft.text(font16, "Read error", 20, 180, st7789.RED, st7789.BLACK)
        time.sleep(2)

功能说明：

• 初始化DHT11传感器和ST7789显示屏
• 显示标题和分隔线
• 循环读取温湿度数据并显示
• 显示当前时间
• 错误处理：当传感器读取失败时显示错误信息

进阶技巧：如何优化显示性能和扩展功能？

1. 使用双缓冲减少闪烁

在动态显示场景中，屏幕闪烁是常见问题。使用双缓冲技术可以有效解决这个问题：

# 创建缓冲区
buffer = bytearray(240 * 240 * 2)  # 240x240分辨率，每个像素2字节

# 在缓冲区中绘制
tft.buffer = buffer
tft.fill(st7789.BLACK)
tft.text(font, "Buffered text", 20, 100, st7789.WHITE, st7789.BLACK)

# 将缓冲区内容一次性显示到屏幕
tft.show()

适用场景：动画、实时数据更新等需要频繁刷新的场景。

2. 自定义字体转换

如何使用自己的字体？st7789py_mpy提供了字体转换工具：

# 进入工具目录
cd utils

# 转换TrueType字体为MicroPython可用格式
python text_font_converter.py -i myfont.ttf -o myfont_16.py -s 16

使用转换后的字体：

import myfont_16 as custom_font
tft.text(custom_font, "Custom font", 20, 50, st7789.WHITE, st7789.BLACK)

图：ST7789显示屏上不同字体的显示效果对比

3. 图像显示优化

如何高效显示图像？可以使用图像转换工具将图片转换为适合ST7789的格式：

# 转换图像为Python数组
python image_converter.py -i image.jpg -o image.py

显示转换后的图像：

from image import image_data
tft.bitmap(image_data, 0, 0)  # 在(0,0)位置显示图像

4. 颜色校正技巧

不同显示屏的颜色表现可能有所差异，可以通过调整RGB分量来校正颜色：

def adjust_color(r, g, b, r_gain=1.0, g_gain=1.0, b_gain=1.0):
    """调整颜色增益"""
    r = min(int(r * r_gain), 255)
    g = min(int(g * g_gain), 255)
    b = min(int(b * b_gain), 255)
    return st7789.color565(r, g, b)

# 使用调整后的颜色（假设红色偏暗，增加红色增益）
red = adjust_color(255, 0, 0, r_gain=1.2)

图：ST7789显示屏颜色测试图案，展示了红、绿、蓝三原色的显示效果

5. 低功耗优化

在电池供电的设备上，如何降低功耗？

# 关闭背光
tft.backlight_off()

# 进入睡眠模式
tft.sleep_mode(True)

# 唤醒显示屏
tft.sleep_mode(False)
tft.backlight_on()

适用场景：电池供电的便携式设备，如智能手表、环境监测节点等。

总结与扩展资源

通过本文，你已经掌握了st7789py_mpy库的核心功能和使用方法，能够实现从简单文本显示到复杂图形绘制的各种功能。以下是一些扩展资源，帮助你进一步深入学习：

相关工具

• mpremote：MicroPython官方远程控制工具，可用于文件传输和交互式调试
• Thonny：适合MicroPython开发的IDE，集成了代码编辑、调试和设备管理功能

学习资源

• 项目官方文档：docs/index.html
• 示例代码集合：examples/
• 硬件配置模板：tft_configs/

版本兼容性

• st7789py_mpy v1.0+ 支持MicroPython 1.17+
• 不同开发板的配置文件位于tft_configs/目录下，选择与你的开发板匹配的配置

st7789py_mpy为ST7789显示屏提供了强大而便捷的驱动支持，无论是制作智能家居控制面板、便携式仪器仪表，还是开发嵌入式游戏，它都能满足你的需求。现在，是时候动手实践，将这些知识应用到你的项目中了！