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有520KB，Flash有4MB以上，SPI外设速度足够，而且自带WiFi和蓝牙，后面做NTP对时、蓝牙调设置都很方便。对比之下ESP8266虽然便宜，但RAM只有160KB，跑图像缓冲会比较吃力。屏幕选ST7789则是因为存量极大、资料多、价格低，出问题时好搜解决方案。

接线表可以直接照抄，不同卖家丝印可能略有差异，但基本都逃不出这几根线：

VCC → 3.3V
GND → GND
SCL/SCK → GPIO18
SDA/MOSI → GPIO23
RES/RST → GPIO4
DC → GPIO2
CS → GPIO5
BLK/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 40000000

MISO设成-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(f"src_{i:02d}.png") img = img.convert("RGB").resize((120, 120), Image.LANCZOS) img.save(f"out_{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图，一帧是120x120x2=28800字节，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(f"out_{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_angle=0，end_angle=270。角度单位是度，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而不是configTime

ESP32连上WiFi后，最靠谱的取时方式就是NTP。Arduino环境里常见两种写法：configTime和configTzTime。我第一次用的是configTime(gmtOffset_sec, daylightOffset_sec, ntpServer)，结果时区问题特别多，因为gmtOffset_sec要手动写偏移，不同地区不同季节还不一样，特别容易出错。

换成configTzTime之后清爽很多：

configTzTime("CST-8", "pool.ntp.org");

这一行直接指定时区为UTC+8，也就是中国标准时间，不需要自己算偏移。注意这里的CST是China Standard Time的缩写，不是美国中部时间，别搞混。

取时间用getLocalTime：

struct 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传了28800，daylightOffset_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到6，0表示周日。很多人默认周一对应0，结果星期错位一天。映射时得先把0处理成周日：

const char* week[] = {"日", "一", "二", "三", "四", "五", "六"}; tft.drawString(String("周") + week[timeinfo.tm_wday], x, y);

6. 从25fps到更顺滑：SPI时钟、DMA与局部刷新优化

6.1 SPI频率和帧率的关系

动画顺不顺，核心瓶颈是推数据的速度。太空人动画区域如果是120x120 RGB565，一帧数据量是120x120x2=28800字节，也就是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文件是高频操作，没有原始素材就得从头折腾一遍，那才是最痛苦的。

本文还有配套的精品资源，点击获取