ST7789显示屏驱动开发实战指南：从硬件连接到高级应用

引言：嵌入式显示开发的挑战与解决方案

在嵌入式系统开发中，显示屏接口往往是项目实现的关键环节。ST7789作为一款广泛应用的TFT LCD控制器，以其出色的显示性能和适中的成本，成为众多嵌入式项目的理想选择。然而，直接操作ST7789硬件寄存器不仅复杂且容易出错，极大影响开发效率。

st7789py_mpy库作为专为MicroPython环境设计的ST7789驱动解决方案，通过抽象底层硬件操作，提供了简洁易用的API接口，使开发者能够专注于应用逻辑实现而非硬件细节。本文将系统介绍该库的使用方法，从环境搭建到高级功能应用，帮助开发者快速掌握ST7789显示屏的驱动开发。

环境准备与项目架构解析

获取项目源码

要开始使用st7789py_mpy库，首先需要获取项目源码：

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

项目结构详解

项目采用模块化设计，主要目录结构如下：

• lib/: 核心驱动实现，包含st7789py.py主驱动文件
• examples/: 丰富的示例程序，覆盖各类显示功能
• tft_configs/: 针对不同开发板的硬件配置模板
• romfonts/: 内置字体资源，支持多种字体尺寸和样式
• utils/: 辅助工具集，用于图像转换和字体生成
• docs/: 项目文档和示例图片

这种结构设计使开发者能够根据自己的硬件平台快速配置，并通过示例代码快速理解各项功能的使用方法。

硬件连接与配置参数

硬件接口概述

ST7789显示屏通常通过SPI接口与微控制器连接，主要信号包括：

• SCL/SCK: SPI时钟线
• SDA/MOSI: SPI数据线
• DC: 数据/命令选择线
• RST: 复位信号线
• CS: 片选信号线
• BL: 背光控制信号线（可选）

典型配置参数

不同开发板的配置文件位于tft_configs/目录下，以下是ESP32开发板的典型配置示例：

# tft_configs/esp32_320x240/tft_config.py
from machine import Pin, SPI
import st7789py as st7789

def config(rotation=0):
    """配置并返回ST7789显示屏对象"""
    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总线	指定SPI接口和通信速率	SPI(2, baudrate=40000000)
屏幕尺寸	显示屏的宽度和高度（像素）	135, 240
控制引脚	复位、片选、数据/命令选择引脚	reset=Pin(23)
背光控制	背光引脚配置（可选）	backlight=Pin(4)
旋转角度	屏幕显示方向	0, 1, 2, 3（0-270度）

基础显示功能实现

显示屏初始化流程

使用st7789py_mpy库初始化显示屏的基本流程如下：

1. 导入必要的模块
2. 配置显示屏参数
3. 初始化显示屏对象
4. 执行基本显示操作

import st7789py as st7789
import tft_config
import vga2_bold_16x32 as font

def main():
    # 初始化显示屏
    tft = tft_config.config()
    
    # 清屏并设置背景色
    tft.fill(st7789.BLACK)
    
    # 显示文本
    tft.text(font, "Hello World!", 20, 100, st7789.WHITE, st7789.BLACK)

if __name__ == "__main__":
    main()

运行上述代码后，显示屏将显示"Hello World!"文本，效果如下：

基本图形绘制

st7789py_mpy库提供了丰富的图形绘制函数，支持点、线、矩形、圆形等基本图形：

# 绘制像素点
tft.pixel(50, 50, st7789.RED)

# 绘制直线
tft.line(0, 0, tft.width-1, tft.height-1, st7789.GREEN)

# 绘制矩形（空心）
tft.rect(20, 20, 100, 80, st7789.BLUE)

# 绘制填充矩形
tft.fill_rect(130, 20, 100, 80, st7789.YELLOW)

# 绘制圆形（空心）
tft.circle(60, 150, 30, st7789.PURPLE)

# 绘制填充圆形
tft.fill_circle(180, 150, 30, st7789.ORANGE)

这些基本图形绘制函数为创建复杂界面提供了基础构建块。

高级显示功能应用

屏幕旋转控制

st7789py_mpy支持四种屏幕旋转模式，通过rotation()方法可以动态调整显示方向：

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

旋转功能在实际应用中非常实用，例如在不同安装方向的设备上保持内容正确显示。以下是不同旋转角度的显示效果：

字体系统与文本显示

库中提供了多种内置字体，位于romfonts/目录下，支持不同尺寸和样式：

• vga1_8x8.py: 8x8像素基础字体
• vga1_16x16.py: 16x16像素字体
• vga2_bold_16x32.py: 16x32像素粗体字体
• 更多字体可在romfonts/目录中查看

使用不同字体显示文本的示例：

import vga1_8x8 as small_font
import vga2_bold_16x32 as large_font

