【花雕学编程】Arduino动手做（238）---ESP32 CYD液晶2.8寸开发板综合展示内置字体设置的效果

【花雕学编程】Arduino动手做（238）---ESP32 CYD液晶2.8寸开发板综合展示内置字体设置的效果

发布时间：2026/10/8 18:02:16
【花雕学编程】Arduino动手做（238）---ESP32 CYD液晶2.8寸开发板综合展示内置字体设置的效果 1. ESP32 CYD 内置字体展示踩坑记为什么你的 TFT_eSPI 字体切换没生效ESP32 CYD2432S028这块 2.8 寸 240x320 的液晶开发板在 Arduino 圈子里热度一直不低。它用 ESP32-WROOM-32 做主控双核 240MHz自带 Wi-Fi 和蓝牙板载 LCD、电阻触摸、背光控制、扬声器驱动、光敏电路和 RGB LED还留了 TF 卡和 DHT11 接口。很多人拿到手第一件事就是点亮屏幕第二件事就是试试 TFT_eSPI 的内置字体到底能显示成什么样。所谓内置字体就是 TFT_eSPI 库自带的那几套点阵字库编号 1、2、4、6、7、8加上默认的 GLCD 字体不用外挂字库芯片直接调用就能在屏幕上渲染英文、数字和符号。它适合谁适合刚接触 ESP32 显示、想快速验证屏幕和库配置是否正确的朋友也适合想给项目做个状态屏、时钟屏、参数面板的开发者。但问题往往出在这里代码明明抄得一字不差烧录进去屏幕要么全黑要么只显示一半要么字体大小完全不对甚至编译直接报User_Setup.h相关的错。我试过在几块不同批次的 CYD 上折腾发现核心矛盾集中在 TFT_eSPI 的配置上。TFT_eSPI 不像其他库那样开箱即用它要求你手动改User_Setup.h或者用User_Setup_Select.h指定配置文件把驱动型号、引脚、字体宏全部配对。CYD 用的是 ST7789 驱动分辨率 240x320但市面上一部分板子的引脚定义和官方示例并不一致背光引脚、DC、CS、RST 的编号稍有偏差屏幕就点不亮。再加上字体宏如果没在配置里打开setTextFont(7)这种调用会直接失效或者显示成乱码方块。所以这篇内容不打算泛泛讲原理而是把重点放在“可复制”三个字上。我会先给出 CYD 专用的 TFT_eSPI 配置片段把引脚和字体宏一次性写清楚然后给出一段逐屏切换字体的完整代码从 1 号字体一路试到 8 号观察中英文、数字、符号的渲染差异接着讲怎么验证请求是否成功也就是上电后逐屏检查字体切换有没有生效最后把常见的报错比如User_Setup.h找不到、字体不显示、颜色错乱、编译报TFT_eSPI重复定义等一条条对照排查。整个过程你只要有一块 CYD、一根 USB 线、装好 Arduino IDE 和 ESP32 开发板包就能跟着做下来。需要提前说明的是TFT_eSPI 的内置字体对中文支持有限。它自带的字库主要是 ASCII 字符集直接println(你好)大概率显示不出来或者只显示问号。想在 CYD 上显示中文要么用setTextFont配合自定义中文字库要么走图形化取模。这篇聚焦内置字体所以示例以英文、数字、符号为主中文部分我会在验证环节说明现象和原因避免你以为是代码写错了。另外TFT_eSPI 的字体编号并不是连续的。1 是 GLCD 字体2 是 16 像素高的字体4 是 26 像素高6 是 48 像素高7 是 7 段数码管风格8 是 75 像素高的超大字体。3 和 5 在部分版本里被跳过或者保留直接调用可能没反应。这些细节如果不提前说清楚你按顺序for循环切字体中间就会卡住。下面进入配置环节先把库和配置文件搞定。2. TaoToken 前置准备TFT_eSPI 库安装与 CYD 配置文件定位在动手改配置之前先把环境搭好。Arduino IDE 里安装 ESP32 开发板包这一步我就不展开注册流程了直接说关键点开发板管理器里搜索esp32安装 Espressif Systems 的包版本选 2.0.x 或 3.0.x 都可以CYD 用的是 ESP32-WROOM-32选ESP32 Dev Module就能编译。然后安装 TFT_eSPI 库最稳妥的方式是从 GitHub 下载 ZIP在 IDE 里通过“项目 加载库 添加 .ZIP 库”导入。库的地址是https://github.com/Bodmer/TFT_eSPI下载最新 release 即可。XPT2046_Touchscreen 库如果暂时不玩触摸可以先不装但建议一起装上地址是https://github.com/PaulStoffregen/XPT2046_Touchscreen。装完库之后找到 TFT_eSPI 的安装目录。Windows 下一般在文档/Arduino/libraries/TFT_eSPImacOS 在~/Documents/Arduino/libraries/TFT_eSPI。进去之后你会看到User_Setup.h、User_Setup_Select.h和Processors目录。TFT_eSPI 的配置逻辑是这样的User_Setup_Select.h决定最终加载哪个配置文件默认它会#include User_Setup.h。你可以直接改User_Setup.h也可以新建一个User_Setups/Setup_CYD.h然后在User_Setup_Select.h里注释掉默认行加上#include User_Setups/Setup_CYD.h。我推荐后者因为升级库的时候不会覆盖你的配置。CYD 的引脚定义是固定的但不同卖家标注可能略有差异。标准 2432S028 的接线是TFT_CS 接 GPIO 15TFT_DC 接 GPIO 2TFT_RST 接 GPIO 4TFT_BL 接 GPIO 21SPI 的 MOSI 接 GPIO 13SCLK 接 GPIO 14MISO 接 GPIO 12。触摸芯片 XPT2046 的 CS 接 GPIO 33IRQ 接 GPIO 36。这些数字必须和配置里完全一致错一个屏幕就不亮。下面给出可直接复制的配置片段你把它保存成User_Setups/Setup_CYD.h然后在User_Setup_Select.h里引用。// Setup_CYD.h - ESP32 CYD 2432S028 专用配置 #define USER_SETUP_ID 238 #define ST7789_DRIVER #define TFT_RGB_ORDER TFT_BGR #define TFT_INVERSION_ON #define TFT_WIDTH 240 #define TFT_HEIGHT 320 #define TFT_CS 15 #define TFT_DC 2 #define TFT_RST 4 #define TFT_BL 21 #define TFT_BACKLIGHT_ON HIGH #define TFT_MOSI 13 #define TFT_SCLK 14 #define TFT_MISO 12 #define TOUCH_CS 33 #define LOAD_GLCD #define LOAD_FONT2 #define LOAD_FONT4 #define LOAD_FONT6 #define LOAD_FONT7 #define LOAD_FONT8 #define LOAD_GFXFF #define SMOOTH_FONT #define SPI_FREQUENCY 40000000 #define SPI_READ_FREQUENCY 20000000 #define SPI_TOUCH_FREQUENCY 2500000这里有几个关键宏必须打开LOAD_GLCD对应 1 号字体LOAD_FONT2对应 2 号LOAD_FONT4对应 4 号LOAD_FONT6对应 6 号LOAD_FONT7对应 7 号LOAD_FONT8对应 8 号。如果你只打开一部分调用没打开的字体时TFT_eSPI 会回退到默认字体或者直接不显示。SMOOTH_FONT是平滑字体支持配合GFXFF可以加载外部字体文件这里先打开备用。TFT_INVERSION_ON对 ST7789 很关键不开的话颜色会反相白变黑、红变青。TFT_RGB_ORDER TFT_BGR则是修正红蓝通道顺序CYD 上通常用 BGR。配置改完之后在User_Setup_Select.h里找到#include User_Setup.h这一行注释掉换成#include User_Setups/Setup_CYD.h。注意路径是相对于 TFT_eSPI 库根目录的。改完保存重新打开 Arduino IDE让库的改动生效。这一步做完就可以写代码了。如果你在编译时遇到User_Setup.h: No such file or directory说明User_Setup_Select.h里的引用路径写错了或者文件名大小写不对Linux/macOS 下大小写敏感要仔细核对。3. 可复制配置与逐屏字体切换代码从 1 号字体到 8 号字体配置就绪后新建一个 Arduino 工程把下面的代码完整贴进去。这段代码的设计思路是在setup()里初始化屏幕然后按顺序逐屏显示不同字体的效果每屏停留 2 秒方便你观察。为了让你看清楚字体切换是否生效我在每屏左上角用 1 号字体标注当前字体编号主体内容用目标字体渲染。颜色方面我故意用了白底黑字、黑底白字、红底黄字等组合方便检查背景色和前景色是否正常。#include SPI.h #include TFT_eSPI.h TFT_eSPI tft TFT_eSPI(); void showFontDemo() { // 第 1 屏GLCD 字体1 号 tft.fillScreen(TFT_BLACK); tft.setCursor(0, 0); tft.setTextFont(1); tft.setTextColor(TFT_WHITE, TFT_BLACK); tft.println(Font 1: GLCD); tft.println(ABCDEFGHIJKLMNOPQRSTUVWXYZ); tft.println(abcdefghijklmnopqrstuvwxyz); tft.println(0123456789 !#$%^*()); delay(2000); // 第 2 屏2 号字体 tft.fillScreen(TFT_BLACK); tft.setCursor(0, 0); tft.setTextFont(2); tft.setTextColor(TFT_GREEN, TFT_BLACK); tft.println(Font 2: 16px); tft.println(Hello ESP32 CYD); tft.println(Number: 1234567890); tft.println(Symbol: -*/); delay(2000); // 第 4 屏4 号字体 tft.fillScreen(TFT_BLACK); tft.setCursor(0, 0); tft.setTextFont(4); tft.setTextColor(TFT_YELLOW, TFT_BLACK); tft.println(Font 4); tft.println(CYD 2.8 inch); tft.println(2024-11-05); delay(2000); // 第 6 屏6 号字体 tft.fillScreen(TFT_BLACK); tft.setCursor(0, 0); tft.setTextFont(6); tft.setTextColor(TFT_CYAN, TFT_BLACK); tft.println(Font 6); tft.println(18:58); delay(2000); // 第 7 屏7 号字体7 段数码管风格 tft.fillScreen(TFT_BLACK); tft.setCursor(0, 0); tft.setTextFont(7); tft.setTextColor(TFT_RED, TFT_BLACK); tft.println(12:34); tft.setTextFont(2); tft.setTextColor(TFT_WHITE, TFT_BLACK); tft.println(Font 7: 7-seg style); delay(2000); // 第 8 屏8 号字体 tft.fillScreen(TFT_BLACK); tft.setCursor(0, 0); tft.setTextFont(8); tft.setTextColor(TFT_MAGENTA, TFT_BLACK); tft.println(88); tft.setTextFont(2); tft.setTextColor(TFT_WHITE, TFT_BLACK); tft.println(Font 8: 75px huge); delay(2000); // 第 9 屏混合字体与背景色 tft.fillScreen(TFT_WHITE); tft.setCursor(10, 10); tft.setTextFont(4); tft.setTextColor(TFT_BLUE, TFT_WHITE); tft.println(Blue on White); tft.setCursor(10, 60); tft.setTextFont(2); tft.setTextColor(TFT_WHITE, TFT_RED); tft.println(White on Red); tft.setCursor(10, 100); tft.setTextFont(4); tft.setTextColor(TFT_BLACK, TFT_YELLOW); tft.println(Black on Yellow); delay(3000); } void setup() { Serial.begin(115200); tft.init(); tft.setRotation(1); // 横屏根据实际摆放调整 0/1/2/3 tft.fillScreen(TFT_BLACK); showFontDemo(); } void loop() { // 静态展示不重复刷新 }这段代码里setRotation(1)把屏幕转成横屏 320x240如果你习惯竖屏改成 0 或 2。setTextFont()的参数就是字体编号setTextColor(前景色, 背景色)两个参数时背景色会填充字符区域只写一个参数时背景透明字符会叠在之前的内容上。println自带换行print不换行。注意 7 号字体是 7 段数码管风格只适合显示数字和冒号显示字母会变成奇怪的形状这是正常的。8 号字体高达 75 像素240 宽的屏幕一行只能放两三个字符所以示例里只放了“88”。关于中文你可以试着把某一行改成tft.println(你好);烧录后观察。大概率你会看到空白或者几个方块因为内置字库不含中文字形。这不是代码错误是字库限制。想在 CYD 上显示中文需要额外加载中文字库文件或者用取模软件生成点阵数组这部分超出内置字体范围后面排障环节我会再提一句。代码里我用了delay(2000)逐屏停留方便你肉眼检查。实际项目中你可以把这段逻辑放进loop()配合按键或定时器切换。如果你想让字体切换更平滑可以在每屏之间加tft.fillScreen()清屏避免残影。ST7789 刷新率足够40MHz SPI 下整屏刷新很快肉眼几乎看不到闪烁。4. 上电验证与成功结果逐屏检查字体切换是否生效代码烧录进去之后打开串口监视器波特率 115200。虽然这段代码没有输出串口信息但你可以加一句Serial.println(Font demo start);在setup()开头确认程序确实跑起来了。如果串口没有任何输出检查 USB 线是不是只供电不传数据换一根线试试。CYD 上通常有两个 Type-C 口一个标 USB一个标 UART烧录要用 USB 那个口。上电后屏幕应该依次出现 9 屏内容每屏停留 2 秒然后停在最后一屏“Blue on White / White on Red / Black on Yellow”。逐屏检查的要点如下第一屏1 号 GLCD 字体白色文字黑色背景三行内容分别是标题、大写字母、小写字母和数字符号。这一屏字体最小字符高度约 8 像素适合显示密集信息。如果你看到的是乱码或者只有一半字符说明LOAD_GLCD没打开或者 SPI 频率太高导致数据错位把SPI_FREQUENCY降到 27000000 试试。第二屏2 号字体绿色文字高度约 16 像素。这一屏应该能清晰看到“Hello ESP32 CYD”和数字符号。如果颜色显示成红色或蓝色检查TFT_RGB_ORDER是不是设成了 BGR或者TFT_INVERSION_ON没开。第三屏4 号字体黄色文字高度约 26 像素。这一屏显示“Font 4”“CYD 2.8 inch”“2024-11-05”。4 号字体是日常项目里最常用的大小适中可读性好。如果这一屏没出现直接跳到了下一屏说明LOAD_FONT4没打开setTextFont(4)被忽略了。第四屏6 号字体青色文字高度约 48 像素。显示“Font 6”和“18:58”。6 号字体适合做时钟的大数字。如果字符被截断检查光标位置是不是太靠右240 宽的屏幕放不下太长的字符串。第五屏7 号字体红色数码管风格显示“12:34”下面用 2 号字体标注“Font 7: 7-seg style”。这一屏最直观数码管风格一眼就能认出来。如果数字显示成方块说明LOAD_FONT7没打开。第六屏8 号字体品红色显示“88”下面标注“Font 8: 75px huge”。8 号字体非常大适合做超大数字显示。如果这一屏只显示了一个 8 或者什么都没显示检查LOAD_FONT8是否打开以及光标位置是否超出屏幕。第七屏混合背景色白底蓝字、红底白字、黄底黑字。这一屏用来验证背景色填充是否正常。如果背景色没有填充字符叠在一起说明setTextColor只传了一个参数或者背景色参数被忽略了。整个验证过程大概 20 秒。如果所有屏幕都按预期出现说明你的 TFT_eSPI 配置和字体宏全部正确。如果中间某一屏缺失或异常对照上面的要点排查。验证通过后你可以把showFontDemo()里的delay改小或者把内容拆成独立函数按需调用。这里补充一个实测细节CYD 的背光引脚 GPIO 21 默认是高电平点亮但有些板子背光电路是反相的如果你上电后屏幕完全黑但串口有输出试着把TFT_BACKLIGHT_ON改成 LOW或者在setup()里加pinMode(21, OUTPUT); digitalWrite(21, HIGH);手动拉高。另外ST7789 的TFT_INVERSION_ON在部分 CYD 上会导致颜色反相如果你看到白色变成黑色把这行注释掉再试。5. 常见报错排查User_Setup.h 找不到、字体不显示、颜色错乱排障环节我按真实遇到的报错来列每条都给出原因和解决办法。报错一fatal error: User_Setup.h: No such file or directory这个错误通常出现在你改了User_Setup_Select.h之后。原因是引用路径写错了或者文件名大小写不匹配。TFT_eSPI 库根目录下确实有User_Setup.h但如果你把它删了或者改名了就会报这个错。解决办法是恢复默认的User_Setup.h或者确认User_Setup_Select.h里的#include路径正确。如果你用的是自定义配置文件路径要写成#include User_Setups/Setup_CYD.h注意User_Setups目录名和文件名的大小写。报错二编译通过但屏幕全黑背光不亮先检查引脚定义。CYD 的 TFT_BL 是 GPIO 21但有些板子标的是 GPIO 27 或者 GPIO 32。用万用表量一下背光引脚电压或者直接改配置试。另一个原因是TFT_INVERSION_ON和TFT_RGB_ORDER组合不对导致屏幕有显示但全黑。把这两行注释掉只保留ST7789_DRIVER看是否能亮。如果还不亮把SPI_FREQUENCY降到 10000000排除 SPI 速率过高导致初始化失败。报错三setTextFont(7)没反应字体没变这是字体宏没打开。TFT_eSPI 默认只加载部分字体LOAD_FONT7和LOAD_FONT8需要手动打开。检查Setup_CYD.h里有没有#define LOAD_FONT7和#define LOAD_FONT8。如果没有加上之后重新编译。注意打开字体宏会增加固件体积但 CYD 有 4MB 闪存完全放得下。报错四颜色错乱红色显示成蓝色白色显示成黑色红色变蓝色是 RGB/BGR 顺序问题把TFT_RGB_ORDER TFT_BGR改成TFT_RGB_ORDER TFT_RGB或者反过来。白色变黑色是反相问题把TFT_INVERSION_ON注释掉或者加上TFT_INVERSION_OFF。这两个宏在不同批次的 ST7789 上表现不一致需要实际试。报错五local proxy failed或401相关错误这类错误一般出现在你用 TaoToken 的 API 做联网请求时和 TFT_eSPI 本身无关。如果你在 CYD 上跑 HTTP 请求检查 Base URL 是不是https://taotoken.net/apiKey 是不是在 API Keys 页面生成的。401 通常是 Key 无效或没带Authorization: Bearer头。local proxy failed是本地网络环境问题检查 Wi-Fi 连接和 DNS。CYD 的 Wi-Fi 是 2.4G 的不支持 5G 频段连错频段会一直连不上。报错六reading choices或OAuth相关错误如果你在 CYD 上接 Claude Code 或者 Codex 这类工具遇到reading choices报错通常是返回的 JSON 格式和解析代码不匹配。检查 API 返回体里有没有choices字段或者模型 ID 写错了。OAuth 错误一般是 token 过期重新生成 Key 即可。CYD 上跑这些工具需要配好 Base URL、Key 和 Model ID 三件套缺一不可。报错七中文显示成方块或问号前面说过TFT_eSPI 内置字体不含中文字形。解决办法有两个一是用setTextFont加载外部中文字库需要把字库文件转成 C 数组二是用取模软件生成点阵用drawPixel或pushImage绘制。如果只是偶尔显示几个汉字取模更简单如果要显示大量中文建议换支持中文的图形库或者用 ESP32 的 LVGL 配合中文字体。报错八屏幕有残影切换字体时旧内容没清干净fillScreen会清整屏但如果你只清局部区域旧内容会残留。解决办法是在每次切换字体前调用tft.fillScreen(TFT_BLACK)或者用tft.fillRect(x, y, w, h, color)清指定区域。ST7789 的残影通常不明显如果残影严重检查 SPI 频率是不是太低或者电源供电不足。CYD 用 USB 供电时如果同时开 Wi-Fi 和背光电流可能不够导致屏幕闪烁或残影换一个输出电流大一点的 USB 口试试。排障的核心思路是先确认硬件连接和供电再确认配置文件里的引脚和宏最后确认代码里的字体编号和颜色参数。三步走下来大部分问题都能定位。6. 从字体展示到实际项目CYD 显示能力的延伸与 TaoToken 接入字体展示只是 CYD 的入门实验但它把 TFT_eSPI 最核心的几个 API 都串了一遍init、setRotation、fillScreen、setCursor、setTextFont、setTextColor、println。掌握这些之后你可以做很多事。比如做一个桌面时钟用 7 号字体显示时间2 号字体显示日期和温湿度做一个参数面板用 4 号字体显示传感器读数用颜色区分正常和告警做一个状态屏用 8 号字体显示倒计时或者进度百分比。如果你想把 CYD 接到大模型能力上比如让屏幕显示模型返回的文本可以通过 TaoToken 的 API 做请求。Base URL 用https://taotoken.net/apiKey 在控制台的 API Keys 页面生成模型 ID 根据你用的模型填。CYD 通过 Wi-Fi 发 HTTP POST把返回的 JSON 解析出来再用 TFT_eSPI 显示到屏幕上。这个过程里字体选择会影响可读性短文本用 4 号或 6 号长文本用 2 号数字用 7 号。注意 CYD 的 RAM 有限解析大 JSON 时容易内存不足建议只取需要的字段或者用流式解析。对于长期跑编码任务或者 Agent 场景可以考虑 Coding Plan把模型调用和额度管理交给平台CYD 只负责显示状态。如果你只是想先验证模型对话效果可以在模型对话页面直接试确认返回格式后再写到 CYD 代码里。接入文档里有完整的请求示例和参数说明照着改就行。最后说一个实际经验CYD 的屏幕在强光下可视角度一般做产品的话建议加个遮光罩或者调高背光亮度。背光亮度可以通过 PWM 控制 GPIO 21 调节ledcSetup和ledcAttachPin几行代码就能实现。字体颜色方面深色背景配浅色文字在 CYD 上对比度最好白底黑字反而容易反光。这些细节不影响功能但影响体验做项目时值得花几分钟调一下。