从零点亮 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_eSPITFT_eSPI 是一款 Arduino 兼容的 TFT 屏幕驱动加图形库当前版本 2.5.43把 ILI9341、ST7735、ILI9488 等 16 款以上 TFT 屏和 ePaper 的驱动、图形、字体、触摸打包在一起。它解决的就是给 ESP32、RP2040、STM32 接块 TFT 屏这件事——接线、配置、画图一次搞定。本文面向第一次给开发板加屏幕的你全部事实取自仓库内的配置头文件、示例和文档。先搞清这三件事关键事实仓库依据支持平台ESP8266、ESP32、STM32、RP2040 有逐芯片优化代码其余 Arduino 兼容板走通用实现更慢库大量使用 32 位变量README.txt最小硬件要求硬件 SPI 至少 3 根 GPIOMOSI/SCK/MISO加 CS、DC、RST、电源MISO 可不接User_Setup.h点亮流程装库 → 选/改配置 → 接线 → 编译测试示例共 4 步下文最短路径最短路径点亮屏幕第 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 240x320User_Setups/ 里有 80 多份预设Setup1 到 Setup302覆盖 M5Stack、TTGO T-Display、LilyGo、Nucleo 等常见板子。注意文件头部的警告升级库会覆盖你改过的配置改完记得自己留一份备份。第 3 步按接线图接屏3.5 寸 RPi TFT V3.0480x320ILI9486接到树莓派 GPIO 的官方接线图DC/RST/CS 与 SPI 信号线一目了然没装触摸屏时 T_CS 接 3.3VESP32 这边以 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_Rainbow160x128 / 320x240 / 480x320 各分辨率目录都有。屏幕出颜色说明库、配置、接线三者对齐了。配置速查表改配置时只动 User_Setup.h或你选中的 User_Setups 预设对照这张表即可不用通读 300 多行注释配置项所在文件控制什么怎么改*_DRIVER如ILI9341_DRIVERUser_Setup.h 第 1 节驱动芯片只放开一行其余全部注释TFT_MOSI/SCLK/MISO/CS/DC/RST第 2 节SPI 接线改成你的实际 GPIO复位接板 RST 时写TFT_RST -1TFT_BLTFT_BACKLIGHT_ON第 2 节背光控制可选begin()时自动开背光TFT_WIDTH/TFT_HEIGHT第 1 节ST7735/ST7789/ILI9163/GC9A01 的像素尺寸按屏幕规格写竖屏宽高TFT_RGB_ORDER第 1 节ST7735/ST7789/ILI9341 红蓝顺序红蓝反了就逐个试TFT_RGB/TFT_BGRTFT_INVERSION_ON/OFF第 1 节显示反色白显黑时两个选项逐个试TFT_PARALLEL_8_BIT16bit 仅 RP2040第 1 节并行接口默认 SPI并行屏放开并补 D0~D7、WR、RD 引脚LOAD_GLCD/LOAD_FONT2/4/6/7/8/LOAD_GFXFF第 3 节内置字体全开约占 17KB FLASH注释不用的省 FLASHSMOOTH_FONT第 3 节抗锯齿字体功能不用就注释省约 20KB FLASHSPI_FREQUENCY第 4 节SPI 时钟决定渲染速度ILI9341 可 40MHz80MHz 有时失败ST7735 超过 27MHz 可能花屏SPI_READ_FREQUENCY第 4 节读屏时钟默认 20000000不稳就再降SPI_TOUCH_FREQUENCY第 4 节触摸 XPT2046 时钟固定 2.5MHz一般别动TOUCH_CS第 2 节触摸片选没有触摸屏就保持注释USE_HSPI_PORT第 4 节ESP32 换用 HSPI 端口VSPI 被占用时放开SUPPORT_TRANSACTIONS第 4 节SPI 事务支持同总线还有别的 SPI 设备时必需外部配置路径docs/PlatformIO/External setup for Platform_IO.txtPlatformIO 用库外 User_Setupbuild_flags里加-D TFT_ESPI_USER_SETUP_PATH\../configs/你的/User_Setup.h\ESP-IDF menuconfigdocs/ESP-IDF/Using ESP-IDF.txt、KconfigIDF 下免改头文件配置idf.py menuconfig进 TFT_eSPI 节或直接删 Kconfig 用 User_Setup_Select按需做你想做的事让 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返回指针创建失败是 NULLRAM 不够先判空再用全屏 16bpp 缓冲在大多数开发板上装不下。如何开启 DMA 加速目标SPI 传数不占 CPU帧率翻倍。DMA 配合双 Sprite 乒乓效果最好参考 examples/DMA test/Bouncy_Circles/RP2040 ILI9341 实测 45~48fpstft.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 稳在 40MHz80MHz 有时失败ST7735 不超 27MHz。SPI 总线上还有 SD 卡等其它设备时确认 Transaction 支持开着ESP32 自动开。共享 SPI 的屏别把 SDO 接 MISO——ILI9488 的 SDO 在 CS 拉高时不会三态会干扰其它设备。Sprite 内存按宽 × 高 × 位深/8字节预算createSprite失败会返回 NULL必须判空。屏幕不听话时症状常见原因先做什么全黑没反应背光/电源没通复位线没接驱动宏选错查背光和 5V确认 User_Setup 里只有一行*_DRIVER有图但花屏、错位SPI 时钟超过驱动承受值逐档降SPI_FREQUENCY如 40M→27M→20M红蓝反色RGB/BGR 顺序不对在 ST7735/ST7789/ILI9341 上逐个试TFT_RGB_ORDER白显黑显示反色未开逐个试TFT_INVERSION_ON/TFT_INVERSION_OFF触摸有值但坐标偏移没校准、校准角度不对跑 Touch_calibrate 重新取 5 个值且角度与成品一致读回像素与写入不符SPI 时钟过快或走线过长用 examples/Test and diagnostics/TFT_ReadWrite_Test/ 逐位验证降时钟下一步先跑一遍 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考