# 使用小字体显示
tft.text(small_font, "Small text", 10, 10, st7789.WHITE)

# 使用大字体显示
tft.text(large_font, "Large Text", 10, 30, st7789.CYAN)

不同字体的显示效果如下：

色彩控制与显示测试

ST7789支持16位RGB色彩显示，库中预定义了常用颜色常量。可以通过color_test.py示例程序测试显示屏的色彩表现：

# 显示基本颜色块
tft.fill_rect(0, 0, tft.width, tft.height//3, st7789.RED)
tft.fill_rect(0, tft.height//3, tft.width, tft.height//3, st7789.GREEN)
tft.fill_rect(0, 2*tft.height//3, tft.width, tft.height//3, st7789.BLUE)

# 显示颜色名称
tft.text(font, "Red", tft.width//2-20, 10, st7789.WHITE)
tft.text(font, "Green", tft.width//2-30, tft.height//3+10, st7789.BLACK)
tft.text(font, "Blue", tft.width//2-25, 2*tft.height//3+10, st7789.WHITE)

运行上述代码可以测试显示屏的色彩显示效果：

图像显示功能

除了基本图形和文本，st7789py_mpy还支持显示位图图像。通过utils/image_converter.py工具可以将普通图片转换为适合显示屏的格式。

# 显示位图图像
from alien_bitmap import alien

# 在指定位置显示位图
tft.bitmap(alien, 50, 50)

位图显示功能特别适合显示图标、logo等简单图像，为界面设计提供了更多可能性。

实用示例：彩色条显示

彩色条是测试显示屏色彩表现和显示连续性的常用方法。以下是完整的彩色条显示实现：

import st7789py as st7789
import tft_config

def colorbars(tft):
    """显示彩色条测试图案"""
    colors = [
        st7789.RED,
        st7789.ORANGE,
        st7789.YELLOW,
        st7789.GREEN,
        st7789.CYAN,
        st7789.BLUE,
        st7789.PURPLE,
        st7789.MAGENTA
    ]
    
    bar_width = tft.width // len(colors)
    
    for i, color in enumerate(colors):
        tft.fill_rect(i*bar_width, 0, bar_width, tft.height, color)

def main():
    tft = tft_config.config()
    tft.fill(st7789.BLACK)
    colorbars(tft)

if __name__ == "__main__":
    main()

运行上述代码后，显示屏将显示连续的彩色条，效果如下：

常见问题与解决方案

显示异常问题排查

1. 无显示或黑屏

   • 检查SPI引脚连接是否正确
   • 确认电源电压是否稳定（通常为3.3V）
   • 检查复位引脚是否正确配置并正常工作

2. 显示错乱或花屏

   • 降低SPI通信速率尝试
   • 检查显示屏型号与驱动配置是否匹配
   • 确认显示屏初始化参数正确

3. 部分区域显示异常

   • 检查屏幕尺寸参数是否正确
   • 确认旋转角度设置是否符合预期
   • 检查显存操作是否越界

性能优化建议

1. 减少刷屏操作

   • 只更新变化的区域而非整个屏幕
   • 使用局部刷新代替全局刷新

2. 优化图像数据传输

   • 使用合适的图像格式减少数据量
   • 考虑使用压缩算法传输图像数据

3. 合理使用颜色

   • 减少颜色切换次数
   • 避免频繁的全屏颜色填充

高级应用与扩展

自定义字体创建

使用utils/text_font_converter.py工具可以将TrueType字体转换为适合ST7789显示的格式：

# 转换字体示例
python utils/text_font_converter.py -f NotoSansSC-Regular.otf -s 24 -o myfont.py

图像转换工具

utils/image_converter.py工具可以将普通图像转换为位图格式：

# 转换图像示例
python utils/image_converter.py -i image.png -o image_bitmap.py

硬件按钮集成

部分配置文件（如tft_configs/m5stack_core/tft_buttons.py）提供了按钮支持，可以实现简单的用户交互：

from tft_buttons import Buttons

buttons = Buttons()

if buttons.pressed(buttons.A):
    # A按钮被按下
    pass
elif buttons.pressed(buttons.B):
    # B按钮被按下
    pass

总结与学习路径

st7789py_mpy库为ST7789显示屏提供了全面的MicroPython驱动支持，通过简洁的API接口降低了嵌入式显示开发的门槛。本文从环境搭建、硬件配置、基础功能到高级应用，系统介绍了库的使用方法。

进阶学习建议

1. 深入理解示例代码：examples目录提供了丰富的功能演示，是学习的重要资源
2. 硬件适配实践：尝试为不同开发板编写或修改配置文件
3. 性能优化研究：探索提高显示性能的方法和技巧
4. 功能扩展开发：基于现有API实现更复杂的显示效果

通过不断实践和探索，开发者可以充分发挥ST7789显示屏的性能，为嵌入式项目打造出色的视觉体验。