ESP32+MicroPython玩转ST7789彩色屏:从点亮到显示自定义图案(附完整代码)
你是否刚拿到一块小巧的ST7789彩色屏幕,看着密密麻麻的引脚和陌生的术语,感觉无从下手?别担心,这篇文章就是为你准备的。我们将绕过枯燥的理论堆砌,直接从动手连接开始,用ESP32和MicroPython这门对初学者极其友好的语言,一步步点亮屏幕,绘制图形,最终实现显示你自己的创意图案。整个过程就像搭积木,我们会把每个步骤拆解得清清楚楚,并准备好应对那些新手常踩的“坑”。无论你是想为你的物联网项目添加一个炫酷的界面,还是单纯享受让硬件“活”过来的乐趣,跟着做,你就能收获一块属于你自己的、会“说话”的彩色画布。
1. 硬件准备与连接:迈出第一步
在敲下第一行代码之前,正确的硬件连接是成功的一半。ST7789屏幕通常通过SPI接口与ESP32通信,这是一种高速、全双工的通信协议。我们需要搞清楚几根关键线的作用。
核心引脚连接指南
对于一块典型的240x240像素的ST7789屏幕,其引脚定义可能因模块而异,但核心引脚大同小异。下面是一个基于常见ESP32开发板(如ESP32 DevKitC V4)的连接示例表格:
| ST7789屏幕引脚 | 功能说明 | ESP32 GPIO引脚 | 备注 |
|---|---|---|---|
| VCC | 电源正极 (3.3V) | 3.3V | 切勿接5V,会烧毁屏幕! |
| GND | 电源地 | GND | 共地是关键 |
| SCL / SCK | 时钟信号 | GPIO 14 | SPI时钟线 |
| SDA / MOSI | 主设备输出,从设备输入 | GPIO 13 | 数据输出线 |
| RES / RST | 复位信号 | GPIO 18 | 用于硬件复位屏幕 |
| DC / RS | 数据/命令选择 | GPIO 16 | 高电平为数据,低电平为命令 |
| CS | 片选信号 | GPIO 15 | 低电平选中该设备 |
| BLK / LED | 背光控制 | GPIO 4 (或接VCC) | 可通过PWM调光 |
注意:上表仅为一种参考接法。你的屏幕引脚顺序可能不同,请务必以屏幕模块本身的丝印或资料为准。背光引脚如果直接接VCC,则屏幕会常亮;接GPIO并通过代码控制,则可以实现开关或亮度调节。
连接时,建议使用杜邦线在面包板上进行。确保所有连接牢固,电源正负极没有接反。一个常见的错误是将屏幕的VCC接到了ESP32的5V引脚(如VIN),这极有可能导致屏幕瞬间损坏。ESP32的逻辑电平是3.3V,屏幕也必须使用3.3V供电。
2. 软件环境搭建与基础驱动
硬件连通后,我们需要为ESP32刷入MicroPython固件,并安装必要的驱动库。这个过程就像给一台新电脑安装操作系统和驱动程序。
2.1 烧录MicroPython固件
首先,你需要一个USB数据线将ESP32连接到电脑。然后,去MicroPython官网下载适用于ESP32的最新稳定版固件文件(.bin文件)。接着,使用像esptool.py这样的工具进行烧录。打开你的终端(Windows可用CMD或PowerShell,Mac/Linux用系统终端),执行类似下面的命令:
esptool.py --chip esp32 --port COM3 --baud 460800 write_flash -z 0x1000 esp32-xxx.bin
请将 COM3 替换为你电脑上识别到的ESP32串口端口(在Mac/Linux上可能是 /dev/ttyUSB0),将 esp32-xxx.bin 替换为你下载的实际固件文件名。
2.2 安装驱动库与开发工具
固件烧录成功后,你需要一个工具来与ESP32上的MicroPython交互并上传文件。Thonny IDE 是当前对MicroPython支持最友好、最适合新手的集成开发环境。
- 安装Thonny:从其官网下载并安装。
- 配置解释器:打开Thonny,在菜单栏选择
运行->选择解释器。在对话框中,选择“MicroPython (ESP32)”,并正确选择你的ESP32所连接的端口。 - 安装ST7789驱动库:驱动库不是MicroPython内置的,需要我们手动上传。你可以从开源社区(如GitHub上的
russhughes/st7789s3_mpy或类似项目)获取针对MicroPython优化过的st7789.py驱动文件。在Thonny的文件侧边栏,将其拖拽到ESP32的设备文件系统中即可。
完成这些,你的软件环境就准备好了。在Thonny下方的Shell窗口中,你应该能看到MicroPython的交互提示符 >>>,尝试输入 print(“Hello ESP32!”) 并回车,看到回复就说明一切正常。
3. 点亮屏幕:从初始化到第一个图形
现在进入激动人心的环节——让屏幕亮起来。我们将从最简单的填充颜色开始,逐步增加复杂度。
3.1 初始化屏幕与SPI
创建一个新的Python脚本文件(例如 main.py),写入以下初始化代码。这段代码建立了ESP32与ST7789屏幕之间的通信桥梁。
from machine import Pin, SPI
import st7789
import time
# 屏幕分辨率定义
TFT_WIDTH = 240
TFT_HEIGHT = 240
# 初始化SPI总线(参数根据你的连接调整)
# SPI(1) 表示使用ESP32的HSPI硬件SPI1,速度设为40MHz
spi = SPI(1, baudrate=40000000, polarity=1, phase=0,
sck=Pin(14), mosi=Pin(13), miso=None) # 大部分ST7789不需要MISO
# 初始化显示屏对象
tft = st7789.ST7789(spi, TFT_WIDTH, TFT_HEIGHT,
reset=Pin(18, Pin.OUT),
dc=Pin(16, Pin.OUT),
cs=Pin(15, Pin.OUT),
backlight=Pin(4, Pin.OUT),
rotation=1) # rotation控制旋转方向(0-3)
# 打开背光
tft.backlight(1)
# 用红色填充整个屏幕
tft.fill(st7789.RED)
time.sleep(2) # 等待2秒,让你看清红色
运行这段代码,你的屏幕应该瞬间被红色充满。如果屏幕没有反应,一片漆黑,别慌,我们马上进入排错环节。
3.2 常见初始化问题排查
“屏幕不亮”是新手遇到最多的问题,可能的原因和解决思路如下:
- 背光未亮:这是最容易被忽略的一点。检查背光引脚(BLK)是否已正确连接并设置为高电平。尝试在代码中显式控制
tft.backlight(1),或者直接用杜邦线将BLK引脚短接到3.3V。 - SPI参数错误:
polarity和phase(合称CPOL和CPHA)是SPI的时钟模式,必须与屏幕驱动IC的要求匹配。ST7789常用模式是polarity=1, phase=0或polarity=0, phase=0。如果不对,屏幕可能无法正确解析数据。查阅你的屏幕资料或尝试另一种组合。 - 引脚连接错误:再次仔细核对每一根线的连接,特别是SCK、MOSI、DC、RST和CS。一个引脚接错就可能导致通信失败。
- 电源问题:确保VCC接的是稳定的3.3V,且GND已共地。可以尝试用万用表测量电压。
- 驱动库不兼容:不同的
st7789.py驱动库可能在初始化参数或方法名上有细微差别。确保你使用的库文档或示例代码与你的调用方式一致。
当屏幕成功点亮并显示颜色后,你可以尝试其他内置颜色,如 st7789.GREEN, st7789.BLUE, st7789.WHITE, st7789.BLACK。
3.3 绘制基本图形与文字
仅仅填充颜色还不够,我们开始绘制一些基础图形。ST7789驱动库通常提供了一些基本绘图函数。
# 清屏为黑色
tft.fill(st7789.BLACK)
# 1. 画一个矩形(参数:x起始, y起始, 宽度, 高度, 颜色)
tft.rect(20, 20, 100, 80, st7789.YELLOW)
# 2. 填充一个矩形
tft.fill_rect(150, 20, 60, 60, st7789.CYAN)
# 3. 画一条线(参数:x0, y0, x1, y1, 颜色)
tft.line(10, 120, 230, 120, st7789.MAGENTA)
# 4. 画单个像素点
tft.pixel(120, 180, st7789.WHITE)
# 5. 显示文字(注意:需要字体文件支持,基础方法可能只支持内置小字体)
# 参数:字符串, x坐标, y坐标, 前景色, 背景色(可选)
tft.text("Hello MicroPython!", 30, 200, st7789.WHITE, st7789.BLACK)
运行后,你会在屏幕上看到黄色的空心矩形、青色的实心矩形、一条洋红色的横线、一个白色的像素点以及一行文字。这标志着你已经完全掌握了屏幕的基础控制。
4. 显示自定义图案:从位图到动画
基础图形是砖瓦,而自定义图案才是构建个性化界面的核心。我们将学习两种主流方法:显示位图图片和动态绘制图案。
4.1 准备并显示位图(BMP)图像
MicroPython处理图像的一个常见方法是使用未经压缩的BMP位图。这种图片的每个像素颜色直接对应屏幕的像素。你需要先将彩色图片转换成适合屏幕分辨率(如240x240)和色彩格式(通常是16位RGB565)的BMP文件。
转换步骤简述:
- 使用图像处理软件(如Photoshop、GIMP或在线工具)将图片调整为240x240像素。
- 将图片颜色模式转换为“索引颜色”,颜色表选择16位(65536色),或者直接保存为16位/像素的BMP格式。有些专门的转换工具(如
LCD Image Converter)可以直接生成MicroPython所需的字节数组格式。 - 将转换后的BMP文件上传到ESP32的文件系统中。
假设我们有一个转换好的 cat.bmp 文件,并已上传。我们可以使用以下代码来显示它:
def show_bmp(filename, x, y):
try:
with open(filename, 'rb') as f:
# 跳过BMP文件头(通常54字节)
if f.read(2) == b'BM': # 检查BMP文件标志
f.seek(10) # 偏移到像素数据起始位置
pixel_data_offset = int.from_bytes(f.read(4), 'little')
f.seek(pixel_data_offset) # 跳到像素数据开始处
# 从底部向上逐行读取并显示(BMP存储顺序是从下到上)
for row in range(TFT_HEIGHT-1, -1, -1):
line_data = f.read(TFT_WIDTH * 2) # 假设16位色,每像素2字节
# 这里需要一个将字节数据写入屏幕指定行的函数
# 具体实现取决于你的驱动库,可能需要使用 `tft.blit_buffer` 方法
# tft.blit_buffer(line_data, x, y+row, TFT_WIDTH, 1)
pass # 此处为示意,实际代码需适配驱动库
print(f"Image {filename} displayed.")
except Exception as e:
print(f"Failed to display image: {e}")
# 调用函数,在坐标(0,0)处显示图片
# show_bmp('cat.bmp', 0, 0)
提示:实际上,更通用的做法是使用专门的MicroPython图像库(如
micropython-stub中的framebuf),或者使用离线工具将图片直接转换成Python字节数组代码,然后通过tft.blit_buffer()方法一次性写入。这样可以避免在资源受限的ESP32上进行复杂的文件解析。
4.2 动态绘制与动画效果
直接操作像素来动态生成图案,能带来更大的灵活性。我们可以利用 framebuf 帧缓冲区模块,先在内存中绘制,再一次性刷新到屏幕,这样动画会更流畅。
下面是一个绘制一个跳动的小球的简单动画示例:
import framebuf
import math
import time
# 创建一个内存中的帧缓冲区,格式为RGB565
buffer = bytearray(TFT_WIDTH * TFT_HEIGHT * 2) # 16位色深,每像素2字节
fb = framebuf.FrameBuffer(buffer, TFT_WIDTH, TFT_HEIGHT, framebuf.RGB565)
ball_x = 120
ball_y = 120
ball_radius = 10
speed_x = 3
speed_y = 2
while True:
# 1. 用黑色清空帧缓冲区
fb.fill(0)
# 2. 在帧缓冲区中绘制一个填充圆(作为小球)
fb.fill_circle(int(ball_x), int(ball_y), ball_radius, 0xF800) # 红色
# 3. 将整个帧缓冲区数据一次性发送到屏幕显示
tft.blit_buffer(buffer, 0, 0, TFT_WIDTH, TFT_HEIGHT)
# 4. 更新小球位置,实现反弹逻辑
ball_x += speed_x
ball_y += speed_y
if ball_x <= ball_radius or ball_x >= TFT_WIDTH - ball_radius:
speed_x = -speed_x
if ball_y <= ball_radius or ball_y >= TFT_HEIGHT - ball_radius:
speed_y = -speed_y
# 控制动画帧率
time.sleep(0.02)
这段代码创建了一个在屏幕边界内来回弹跳的红色小球。通过 framebuf 在内存中绘图再整体刷新(blit_buffer),有效避免了直接操作屏幕时的闪烁问题,是制作简单动画的经典模式。
5. 项目实战:打造一个简易的天气信息站
掌握了所有基础技能后,让我们整合一下,创建一个简单的模拟天气信息站界面。这个项目将综合运用文字显示、图形绘制和动态更新。
我们将模拟显示温度、湿度和一个简单的天气图标(用图形绘制代替)。为了简化,我们使用随机数模拟传感器数据。
import random
import time
def draw_weather_icon(icon_type, x, y):
"""根据天气类型绘制简单图标"""
if icon_type == 'sunny':
# 画一个太阳:黄色圆和几条线
tft.fill_circle(x, y, 15, st7789.YELLOW)
for i in range(0, 360, 45):
rad = math.radians(i)
end_x = x + int(25 * math.cos(rad))
end_y = y + int(25 * math.sin(rad))
tft.line(x, y, end_x, end_y, st7789.YELLOW)
elif icon_type == 'cloudy':
# 画一朵云:几个重叠的灰色圆
tft.fill_circle(x-10, y, 10, st7789.LIGHTGREY)
tft.fill_circle(x, y, 12, st7789.LIGHTGREY)
tft.fill_circle(x+10, y, 10, st7789.LIGHTGREY)
elif icon_type == 'rainy':
# 画一朵云和几条蓝色的雨线
draw_weather_icon('cloudy', x, y)
for i in range(-5, 6, 5):
tft.line(x+i, y+15, x+i, y+25, st7789.BLUE)
def update_display(temp, humidity, weather):
"""更新整个显示界面"""
# 清屏,使用浅灰色背景
tft.fill(st7789.color565(230, 230, 230))
# 绘制标题栏
tft.fill_rect(0, 0, TFT_WIDTH, 30, st7789.color565(50, 100, 200))
tft.text("Weather Station", 50, 10, st7789.WHITE)
# 绘制分割线
tft.hline(0, 35, TFT_WIDTH, st7789.DARKGREY)
# 显示天气图标 (居中偏上)
draw_weather_icon(weather, TFT_WIDTH//2, 80)
# 显示温度数据 (左侧)
tft.text("Temperature:", 20, 120, st7789.BLACK)
temp_str = f"{temp:.1f} C"
# 为了显示更大的字体,我们可以用多个矩形和文字组合模拟
tft.fill_rect(20, 140, 100, 40, st7789.color565(255, 200, 200)) # 背景框
tft.text(temp_str, 30, 150, st7789.RED) # 实际项目中建议使用位图字体
# 显示湿度数据 (右侧)
tft.text("Humidity:", 140, 120, st7789.BLACK)
hum_str = f"{humidity:.0f} %"
tft.fill_rect(140, 140, 80, 40, st7789.color565(200, 220, 255))
tft.text(hum_str, 150, 150, st7789.BLUE)
# 底部状态栏
tft.fill_rect(0, TFT_HEIGHT-25, TFT_WIDTH, 25, st7789.DARKGREY)
tft.text("Updated", 10, TFT_HEIGHT-18, st7789.WHITE)
# 可以在这里添加更新时间等
# 主循环,模拟数据更新
weather_types = ['sunny', 'cloudy', 'rainy']
current_weather = 'sunny'
while True:
# 模拟读取传感器数据
simulated_temp = 20 + random.uniform(-2, 2) # 20度上下波动
simulated_humidity = 50 + random.uniform(-10, 10) # 50%上下波动
# 偶尔切换一下天气
if random.random() > 0.95: # 5%的概率切换
current_weather = random.choice(weather_types)
# 更新显示
update_display(simulated_temp, simulated_humidity, current_weather)
# 每隔5秒更新一次
time.sleep(5)
这个实战项目虽然数据是模拟的,但它完整展示了一个典型的信息显示应用的骨架:界面布局、数据区域划分、图形化元素绘制以及定时刷新逻辑。你可以很容易地将模拟数据替换为真实的传感器读数(如DHT11温湿度传感器),一个实用的桌面天气站就初具雏形了。
硬件编程的魅力在于,你能亲眼看到每一行代码如何转化为物理世界的反馈。ST7789这块小屏幕就像一个窗口,通过它,你的程序拥有了色彩和形状。从点亮第一抹红色,到让自定义的图案动起来,这个过程里遇到的每一个问题和解开每一个疑惑,都是实实在在的成长。我自己的第一块屏幕因为接错电源烧了,但也正是那次教训,让我养成了连接前必看电压的好习惯。别怕出错,多动手试,屏幕亮起的那一刻,你会觉得一切都值了。
1763



被折叠的 条评论
为什么被折叠?



