企业官网建设流程全解析

从零点亮 TFT 屏幕：TFT_eSPI 驱动库 4 步实战配置教程

【免费下载链接】TFT_eSPIArduino and PlatformIO IDE compatible TFT library optimised for the Raspberry Pi Pico (RP2040), STM32, ESP8266 and ESP32 that supports different driver chips项目地址: https://gitcode.com/GitHub_Trending/tf/TFT_eSPI

TFT_eSPI 是一款 Arduino 兼容的 TFT 屏幕驱动加图形库（当前版本 2.5.43），把 ILI9341、ST7735、ILI9488 等 16 款以上 TFT 屏和 ePaper 的驱动、图形、字体、触摸打包在一起。它解决的就是"给 ESP32、RP2040、STM32 接块 TFT 屏"这件事——接线、配置、画图一次搞定。本文面向第一次给开发板加屏幕的你，全部事实取自仓库内的配置头文件、示例和文档。

先搞清这三件事

最短路径点亮屏幕

第 1 步：把库放进工程

git clone https://gitcode.com/GitHub_Trending/tf/TFT_eSPI

克隆完成后，把 TFT_eSPI 目录放进 Arduino IDE 的libraries文件夹，或在 PlatformIO 里作为库引入。这一步只负责"让编译器能找到库"。

第 2 步：选定一份与你硬件一致的配置

打开 User_Setup_Select.h，默认包含根目录的 User_Setup.h。如果硬件有现成预设，注释掉默认行、放开对应行即可，只留一行生效：

//#include <User_Setup.h> // Default setup is root library folder #include <User_Setups/Setup42_ILI9341_ESP32.h> // ESP32 + SPI ILI9341 240x320

User_Setups/ 里有 80 多份预设（Setup1 到 Setup302），覆盖 M5Stack、TTGO T-Display、LilyGo、Nucleo 等常见板子。注意文件头部的警告：升级库会覆盖你改过的配置，改完记得自己留一份备份。

第 3 步：按接线图接屏

3.5 寸 RPi TFT V3.0（480x320，ILI9486）接到树莓派 GPIO 的官方接线图，DC/RST/CS 与 SPI 信号线一目了然；没装触摸屏时 T_CS 接 3.3V：

ESP32 这边以 UNO 引脚布局板为例，SPI 一排（SD2/SD3/CK/MOSI/CSSD1）在板边标注得很清楚，接屏前对一下丝印：


然后把 User_Setup 里的引脚宏改成你实际用的脚。以 ESP32 + ILI9341 为例：

#define TFT_MOSI 23 #define TFT_SCLK 18 #define TFT_CS 15 #define TFT_DC 2 #define TFT_RST 4

引脚写错是黑屏的头号原因，改完这一步别急着编译，先对着实物数一遍线。

第 4 步：编译一个测试示例验证

打开 examples/ 里按分辨率分好的示例，先跑一个最简单的：

#include <TFT_eSPI.h> TFT_eSPI tft = TFT_eSPI(); void setup() { tft.init(); tft.fillScreen(TFT_RED); } void loop() {}

或者直接用现成的TFT_Rainbow（160x128 / 320x240 / 480x320 各分辨率目录都有）。屏幕出颜色，说明库、配置、接线三者对齐了。

配置速查表

改配置时只动 User_Setup.h（或你选中的 User_Setups 预设），对照这张表即可，不用通读 300 多行注释：

按需做你想做的事

让 XPT2046 触摸屏可用（使用方法）

目标：点哪显示哪。

先在 User_Setup 里放开触摸片选：

#define TOUCH_CS 21

再跑 examples/Generic/Touch_calibrate/Touch_calibrate.ino，串口会输出 5 个校准值，写回代码：

uint16_t calData[5] = { 286, 3534, 283, 3600, 6 }; // 示例值，以校准输出为准 tft.setTouch(calData);

uint16_t x, y; if (tft.getTouch(&x, &y)) { // 有按压才为 true tft.fillCircle(x, y, 4, TFT_RED); }

坑：校准是在某个旋转角度下做的，返回坐标只对应那个角度——改tft.setRotation()就得重新校准。

使用抗锯齿平滑字体

目标：文字边缘没有锯齿。

User_Setup 里必须有#define SMOOTH_FONT（默认开着）。字库用 Tools/Create_Smooth_Font/Create_font/Create_font.pde 从 ttf 生成，仓库 examples/Smooth Fonts/ 里现成带NotoSansBold15.h这类字头：

#include "NotoSansBold15.h" // 字体数组名，不能加引号引用 tft.setTextColor(TFT_WHITE, TFT_BLACK); // 第二参数是背景色 tft.loadFont(NotoSansBold15); tft.println("Smooth 15pt"); tft.unloadFont();

坑：抗锯齿靠"文字色 + 背景色"逐像素混合，setTextColor(fg, bg)的背景色必须设对，否则字与字之间会留色边。

无闪烁动画：Sprite 缓冲区

目标：旋转、刷新不闪。

Sprite 是一块 RAM 里的"画布"，画完一次性推到屏幕，参考 examples/Sprite/Rotated_Sprite_1/：

TFT_eSprite spr = TFT_eSprite(&tft); spr.setColorDepth(8); // 8bpp：同样尺寸 RAM 占用是 16bpp 的 1/2 spr.createSprite(64, 30); spr.fillSprite(TFT_BLACK); spr.drawString("Hello", 32, 15, 4); spr.pushRotated(45, TFT_BLACK); // 按 45° 推出，黑色作透明色

坑：createSprite返回指针，创建失败是 NULL（RAM 不够），先判空再用；全屏 16bpp 缓冲在大多数开发板上装不下。

如何开启 DMA 加速

目标：SPI 传数不占 CPU，帧率翻倍。

DMA 配合"双 Sprite 乒乓"效果最好，参考 examples/DMA test/Bouncy_Circles/（RP2040 + ILI9341 实测 45~48fps）：

tft.init(); tft.initDMA(); // 初始化 DMA 并挂到 SPI 总线 // 两个半屏 Sprite 交替：画一个，推另一个 sprPtr[0] = (uint16_t*)spr[0].createSprite(240, 160); sprPtr[1] = (uint16_t*)spr[1].createSprite(240, 160);

坑：缓冲要真金白银的 RAM（示例注释写得很直白：240x320 全屏缓冲是 150KB），先算宽x高x2字节，不够就改小尺寸或降位深。

上线前检查

• SPI 时钟按驱动上限设：ILI9341 稳在 40MHz（80MHz 有时失败），ST7735 不超 27MHz。
• SPI 总线上还有 SD 卡等其它设备时，确认 Transaction 支持开着（ESP32 自动开）。
• 共享 SPI 的屏别把 SDO 接 MISO——ILI9488 的 SDO 在 CS 拉高时不会三态，会干扰其它设备。
• Sprite 内存按宽 × 高 × 位深/8字节预算，createSprite失败会返回 NULL，必须判空。

屏幕不听话时

下一步

先跑一遍 Read_User_Setup 确认编译器吃进的是你想用的那份配置，再刷一个TFT_Rainbow和一次TFT_ReadWrite_Test收尾。配置改完立刻备份一份到库目录外面——升级库会把你改过的 User_Setup 直接覆盖掉。

【免费下载链接】TFT_eSPIArduino and PlatformIO IDE compatible TFT library optimised for the Raspberry Pi Pico (RP2040), STM32, ESP8266 and ESP32 that supports different driver chips项目地址: https://gitcode.com/GitHub_Trending/tf/TFT_eSPI