保姆级教程：用ESP32和TFT_eSPI库驱动1.3寸ST7789屏幕，从接线到显示中文全搞定-深圳市維司達科技有限公司

ESP32与ST7789屏幕实战：从硬件对接到中文显示的完整指南

刚拿到一块1.3寸ST7789屏幕时，面对密密麻麻的引脚和陌生的代码库，很多开发者都会感到无从下手。本文将带你从零开始，用ESP32驱动这块小巧但功能强大的SPI屏幕，最终实现中文显示——整个过程就像搭积木一样简单明了。不同于零散的教程，这里提供的是一套经过验证的完整解决方案，包含硬件连接、库配置、基础图形绘制和中文处理的每个细节。

1. 硬件准备与连接

1.1 所需材料清单

在开始前，请确保备齐以下组件：

ESP32开发板（推荐使用NodeMCU-32S或ESP32 DevKit）
1.3寸ST7789 SPI屏幕模块（240×240分辨率）
杜邦线（建议使用不同颜色区分功能）
微型面包板（可选，方便测试）
USB数据线（用于供电和程序烧录）

1.2 引脚连接详解

ST7789与ESP32的SPI通信需要正确连接6个关键引脚。以下是经过优化的接线方案：

屏幕引脚	ESP32引脚	功能说明
GND	GND	接地
VCC	3.3V	电源（切勿接5V）
SCL	GPIO18	SPI时钟线
SDA	GPIO23	SPI数据线
RES	GPIO17	复位信号（低电平有效）
DC	GPIO16	数据/命令选择
BLK	GPIO4	背光控制（高电平开启）

注意：不同厂商的屏幕引脚标注可能略有差异，务必对照产品说明书确认。若屏幕无BLK引脚，可直接接3.3V常亮。

1.3 硬件连接技巧

使用彩色杜邦线按功能分组连接（如红色接电源，黑色接地，黄色接数据线）
若出现屏幕闪烁，可在VCC和GND之间并联一个100μF电容稳定电压
长距离连接时，建议在SCL和SDA线上串联100Ω电阻减少信号反射

2. 软件环境搭建

2.1 安装TFT_eSPI库

TFT_eSPI是专为TFT屏幕优化的Arduino库，支持多种驱动芯片。推荐通过PlatformIO安装：

# 在PlatformIO项目的lib目录下执行 git clone https://github.com/Bodmer/TFT_eSPI.git

或使用Arduino IDE的库管理器直接搜索安装。

2.2 关键配置修改

库安装后，需要修改User_Setup.h文件（位于库目录下的User_Setups文件夹）：

// 主要配置项 #define ST7789_DRIVER // 指定驱动芯片 #define TFT_WIDTH 240 // 屏幕宽度 #define TFT_HEIGHT 240 // 屏幕高度 // 引脚定义（与硬件连接一致） #define TFT_MOSI 23 // SDA #define TFT_SCLK 18 // SCL #define TFT_CS -1 // 未使用片选 #define TFT_DC 16 // 数据/命令 #define TFT_RST 17 // 复位 #define TFT_BL 4 // 背光控制

常见配置错误及解决方法：

屏幕显示错乱：检查ST7789_DRIVER是否正确定义
触摸无反应：确认TOUCH_CS引脚未错误定义
背光不亮：确保TFT_BL引脚配置正确且代码中已启用

3. 基础显示功能实现

3.1 初始化与清屏

创建基础测试程序验证硬件连接：

#include <TFT_eSPI.h> TFT_eSPI tft = TFT_eSPI(); void setup() { tft.init(); tft.setRotation(1); // 根据屏幕实际方向调整 tft.fillScreen(TFT_BLACK); pinMode(TFT_BL, OUTPUT); digitalWrite(TFT_BL, HIGH); // 开启背光 } void loop() { // 后续功能在此添加 }

3.2 图形绘制API实战

TFT_eSPI提供了丰富的图形绘制功能：

// 绘制红色矩形边框 tft.drawRect(10, 10, 100, 50, TFT_RED); // 填充蓝色圆角矩形 tft.fillRoundRect(50, 70, 120, 60, 10, TFT_BLUE); // 画对角线 tft.drawLine(0, 0, 239, 239, TFT_GREEN); // 绘制渐变效果 for(int i=0; i<240; i++) { tft.drawFastVLine(i, 0, 240, tft.color565(i, 255-i, 127)); }

3.3 文本显示进阶

显示不同大小和颜色的文本：

tft.setTextColor(TFT_WHITE, TFT_BLACK); // 白字黑底 // 小号字体 tft.setTextSize(1); tft.setCursor(10, 10); tft.print("Small Text"); // 大号字体 tft.setTextSize(3); tft.setCursor(10, 30); tft.print("Large Text"); // 使用内置字体 tft.loadFont(NotoSansBold20); tft.drawString("Custom Font", 10, 60); tft.unloadFont();

4. 中文显示解决方案

4.1 字库制作全流程

实现中文显示需要自定义字库，以下是详细步骤：

准备工具：
- 下载Processing IDE（https://processing.org/）
- 获取TFT_eSPI库中的Create_Smooth_Font工具
- 准备中文字体文件（如微软雅黑）
生成字库文件：
- 修改Create_font项目中的unicodeBlocks数组，添加中文范围：
```
static final int[] unicodeBlocks = { 0x4E00, 0x9FFF, // 基本汉字 0x3000, 0x303F, // 中文标点 0xFF00, 0xFFEF // 全角字符 };
```
- 运行Processing脚本生成.vlw字库文件

转换字库格式：使用Hex转换工具将.vlw文件转换为C数组，保存为头文件：

// font_yahei24.h const uint8_t yahei24[] PROGMEM = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // 字模数据... };

4.2 中文显示实战

将生成的字库文件加入项目后：

#include "font_yahei24.h" void showChinese() { tft.loadFont(yahei24); // 加载自定义字库 tft.setTextColor(TFT_WHITE); tft.drawString("你好，ESP32！", 10, 50); tft.drawString("温度:25℃", 10, 80); tft.unloadFont(); // 释放字库内存 }

4.3 优化技巧

部分字库：只包含常用汉字减少体积
内存管理：及时调用unloadFont()释放资源
混合显示：中英文使用不同字号时分开渲染

5. 高级应用与性能优化

5.1 双缓冲技术

对于动态内容，使用双缓冲避免闪烁：

TFT_eSprite sprite = TFT_eSprite(&tft); void setup() { sprite.createSprite(240, 240); // 创建缓冲区 } void loop() { sprite.fillSprite(TFT_BLACK); sprite.drawString("帧率测试", 10, 10); sprite.pushSprite(0, 0); // 一次性输出到屏幕 }

5.2 触摸功能集成

若屏幕支持触摸，可添加交互功能：

#include <XPT2046_Touchscreen.h> XPT2046_Touchscreen ts(TOUCH_CS); void setup() { ts.begin(); } void loop() { if (ts.touched()) { TS_Point p = ts.getPoint(); tft.fillCircle(p.x, p.y, 5, TFT_RED); } }

5.3 性能基准测试

通过以下代码测试屏幕刷新率：

uint32_t start = millis(); for(int i=0; i<100; i++) { tft.fillScreen(TFT_BLACK); tft.fillScreen(TFT_WHITE); } uint32_t fps = 200000 / (millis() - start); tft.drawNumber(fps, 10, 10); // 显示每秒帧数

典型优化手段：