Arduino IDE 配置 TFT_eSPI 库函数：从 User_Setup.h 到屏幕点亮

1. 从一块不亮的 ST7789 说起TFT_eSPI 到底卡在哪如果你手上有一块 1.3 寸或 1.8 寸的 TFT 小屏驱动芯片是 ST7789、ILI9341、ILI9163 这类接线也照着卖家给的表格插好了结果 Arduino IDE 上传程序后屏幕要么全白、要么全黑、要么花屏那大概率不是屏坏了而是 TFT_eSPI 这个库没配对。TFT_eSPI 和别的显示库不太一样它把屏幕型号、引脚、字体、SPI 频率这些全部塞进一个叫User_Setup.h的头文件里编译时直接写死进固件。也就是说你不改这个文件库根本不知道你接的是哪块屏、哪根线接在哪。这篇就围绕 Arduino IDE 下 TFT_eSPI 库的配置与函数调用展开面向驱动 ST7789 / ILI9341 等 TFT 屏的开发者。我会给出一份可以直接抄的User_Setup.h骨架和引脚映射然后一步步演示tft.init()、tft.fillScreen()、tft.setTextColor()、tft.setCursor()这些核心函数怎么验证让你快速把屏幕点亮并且确认库函数真的生效了。整个过程不需要额外装驱动只要 Arduino IDE 加一块开发板加几根杜邦线。先说清楚适合谁如果你用的是 ESP32、ESP8266、Arduino UNO、Nano、Leonardo 这类常见板子想驱动 SPI 接口的 TFT 彩屏并且希望用一套统一的绘图 API 而不是自己写寄存器那 TFT_eSPI 就是省事的选择。它支持基本绘图、文字、图片还能跑在较高 SPI 频率下刷屏速度比很多老库快不少。代价就是配置这一步必须做对做错就是黑屏。2. 前置准备装库、认引脚、把 TaoToken 的 Key 备好2.1 安装 TFT_eSPI 库打开 Arduino IDE菜单栏工具→管理库搜索TFT_eSPI作者是 Bodmer安装最新版即可。装完之后先别急着写代码因为默认配置是给 ILI9341 用的引脚也是库作者假设的一套跟你实际接线几乎不可能一样。安装完成后库文件一般在你的 Arduino 库目录下路径类似Documents/Arduino/libraries/TFT_eSPI/里面有个User_Setup.h这就是我们要改的核心文件。旁边还有User_Setup_Select.h它负责决定最终用哪个 setup 文件。默认情况下User_Setup_Select.h会 includeUser_Setup.h所以我们直接改User_Setup.h最省事。2.2 确认你的屏幕和接线以常见的 ST7789 240x240 为例SPI 接口一般有这些引脚屏幕引脚含义ESP32 建议引脚VCC电源 3.3V3V3GND地GNDSCL / SCKSPI 时钟GPIO 18SDA / MOSISPI 数据GPIO 23RES / RST复位GPIO 4DC / RS数据/命令GPIO 2CS片选GPIO 15BLK背光3V3 或 GPIO 21注意两点第一很多模块的 BLK 直接接 3.3V 就常亮接 GPIO 才能用代码调亮度第二ESP32 的 SPI 引脚可以重映射但为了稳定建议用上面这套默认 VSPI 引脚。ILI9341 的接线逻辑一样只是分辨率通常是 240x320。2.3 关于 TaoToken 的 API Key配置和调试阶段其实用不到网络但如果你后面想让屏幕显示模型返回的文字或者做联网小终端就需要一个稳定的 API 入口。我习惯在 TaoToken 上开一个 Key 备用地址是https://taotoken.net/api控制台里可以创建 API Keys文档在接入文档页。这个 Key 先放着等屏幕点亮、库函数验证通过之后再拿来做联网显示会顺很多。现在重点还是先把屏点亮。3. 可复制的 User_Setup.h 骨架与引脚映射3.1 打开并清空默认内容找到TFT_eSPI/User_Setup.h用编辑器打开。最稳妥的做法是把里面内容全部注释掉或删掉换成下面这份骨架。因为默认文件里有一堆#define是给别的屏用的留着容易冲突。3.2 ST7789 240x240 配置骨架// User_Setup.h - ST7789 240x240 on ESP32 #define ST7789_DRIVER // 分辨率 #define TFT_WIDTH 240 #define TFT_HEIGHT 240 // 颜色顺序如果红蓝反了就改这里 #define TFT_RGB_ORDER TFT_RGB // #define TFT_RGB_ORDER TFT_BGR // SPI 引脚 #define TFT_MOSI 23 #define TFT_SCLK 18 #define TFT_CS 15 #define TFT_DC 2 #define TFT_RST 4 // 背光如果 BLK 接的是 GPIO 就打开 // #define TFT_BL 21 // #define TFT_BACKLIGHT_ON HIGH // SPI 频率 #define SPI_FREQUENCY 40000000 // 字体 #define LOAD_GLCD #define LOAD_FONT2 #define LOAD_FONT4 #define LOAD_FONT6 #define LOAD_FONT7 #define LOAD_FONT8 #define LOAD_GFXFF #define SMOOTH_FONT这份配置里ST7789_DRIVER是关键它告诉库用哪套初始化序列。TFT_WIDTH和TFT_HEIGHT必须和你的屏一致240x240 的 ST7789 如果写成 240x320画面会错位。TFT_RGB_ORDER决定红蓝通道顺序如果点亮后颜色明显偏比如该红的地方显示蓝就换成TFT_BGR。3.3 ILI9341 240x320 配置差异如果你用的是 ILI9341把驱动和分辨率换掉即可其余引脚定义不变#define ILI9341_DRIVER #define TFT_WIDTH 240 #define TFT_HEIGHT 320ILI9341 一般不需要手动设 RGB 顺序默认就行。SPI 频率可以先保持 40MHz如果花屏就降到 27MHz 试试。3.4 检查 User_Setup_Select.h打开同目录的User_Setup_Select.h确认里面没有被#include到别的 setup 文件。正常情况下它只有一行有效的#include User_Setup.h如果看到类似#include User_Setups/Setup1_ILI9341.h这种被取消注释的行把它注释掉否则你改的User_Setup.h不会生效。这是很多人改完没反应的头号原因。4. 验证请求用最小程序点亮并确认库函数生效4.1 最小验证代码新建一个 sketch写入下面这段。它依次调用tft.init()、tft.fillScreen()、tft.setTextColor()、tft.setCursor()、tft.println()每一步都能在屏幕上看到结果。#include TFT_eSPI.h TFT_eSPI tft TFT_eSPI(); void setup() { Serial.begin(115200); tft.init(); Serial.println(init done); tft.setRotation(0); // 1. 整屏填充红色 tft.fillScreen(TFT_RED); delay(1000); // 2. 整屏填充黑色 tft.fillScreen(TFT_BLACK); delay(500); // 3. 设置文字颜色和背景 tft.setTextColor(TFT_WHITE, TFT_BLACK); tft.setTextSize(2); // 4. 设置光标位置并输出 tft.setCursor(20, 40); tft.println(TFT_eSPI OK); tft.setCursor(20, 80); tft.setTextColor(TFT_GREEN, TFT_BLACK); tft.println(ST7789 240x240); // 5. 画个矩形确认绘图函数 tft.drawRect(20, 120, 200, 60, TFT_BLUE); tft.fillRect(30, 130, 180, 40, TFT_YELLOW); } void loop() { }4.2 每一步应该看到什么上传后打开串口监视器波特率 115200。正常流程是屏幕先整屏变红一秒后变黑然后左上角出现白色TFT_eSPI OK下面一行绿色ST7789 240x240再下面一个蓝色边框、黄色填充的矩形。串口会打印init done。如果红色出现了说明tft.init()和tft.fillScreen()都通了SPI 通信没问题。如果文字出来了说明setTextColor、setCursor、println这条链路也通了。到这一步库函数就算验证成功。4.3 颜色和坐标的对照理解tft.fillScreen(TFT_RED)接受一个 16 位或 32 位颜色值TFT_eSPI 预定义了一堆颜色常量也可以自己用tft.color565(r, g, b)生成。tft.setCursor(x, y)的坐标原点在屏幕左上角x 向右增大y 向下增大。tft.setTextColor(fg, bg)第二个参数是背景色带上它文字刷新时不会残留旧像素做动态显示时很有用。5. 本篇常见错排查5.1 屏幕全黑串口有 init done先量背光。BLK 没接或接错屏幕就是黑的但 SPI 其实在跑。把 BLK 接 3.3V 试一下。如果背光亮了但没画面检查TFT_CS、TFT_DC、TFT_RST三个脚有没有接反。DC 接错是最常见的表现为完全无显示或随机噪点。5.2 花屏、雪花、颜色错乱优先降 SPI 频率。把SPI_FREQUENCY从 40000000 改成 27000000 甚至 20000000。杜邦线越长、越杂高频越容易出错。其次是颜色顺序红蓝互换就改TFT_RGB_ORDER。如果画面整体偏移或重复检查TFT_WIDTH、TFT_HEIGHT是否和实际屏一致。5.3 编译报错找不到 TFT_eSPI.h库没装好或者装到了错误的库目录。重新在库管理器里装一次确认Documents/Arduino/libraries/TFT_eSPI/存在。另外注意不要同时装多个版本的 TFT_eSPI会冲突。5.4 改了 User_Setup.h 但没变化九成是User_Setup_Select.h里 include 了别的文件。打开它逐行看只保留#include User_Setup.h这一行有效。改完记得重新编译Arduino IDE 有时会缓存可以关掉重开。5.5 文字显示但位置不对setRotation()会影响坐标系。如果你设了setRotation(1)或3宽高会对调原来的坐标就不对了。调试阶段先用setRotation(0)确认无误再改方向。6. 点亮之后把库函数用顺再接上模型输出屏幕点亮只是第一步。TFT_eSPI 的函数体系其实很统一fillScreen管清屏setCursor管定位setTextColor管配色drawRect、fillRect、drawLine、drawCircle管图形pushImage管图片。你把这几个用熟做一个天气小屏、串口监视器、甚至模型对话终端都不难。如果你打算让屏幕显示联网内容比如把模型返回的文本打到 TFT 上那就需要一个 API Key。我一般会在 TaoToken 控制台创建 API Keys接入文档里有完整的请求示例模型对话页可以直接试返回格式。调试阶段建议先用模型对话确认返回结构再写进 ESP32 的 HTTP 请求里这样能少走很多弯路。长期做编码类项目或者 Agent 的话Coding Plan 会更合适额度稳定不用每次临时开 Key。最后留一个实用习惯每次改完User_Setup.h先跑第 4 节那段最小验证代码确认红屏、黑屏、文字、矩形都正常再去写业务逻辑。这样一旦出问题你能立刻判断是配置层还是应用层排查范围小很多。屏幕这东西配置对了就是几行代码的事配置错了能耗你一晚上顺序别搞反。