尧图网页设计 
简介这是一份基于Arduino IDE与ESP32微控制器、驱动TFT 7789显示屏实现太空人表盘完整复刻的工程资源包适合物联网爱好者、嵌入式初学者及DIY创客参考学习。包内文件总数1498个压缩包约5.46MB以cpp、h、hpp、ino等源码文件为主同时包含vlw字体资源、JSON配置、Shell脚本、Markdown说明等覆盖Arduino库依赖、示例程序与项目构建配置便于直接梳理和复用。目前已有970人学习下载。通过源码与说明文档可掌握ESP32的SPI屏幕驱动、Adafruit GFX绘图、Wi-Fi联网获取天气数据并在表盘上动态更新等关键实现思路还可借鉴像素画太空人素材的定位方式与项目整体组织逻辑适合希望从零跑通并二次开发该表盘效果的读者。 上个月翻出一块吃灰很久的1.54寸TFT彩屏刚好手头又有ESP32开发板就想着把网上很火的那个太空人表盘复刻出来。这个项目从外面看就是一个动态的太空人行走动画叠在表盘上再加一行时间文字做成桌面小摆件。但真正动手做才发现ESP32、ST7789屏幕驱动、动画素材取模、UI分层绘制、NTP网络对时这些环节每一个单拎出来都有不少坑尤其是对刚接触Arduino开发ESP32的人来说经常卡在“屏幕白屏”和“动画帧率上不去”这两个地方。这篇文章不打算直接甩一个成品工程完事而是把这个复刻项目里真正让人头疼的细节逐段拆开讲一遍屏幕驱动怎么配才不花屏、太空人GIF怎么变成能上屏的RGB565帧、动画和时间文字怎么分层画不打架、NTP对时为什么总是快8小时、最后怎么让动画跑顺不残影。所有代码以Arduino IDE 官方ESP32核心为主新手跟着操作就能复现老手也能拿去当配置清单参考。1. 拆解太空人表盘这个复刻项目的真实工作量先别急着写代码把表盘的设计拆开看复杂度就清晰了。所谓太空人表盘本质上就是几层内容叠在一起最底层表盘底图包括背景色、外圈刻度、品牌文字或小装饰。中间层太空人行走动画通常是8到12帧循环播放。上层时间、日期、秒数等动态文字。可选层步数进度环、电量百分比、温湿度数据。理解了这层结构你就明白这个项目不是一个“大而全”的程序而是可以拆成几个独立模块先把屏幕点亮再解决素材然后写UI渲染最后接网络对时。每个模块单独调通再组合比憋一个大程序再一起调要省心得多。硬件选型上我用的是一片很常见的ESP32 DevKitC V4开发板加一块1.54寸240x240分辨率的ST7789 SPI屏幕。选ESP32的原因很直接RAM有520KBFlash有4MB以上SPI外设速度足够而且自带WiFi和蓝牙后面做NTP对时、蓝牙调设置都很方便。对比之下ESP8266虽然便宜但RAM只有160KB跑图像缓冲会比较吃力。屏幕选ST7789则是因为存量极大、资料多、价格低出问题时好搜解决方案。接线表可以直接照抄不同卖家丝印可能略有差异但基本都逃不出这几根线VCC → 3.3VGND → GNDSCL/SCK → GPIO18SDA/MOSI → GPIO23RES/RST → GPIO4DC → GPIO2CS → GPIO5BLK/BL → GPIO15背光也可以直接接3.3V常亮但留引脚方便后续PWM调亮度接好之后别急着焊死先用杜邦线测试因为后期很可能要换DC引脚或调整SPI频率焊死了改动就麻烦。项目功能上也要分清主次。基础版只需要“时间显示 太空人动画循环”这个跑通后再往上面加日期、星期、电量、进度环这些可选功能。一上来就想全功能很容易在调试阶段被多个变量同时干扰最后哪个都没做好。2. ST7789驱动从白屏到稳定显示的完整配置2.1 为什么选TFT_eSPI而不是Adafruit库Arduino生态里驱动ST7789的库主要分两派一派是Adafruit GFX Adafruit ST7735/ST7789组合另一派是TFT_eSPI。Adafruit的库文档多、API友好很适合初学者但性能差距比较大。TFT_eSPI针对ESP32做了很多底层优化内置了DMA推屏、平滑圆弧、宽线条等函数对“高频刷图”这种场景帮助巨大。太空人动画恰恰就是典型的推图密集型任务Adafruit库能跑但明显会卡TFT_eSPI配合DMA能快上一截而且它本身就把ST7789列为默认支持之一配置门槛并不高。安装方式很简单Arduino IDE的库管理器里搜TFT_eSPI直接装。需要提醒的是这个库不像普通库那样装完即用必须编辑库目录下的User_Setup.h文件告诉它你用的屏幕型号和引脚。建议用VS Code或记事本单独打开这个文件修改别在Arduino IDE自带的编辑器里改偶尔会遇到编码格式导致编译报错。2.2 User_Setup.h里真正影响成败的几行打开User_Setup.h先把ST7789驱动这一行打开#define ST7789_DRIVER接着设置屏幕宽高。ST7789本身RAM是240x320市面上的1.54寸屏一般只用上半部分240x240所以必须显式声明#define TFT_WIDTH 240 #define TFT_HEIGHT 240如果你的屏显示区域偏移了内容跑到屏幕中间或者四周有黑边就需要设置偏移量#define TFT_OFFSET_X 0 #define TFT_OFFSET_Y 0偏移量不是固定的不同模组的驱动IC批次不同可能需要设成0、40、80这些值逐个试。然后是引脚配置和SPI频率#define TFT_MISO -1 #define TFT_MOSI 23 #define TFT_SCLK 18 #define TFT_CS 5 #define TFT_DC 2 #define TFT_RST 4 #define TFT_BL 15 #define SPI_FREQUENCY 40000000MISO设成-1是因为这块屏幕只收不发不需要MISO引脚。SPI频率先给40MHz这是很多屏幕的甜点值稳定性和速度均衡等显示正常后再尝试往80MHz调。2.3 白屏、花屏、颜色错乱的排查顺序屏幕点亮后最常见的三个问题白屏、花屏、颜色错乱。我复刻时也踩过排查顺序基本是固定的。第一背光亮但全白。先查复位引脚。很多模块要求MCU把RST拉低20ms再拉高如果RST引脚没接对或没配置屏幕就停在复位状态。确保User_Setup.h里的TFT_RST和实际接线一致。如果还是白屏检查背光引脚是否被拉高有些模块的BL脚默认低电平关背光。第二花屏或斜条纹。通常是SPI频率太高或者杜邦线太长。我一开始用40MHz接20cm杜邦线画面时不时花把SPI_FREQUENCY降到10MHz后立刻稳定。降频确认问题后再逐步往上加同时把线尽量剪短或者直接焊上去。物理因素往往比代码问题更隐蔽。第三颜色错乱红蓝互换、绿色偏紫。这是ST7789的RGB/BGR扫描顺序问题。在User_Setup.h里找#define TFT_RGB_ORDER TFT_RGB如果颜色不对改成#define TFT_RGB_ORDER TFT_BGR国产模组很多默认BGR不设置就会偏色。还有一个小环境问题很常见Arduino IDE安装ESP32开发板核心包时卡在“failed to install platform: esp32:3.3.11”这类下载失败提示。这不是代码问题是网络问题。解决办法可以是换成国内可访问的附加开发板管理网址或者手动下载离线核心包放进Arduino15/packages/esp32目录。把环境先理顺后面编译才不会反复被中断。3. 太空人素材处理GIF拆帧、RGB565取模与存储方案3.1 素材来源与拆帧太空人的原始素材网上很多常见的是GIF动图或者Lottie动画。但表盘动画一般只需要8到12帧循环动作还要无缝衔接。如果你下载的GIF有几十帧建议用ffmpeg挑出动作循环里的关键帧把无关的过渡帧去掉。拆帧命令很简单ffmpeg -i astronaut.gif -vsync 0 frame_%02d.png然后挑出需要的帧统一缩放到动画实际显示大小。太空人区域在表盘上通常不大120x120或96x96就够。缩放用Pillow处理from PIL import Image for i in range(12): img Image.open(fsrc_{i:02d}.png) img img.convert(RGB).resize((120, 120), Image.LANCZOS) img.save(fout_{i:02d}.png)注意透明背景问题。GIF转出来的PNG如果带透明通道后面取模时要决定怎么处理透明区域。最简单的方案是把透明区域填充成和表盘底色一致的颜色这样上屏后看起来就像透明。3.2 RGB565取模字节序和C数组的坑屏幕是16位色也就是RGB565每个像素占2字节。要把PNG变成屏幕上能直接用的数据可以用Image2Lcd这类Windows小工具也可以用LVGL的在线Image Converter。这类工具转换时通常有一个关键选项字节序。同一个颜色比如红色0xF800在二进制里可能是0xF8 0x00也可能反过来是0x00 0xF8取决于屏的SPI时序要求。ST7789通常支持两种模式但国产模组默认情况不一定。判断方法很简单先做一张纯色图取模上屏看颜色对不对。红蓝反了就把取模工具的“字节序”选项换一下重新生成。这个坑很小但很耗时间我当时折腾了半小时才锁定是取模工具选项的问题而不是屏幕坏了。3.3 不要把所有帧写死成C数组用LittleFS存bin文件12帧120x120的RGB565图一帧是120x120x228800字节12帧总共345600字节。看起来不大但如果你把它们全部写成C数组放进代码Arduino编译时会非常吃力改一帧素材还得重新编译整个工程。更麻烦的是如果后续想升级成240x240全屏动画一帧就是115200字节几十帧就是好几MB纯C数组方案直接崩。我的方案是把所有动画帧合并成一个.bin文件用ESP32的“ESP32 Sketch Data Upload”工具上传到LittleFS分区程序启动时从文件系统按需读取帧数据再推屏。这样素材和固件分离换动画只需要重新上传bin文件不用改代码。写入bin的Python脚本如下import struct with open(anim.bin, wb) as f: for i in range(12): img Image.open(fout_{i:02d}.png) pixels img.load() for y in range(120): for x in range(120): r, g, b pixels[x, y] rgb565 ((r 3) 11) | ((g 2) 5) | (b 3) f.write(struct.pack(H, rgb565))注意H表示大端序。如果你的屏显示出来红蓝互换改成H试试。读帧时在ESP32端用一个uint16_t数组做缓冲每次从LittleFS读取一帧28800字节到缓冲再传给TFT_eSPI的推图函数。如果不想用文件系统也可以把所有帧压缩成RLE格式太空人背景区域可以跳过大段重复数据体积能缩小一半以上代价是显示时要写一个解压函数。这个属于进阶玩法初期先用bin文件最省心。4. 表盘UI分层绘制动画帧、时间数字与表盘底图的合成4.1 先画一次底图之后不要每帧重画表盘上的静态元素比如背景、外圈刻度、装饰文字这些画一次就够了。很多人第一次写表盘会进入一个误区主循环里每一帧都从头画底图、画刻度、画动画、画时间结果帧率被底图绘制拖死。正确做法是启动时把静态部分一次性画好屏幕上这部分内容保持不变。之后每一帧只更新“会变”的区域也就是太空人动画区域和时间数字区域。用TFT_eSPI的pushImage只推120x120的动画区域底图根本不需要重画。时间数字每分钟变一次时也只需要把数字那块小区域清掉重画。4.2 画圆弧进度环和刻度的代码思路如果你想要表盘外圈有个进度环模拟秒数或者步数百分比TFT_eSPI较新版本提供了drawSmoothArc函数可以直接画平滑圆弧tft.drawSmoothArc(cx, cy, r_outer, r_inner, start_angle, end_angle, color, bgColor);比如画一个0到270度的圆弧参数就是start_angle0end_angle270。角度单位是度0度对应三点钟方向。做百分比进度环时end_angle用百分比计算end_angle 360 * percent / 100。刻度线就更是纯数学题了循环12次用三角函数算出内外点坐标再画线for (int i 0; i 12; i) { float angle i * 30 * DEG_TO_RAD; int x1 cx r_outer * cos(angle); int y1 cy r_outer * sin(angle); int x2 cx (r_outer - 8) * cos(angle); int y2 cy (r_outer - 8) * sin(angle); tft.drawLine(x1, y1, x2, y2, TFT_WHITE); }如果你用的TFT_eSPI版本较旧找不到drawSmoothArc可以直接搜下库文件确认没有的话升级库版本或者退而求其次用drawArc只是边缘平滑度差一些。4.3 动画帧和时间的渲染顺序合成顺序决定遮挡关系我的顺序是第一层底图、刻度、进度环第二层太空人动画区域第三层时间数字和日期文字如果时间文字和动画区域重叠一定要把时间放到动画之后画。时间数字每秒刷新的话用fillRect把旧数字区域填成背景色再画新数字不会有明显闪烁。如果刷新频率再高就得用readRect先把背景存起来刷新时先pushRect恢复背景再画新数字。但对于表盘这种场景分钟级或秒级刷新用fillRect足够。还有一个新手容易忽略的坑动画帧如果带透明背景直接用pushImage会把整块120x120矩形刷上去包括透明区域结果盖住底图。处理方法有两种一种是把动画帧透明背景填充成和表盘底色一致视觉上伪装成透明另一种是逐像素判断透明色跳过但会拖慢帧率。新手阶段建议选第一种视觉效果差别不大效率高得多。5. NTP授时与本地时间处理时区的正确姿势5.1 用configTzTime而不是configTimeESP32连上WiFi后最靠谱的取时方式就是NTP。Arduino环境里常见两种写法configTime和configTzTime。我第一次用的是configTime(gmtOffset_sec, daylightOffset_sec, ntpServer)结果时区问题特别多因为gmtOffset_sec要手动写偏移不同地区不同季节还不一样特别容易出错。换成configTzTime之后清爽很多configTzTime(CST-8, pool.ntp.org);这一行直接指定时区为UTC8也就是中国标准时间不需要自己算偏移。注意这里的CST是China Standard Time的缩写不是美国中部时间别搞混。取时间用getLocalTimestruct tm timeinfo; if (getLocalTime(timeinfo)) { char buf[32]; strftime(buf, sizeof(buf), %H:%M:%S, timeinfo); tft.drawString(buf, x, y); }getLocalTime调用之前要确认WiFi已经连接否则会一直返回false。5.2 时区和夏令时的坑如果用configTime两个经典问题很容易踩到。一是gmtOffset_sec传了28800daylightOffset_sec又传了3600结果夏天时间多了一小时。国内不实行夏令时daylightOffset_sec应该设0。二是有人图省事直接显示UTC时间结果表盘比本地时间慢8小时。还有人尝试用settimezone函数但Arduino核心不同版本行为有差异容易踩版本坑。我的建议很直接不要手动管理偏移统一用configTzTime加POSIX时区字符串。中国时区就写“CST-8”代码可读性好也省得自己算夏令时。5.3 时间获取完整流程与断网回退实际项目里还要考虑一个问题表盘如果断网了时间从哪来ESP32本身没有纽扣电池RTC掉电后时间会丢。我在项目里做了一个折中方案上电先连WiFi连上后执行configTzTime然后用getLocalTime获取时间。如果WiFi连不上或NTP请求超时就使用上次编译时写入的一个起始时间配合millis()做临时计时等网络恢复后再校准。完整流程大致是WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(500); } configTzTime(CST-8, pool.ntp.org);如果想让显示更稳定可以加一个间隔定时比如每6小时重新同步一次NTP避免长时间运行后时钟漂移。日期星期显示也要注意getLocalTime拿到的tm_wday范围是0到60表示周日。很多人默认周一对应0结果星期错位一天。映射时得先把0处理成周日const char* week[] {日, 一, 二, 三, 四, 五, 六}; tft.drawString(String(周) week[timeinfo.tm_wday], x, y);6. 从25fps到更顺滑SPI时钟、DMA与局部刷新优化6.1 SPI频率和帧率的关系动画顺不顺核心瓶颈是推数据的速度。太空人动画区域如果是120x120 RGB565一帧数据量是120x120x228800字节也就是230400 bit。SPI跑40MHz时理论传输时间230400 / 40000000 ≈ 5.76ms但pushImage还有函数调用开销和SPI驱动的逐行处理开销实际测下来大概每秒能推20到25帧。120x120区域跑到这个帧率肉眼已经觉得顺滑了。想更快就把SPI_FREQUENCY改到80000000实测部分屏幕能上30帧但不是每块屏都能稳定跑80MHz花屏就降回40MHz。还有一个容易忽略的函数setSwapBytes(true)。pushImage推送图像数据时如果字节序设置不对图像颜色会错乱。TFT_eSPI默认很多屏是关闭的需要显式开启尤其是从文件系统读出的字节流一定要在初始化时调用一次tft.setSwapBytes(true);6.2 用DMA把推屏和绘制重叠起来ESP32的SPI硬件支持DMA传输简单说就是硬件直接把内存里的数据搬给SPI外设CPU不用傻等传输完成可以提前准备下一帧。TFT_eSPI里改动很小tft.startWrite(); tft.pushImageDMA(x, y, w, h, imageBuffer); tft.endWrite();注意pushImageDMA要求图像数据缓冲区在传输期间要保持有效不能传局部临时数组否则DMA还没搬完数据缓冲区就被释放了显示出来就是花屏或残影。我在项目里开了一个全局或静态的uint16_t数组animBuffer[120 * 120]每次从LittleFS读帧数据到这个缓冲再传给pushImageDMA。6.3 局部刷新与后续扩展即使动画区域跑顺了整体刷新也要克制。主循环大概这种节奏每秒检查秒数变化只刷新时间数字区域每80到100毫秒切换一帧太空人动画跨天时才重绘日期文字区域这样屏幕大部分区域保持静止实际吞吐量远低于全屏动画帧率自然更高。如果你第一次做先按这种局部刷新思路来不要一上来就全屏乱刷否则又慢又闪。后续想升级的话两个方向可以参考一是引入LVGL用lv_canvas把动画帧贴到控件上再用lv_anim控制循环做复杂UI会灵活很多代价是内存占用和工程复杂度上升二是先用wokwi这类在线仿真平台调通时间、UI逻辑再烧到真机验证。不过仿真对硬件时序的模拟不完全真实白屏、花屏这种问题最终还是得靠真机调。最后再说一个我个人复刻完这个项目后很深的体会真机上跑的时候别一味追求高帧率。120x120的动画跑到15到20帧观感已经很舒服稳定比参数好看重要得多。另外接线如果用的是杜邦线长度超过10cm出现花屏时先别怀疑代码把线剪短或者直接焊上去很多疑难杂症会自己消失。素材处理那边也一定要保留好原始工程文件包括GIF、PNG、取模工具的配置因为换素材重新出bin文件是高频操作没有原始素材就得从头折腾一遍那才是最痛苦的。本文还有配套的精品资源点击获取 ESP32复刻太空人表盘：ST7789驱动、动画渲染与NTP对时全解析
简介这是一份基于Arduino IDE与ESP32微控制器、驱动TFT 7789显示屏实现太空人表盘完整复刻的工程资源包适合物联网爱好者、嵌入式初学者及DIY创客参考学习。包内文件总数1498个压缩包约5.46MB以cpp、h、hpp、ino等源码文件为主同时包含vlw字体资源、JSON配置、Shell脚本、Markdown说明等覆盖Arduino库依赖、示例程序与项目构建配置便于直接梳理和复用。目前已有970人学习下载。通过源码与说明文档可掌握ESP32的SPI屏幕驱动、Adafruit GFX绘图、Wi-Fi联网获取天气数据并在表盘上动态更新等关键实现思路还可借鉴像素画太空人素材的定位方式与项目整体组织逻辑适合希望从零跑通并二次开发该表盘效果的读者。 上个月翻出一块吃灰很久的1.54寸TFT彩屏刚好手头又有ESP32开发板就想着把网上很火的那个太空人表盘复刻出来。这个项目从外面看就是一个动态的太空人行走动画叠在表盘上再加一行时间文字做成桌面小摆件。但真正动手做才发现ESP32、ST7789屏幕驱动、动画素材取模、UI分层绘制、NTP网络对时这些环节每一个单拎出来都有不少坑尤其是对刚接触Arduino开发ESP32的人来说经常卡在“屏幕白屏”和“动画帧率上不去”这两个地方。这篇文章不打算直接甩一个成品工程完事而是把这个复刻项目里真正让人头疼的细节逐段拆开讲一遍屏幕驱动怎么配才不花屏、太空人GIF怎么变成能上屏的RGB565帧、动画和时间文字怎么分层画不打架、NTP对时为什么总是快8小时、最后怎么让动画跑顺不残影。所有代码以Arduino IDE 官方ESP32核心为主新手跟着操作就能复现老手也能拿去当配置清单参考。1. 拆解太空人表盘这个复刻项目的真实工作量先别急着写代码把表盘的设计拆开看复杂度就清晰了。所谓太空人表盘本质上就是几层内容叠在一起最底层表盘底图包括背景色、外圈刻度、品牌文字或小装饰。中间层太空人行走动画通常是8到12帧循环播放。上层时间、日期、秒数等动态文字。可选层步数进度环、电量百分比、温湿度数据。理解了这层结构你就明白这个项目不是一个“大而全”的程序而是可以拆成几个独立模块先把屏幕点亮再解决素材然后写UI渲染最后接网络对时。每个模块单独调通再组合比憋一个大程序再一起调要省心得多。硬件选型上我用的是一片很常见的ESP32 DevKitC V4开发板加一块1.54寸240x240分辨率的ST7789 SPI屏幕。选ESP32的原因很直接RAM有520KBFlash有4MB以上SPI外设速度足够而且自带WiFi和蓝牙后面做NTP对时、蓝牙调设置都很方便。对比之下ESP8266虽然便宜但RAM只有160KB跑图像缓冲会比较吃力。屏幕选ST7789则是因为存量极大、资料多、价格低出问题时好搜解决方案。接线表可以直接照抄不同卖家丝印可能略有差异但基本都逃不出这几根线VCC → 3.3VGND → GNDSCL/SCK → GPIO18SDA/MOSI → GPIO23RES/RST → GPIO4DC → GPIO2CS → GPIO5BLK/BL → GPIO15背光也可以直接接3.3V常亮但留引脚方便后续PWM调亮度接好之后别急着焊死先用杜邦线测试因为后期很可能要换DC引脚或调整SPI频率焊死了改动就麻烦。项目功能上也要分清主次。基础版只需要“时间显示 太空人动画循环”这个跑通后再往上面加日期、星期、电量、进度环这些可选功能。一上来就想全功能很容易在调试阶段被多个变量同时干扰最后哪个都没做好。2. ST7789驱动从白屏到稳定显示的完整配置2.1 为什么选TFT_eSPI而不是Adafruit库Arduino生态里驱动ST7789的库主要分两派一派是Adafruit GFX Adafruit ST7735/ST7789组合另一派是TFT_eSPI。Adafruit的库文档多、API友好很适合初学者但性能差距比较大。TFT_eSPI针对ESP32做了很多底层优化内置了DMA推屏、平滑圆弧、宽线条等函数对“高频刷图”这种场景帮助巨大。太空人动画恰恰就是典型的推图密集型任务Adafruit库能跑但明显会卡TFT_eSPI配合DMA能快上一截而且它本身就把ST7789列为默认支持之一配置门槛并不高。安装方式很简单Arduino IDE的库管理器里搜TFT_eSPI直接装。需要提醒的是这个库不像普通库那样装完即用必须编辑库目录下的User_Setup.h文件告诉它你用的屏幕型号和引脚。建议用VS Code或记事本单独打开这个文件修改别在Arduino IDE自带的编辑器里改偶尔会遇到编码格式导致编译报错。2.2 User_Setup.h里真正影响成败的几行打开User_Setup.h先把ST7789驱动这一行打开#define ST7789_DRIVER接着设置屏幕宽高。ST7789本身RAM是240x320市面上的1.54寸屏一般只用上半部分240x240所以必须显式声明#define TFT_WIDTH 240 #define TFT_HEIGHT 240如果你的屏显示区域偏移了内容跑到屏幕中间或者四周有黑边就需要设置偏移量#define TFT_OFFSET_X 0 #define TFT_OFFSET_Y 0偏移量不是固定的不同模组的驱动IC批次不同可能需要设成0、40、80这些值逐个试。然后是引脚配置和SPI频率#define TFT_MISO -1 #define TFT_MOSI 23 #define TFT_SCLK 18 #define TFT_CS 5 #define TFT_DC 2 #define TFT_RST 4 #define TFT_BL 15 #define SPI_FREQUENCY 40000000MISO设成-1是因为这块屏幕只收不发不需要MISO引脚。SPI频率先给40MHz这是很多屏幕的甜点值稳定性和速度均衡等显示正常后再尝试往80MHz调。2.3 白屏、花屏、颜色错乱的排查顺序屏幕点亮后最常见的三个问题白屏、花屏、颜色错乱。我复刻时也踩过排查顺序基本是固定的。第一背光亮但全白。先查复位引脚。很多模块要求MCU把RST拉低20ms再拉高如果RST引脚没接对或没配置屏幕就停在复位状态。确保User_Setup.h里的TFT_RST和实际接线一致。如果还是白屏检查背光引脚是否被拉高有些模块的BL脚默认低电平关背光。第二花屏或斜条纹。通常是SPI频率太高或者杜邦线太长。我一开始用40MHz接20cm杜邦线画面时不时花把SPI_FREQUENCY降到10MHz后立刻稳定。降频确认问题后再逐步往上加同时把线尽量剪短或者直接焊上去。物理因素往往比代码问题更隐蔽。第三颜色错乱红蓝互换、绿色偏紫。这是ST7789的RGB/BGR扫描顺序问题。在User_Setup.h里找#define TFT_RGB_ORDER TFT_RGB如果颜色不对改成#define TFT_RGB_ORDER TFT_BGR国产模组很多默认BGR不设置就会偏色。还有一个小环境问题很常见Arduino IDE安装ESP32开发板核心包时卡在“failed to install platform: esp32:3.3.11”这类下载失败提示。这不是代码问题是网络问题。解决办法可以是换成国内可访问的附加开发板管理网址或者手动下载离线核心包放进Arduino15/packages/esp32目录。把环境先理顺后面编译才不会反复被中断。3. 太空人素材处理GIF拆帧、RGB565取模与存储方案3.1 素材来源与拆帧太空人的原始素材网上很多常见的是GIF动图或者Lottie动画。但表盘动画一般只需要8到12帧循环动作还要无缝衔接。如果你下载的GIF有几十帧建议用ffmpeg挑出动作循环里的关键帧把无关的过渡帧去掉。拆帧命令很简单ffmpeg -i astronaut.gif -vsync 0 frame_%02d.png然后挑出需要的帧统一缩放到动画实际显示大小。太空人区域在表盘上通常不大120x120或96x96就够。缩放用Pillow处理from PIL import Image for i in range(12): img Image.open(fsrc_{i:02d}.png) img img.convert(RGB).resize((120, 120), Image.LANCZOS) img.save(fout_{i:02d}.png)注意透明背景问题。GIF转出来的PNG如果带透明通道后面取模时要决定怎么处理透明区域。最简单的方案是把透明区域填充成和表盘底色一致的颜色这样上屏后看起来就像透明。3.2 RGB565取模字节序和C数组的坑屏幕是16位色也就是RGB565每个像素占2字节。要把PNG变成屏幕上能直接用的数据可以用Image2Lcd这类Windows小工具也可以用LVGL的在线Image Converter。这类工具转换时通常有一个关键选项字节序。同一个颜色比如红色0xF800在二进制里可能是0xF8 0x00也可能反过来是0x00 0xF8取决于屏的SPI时序要求。ST7789通常支持两种模式但国产模组默认情况不一定。判断方法很简单先做一张纯色图取模上屏看颜色对不对。红蓝反了就把取模工具的“字节序”选项换一下重新生成。这个坑很小但很耗时间我当时折腾了半小时才锁定是取模工具选项的问题而不是屏幕坏了。3.3 不要把所有帧写死成C数组用LittleFS存bin文件12帧120x120的RGB565图一帧是120x120x228800字节12帧总共345600字节。看起来不大但如果你把它们全部写成C数组放进代码Arduino编译时会非常吃力改一帧素材还得重新编译整个工程。更麻烦的是如果后续想升级成240x240全屏动画一帧就是115200字节几十帧就是好几MB纯C数组方案直接崩。我的方案是把所有动画帧合并成一个.bin文件用ESP32的“ESP32 Sketch Data Upload”工具上传到LittleFS分区程序启动时从文件系统按需读取帧数据再推屏。这样素材和固件分离换动画只需要重新上传bin文件不用改代码。写入bin的Python脚本如下import struct with open(anim.bin, wb) as f: for i in range(12): img Image.open(fout_{i:02d}.png) pixels img.load() for y in range(120): for x in range(120): r, g, b pixels[x, y] rgb565 ((r 3) 11) | ((g 2) 5) | (b 3) f.write(struct.pack(H, rgb565))注意H表示大端序。如果你的屏显示出来红蓝互换改成H试试。读帧时在ESP32端用一个uint16_t数组做缓冲每次从LittleFS读取一帧28800字节到缓冲再传给TFT_eSPI的推图函数。如果不想用文件系统也可以把所有帧压缩成RLE格式太空人背景区域可以跳过大段重复数据体积能缩小一半以上代价是显示时要写一个解压函数。这个属于进阶玩法初期先用bin文件最省心。4. 表盘UI分层绘制动画帧、时间数字与表盘底图的合成4.1 先画一次底图之后不要每帧重画表盘上的静态元素比如背景、外圈刻度、装饰文字这些画一次就够了。很多人第一次写表盘会进入一个误区主循环里每一帧都从头画底图、画刻度、画动画、画时间结果帧率被底图绘制拖死。正确做法是启动时把静态部分一次性画好屏幕上这部分内容保持不变。之后每一帧只更新“会变”的区域也就是太空人动画区域和时间数字区域。用TFT_eSPI的pushImage只推120x120的动画区域底图根本不需要重画。时间数字每分钟变一次时也只需要把数字那块小区域清掉重画。4.2 画圆弧进度环和刻度的代码思路如果你想要表盘外圈有个进度环模拟秒数或者步数百分比TFT_eSPI较新版本提供了drawSmoothArc函数可以直接画平滑圆弧tft.drawSmoothArc(cx, cy, r_outer, r_inner, start_angle, end_angle, color, bgColor);比如画一个0到270度的圆弧参数就是start_angle0end_angle270。角度单位是度0度对应三点钟方向。做百分比进度环时end_angle用百分比计算end_angle 360 * percent / 100。刻度线就更是纯数学题了循环12次用三角函数算出内外点坐标再画线for (int i 0; i 12; i) { float angle i * 30 * DEG_TO_RAD; int x1 cx r_outer * cos(angle); int y1 cy r_outer * sin(angle); int x2 cx (r_outer - 8) * cos(angle); int y2 cy (r_outer - 8) * sin(angle); tft.drawLine(x1, y1, x2, y2, TFT_WHITE); }如果你用的TFT_eSPI版本较旧找不到drawSmoothArc可以直接搜下库文件确认没有的话升级库版本或者退而求其次用drawArc只是边缘平滑度差一些。4.3 动画帧和时间的渲染顺序合成顺序决定遮挡关系我的顺序是第一层底图、刻度、进度环第二层太空人动画区域第三层时间数字和日期文字如果时间文字和动画区域重叠一定要把时间放到动画之后画。时间数字每秒刷新的话用fillRect把旧数字区域填成背景色再画新数字不会有明显闪烁。如果刷新频率再高就得用readRect先把背景存起来刷新时先pushRect恢复背景再画新数字。但对于表盘这种场景分钟级或秒级刷新用fillRect足够。还有一个新手容易忽略的坑动画帧如果带透明背景直接用pushImage会把整块120x120矩形刷上去包括透明区域结果盖住底图。处理方法有两种一种是把动画帧透明背景填充成和表盘底色一致视觉上伪装成透明另一种是逐像素判断透明色跳过但会拖慢帧率。新手阶段建议选第一种视觉效果差别不大效率高得多。5. NTP授时与本地时间处理时区的正确姿势5.1 用configTzTime而不是configTimeESP32连上WiFi后最靠谱的取时方式就是NTP。Arduino环境里常见两种写法configTime和configTzTime。我第一次用的是configTime(gmtOffset_sec, daylightOffset_sec, ntpServer)结果时区问题特别多因为gmtOffset_sec要手动写偏移不同地区不同季节还不一样特别容易出错。换成configTzTime之后清爽很多configTzTime(CST-8, pool.ntp.org);这一行直接指定时区为UTC8也就是中国标准时间不需要自己算偏移。注意这里的CST是China Standard Time的缩写不是美国中部时间别搞混。取时间用getLocalTimestruct tm timeinfo; if (getLocalTime(timeinfo)) { char buf[32]; strftime(buf, sizeof(buf), %H:%M:%S, timeinfo); tft.drawString(buf, x, y); }getLocalTime调用之前要确认WiFi已经连接否则会一直返回false。5.2 时区和夏令时的坑如果用configTime两个经典问题很容易踩到。一是gmtOffset_sec传了28800daylightOffset_sec又传了3600结果夏天时间多了一小时。国内不实行夏令时daylightOffset_sec应该设0。二是有人图省事直接显示UTC时间结果表盘比本地时间慢8小时。还有人尝试用settimezone函数但Arduino核心不同版本行为有差异容易踩版本坑。我的建议很直接不要手动管理偏移统一用configTzTime加POSIX时区字符串。中国时区就写“CST-8”代码可读性好也省得自己算夏令时。5.3 时间获取完整流程与断网回退实际项目里还要考虑一个问题表盘如果断网了时间从哪来ESP32本身没有纽扣电池RTC掉电后时间会丢。我在项目里做了一个折中方案上电先连WiFi连上后执行configTzTime然后用getLocalTime获取时间。如果WiFi连不上或NTP请求超时就使用上次编译时写入的一个起始时间配合millis()做临时计时等网络恢复后再校准。完整流程大致是WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(500); } configTzTime(CST-8, pool.ntp.org);如果想让显示更稳定可以加一个间隔定时比如每6小时重新同步一次NTP避免长时间运行后时钟漂移。日期星期显示也要注意getLocalTime拿到的tm_wday范围是0到60表示周日。很多人默认周一对应0结果星期错位一天。映射时得先把0处理成周日const char* week[] {日, 一, 二, 三, 四, 五, 六}; tft.drawString(String(周) week[timeinfo.tm_wday], x, y);6. 从25fps到更顺滑SPI时钟、DMA与局部刷新优化6.1 SPI频率和帧率的关系动画顺不顺核心瓶颈是推数据的速度。太空人动画区域如果是120x120 RGB565一帧数据量是120x120x228800字节也就是230400 bit。SPI跑40MHz时理论传输时间230400 / 40000000 ≈ 5.76ms但pushImage还有函数调用开销和SPI驱动的逐行处理开销实际测下来大概每秒能推20到25帧。120x120区域跑到这个帧率肉眼已经觉得顺滑了。想更快就把SPI_FREQUENCY改到80000000实测部分屏幕能上30帧但不是每块屏都能稳定跑80MHz花屏就降回40MHz。还有一个容易忽略的函数setSwapBytes(true)。pushImage推送图像数据时如果字节序设置不对图像颜色会错乱。TFT_eSPI默认很多屏是关闭的需要显式开启尤其是从文件系统读出的字节流一定要在初始化时调用一次tft.setSwapBytes(true);6.2 用DMA把推屏和绘制重叠起来ESP32的SPI硬件支持DMA传输简单说就是硬件直接把内存里的数据搬给SPI外设CPU不用傻等传输完成可以提前准备下一帧。TFT_eSPI里改动很小tft.startWrite(); tft.pushImageDMA(x, y, w, h, imageBuffer); tft.endWrite();注意pushImageDMA要求图像数据缓冲区在传输期间要保持有效不能传局部临时数组否则DMA还没搬完数据缓冲区就被释放了显示出来就是花屏或残影。我在项目里开了一个全局或静态的uint16_t数组animBuffer[120 * 120]每次从LittleFS读帧数据到这个缓冲再传给pushImageDMA。6.3 局部刷新与后续扩展即使动画区域跑顺了整体刷新也要克制。主循环大概这种节奏每秒检查秒数变化只刷新时间数字区域每80到100毫秒切换一帧太空人动画跨天时才重绘日期文字区域这样屏幕大部分区域保持静止实际吞吐量远低于全屏动画帧率自然更高。如果你第一次做先按这种局部刷新思路来不要一上来就全屏乱刷否则又慢又闪。后续想升级的话两个方向可以参考一是引入LVGL用lv_canvas把动画帧贴到控件上再用lv_anim控制循环做复杂UI会灵活很多代价是内存占用和工程复杂度上升二是先用wokwi这类在线仿真平台调通时间、UI逻辑再烧到真机验证。不过仿真对硬件时序的模拟不完全真实白屏、花屏这种问题最终还是得靠真机调。最后再说一个我个人复刻完这个项目后很深的体会真机上跑的时候别一味追求高帧率。120x120的动画跑到15到20帧观感已经很舒服稳定比参数好看重要得多。另外接线如果用的是杜邦线长度超过10cm出现花屏时先别怀疑代码把线剪短或者直接焊上去很多疑难杂症会自己消失。素材处理那边也一定要保留好原始工程文件包括GIF、PNG、取模工具的配置因为换素材重新出bin文件是高频操作没有原始素材就得从头折腾一遍那才是最痛苦的。本文还有配套的精品资源点击获取