当前位置：首页 > news >正文

保姆级教程：用ESP32和GC9A01圆形屏播放视频，从接线到代码修改全流程（附避坑点）

news 2026/5/30 20:34:04

ESP32与GC9A01圆形屏视频播放实战指南：从硬件搭建到代码调试全解析

第一次拿到ESP32开发板和那块精致的1.28寸GC9A01圆形屏时，我完全被它240×240分辨率的显示效果震撼了。但当我兴冲冲地想要播放一段视频时，却发现GitHub上的开源代码根本无法直接运行——引脚定义不匹配、SPI库需要修改、视频格式需要转换，一连串的问题让我这个Arduino新手差点放弃。经过三天反复试验和无数次的失败后，我终于整理出了这份零失败操作手册，它将带你避开所有我踩过的坑，从接线到代码修改，一步步实现圆形屏上的流畅视频播放。

1. 硬件准备与接线详解

1.1 组件清单与规格确认

在开始之前，请确保你已准备好以下硬件：

ESP32开发板（推荐使用ESP32 DevKitC V4，它自带USB转串口芯片）
GC9A01圆形显示屏（1.28寸，240×240分辨率）
TF卡模块（或带TF卡槽的ESP32开发板）
杜邦线（建议使用20cm长度，方便整理）

特别注意：GC9A01屏幕有多个版本，确认你的屏幕驱动芯片确实是GC9A01而非ST7789或ILI9341。一个简单的辨别方法是查看屏幕背面——GC9A01通常会明确标注芯片型号。

1.2 精准接线指南

接线是第一个容易出错的关键环节。以下是经过验证的稳定连接方案：

GC9A01引脚	ESP32引脚	功能说明
GND	GND	地线
VCC	3.3V	电源
SCL	GPIO14	时钟线
SDA	GPIO15	数据线
RES	GPIO33	复位
DC	GPIO27	数据/命令选择
CS	GPIO5	片选
BLK	GPIO22	背光控制

提示：接线时务必先断开电源，使用万用表检查是否有短路。我曾因一根劣质杜邦线内部断裂导致屏幕无法正常工作，排查了整整两小时。

TF卡模块的连接同样关键：

TF模块的CS引脚连接到ESP32的GPIO13
MISO→GPIO2,MOSI→GPIO15,SCK→GPIO14（与屏幕共用）
电源同样接3.3V和GND

2. 开发环境配置与库安装

2.1 Arduino IDE基础设置

安装最新版Arduino IDE（1.8.19+）

在首选项中添加ESP32开发板管理地址：

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

通过开发板管理器安装"esp32 by Espressif Systems"

2.2 必须的库文件

这些库需要逐个安装：

Arduino_GFX（核心图形库）
ESP32SPI（SPI通信优化版）
SD（TF卡读取）
MjpegVideo（视频解码）

安装时常见的两个坑：

库版本冲突：如果遇到编译错误，尝试删除旧版本库
依赖缺失：某些库需要先安装其依赖库，仔细阅读错误提示

3. SPI库修改与引脚重定义

3.1 定位SPI.cpp文件

这是整个过程中最关键的步骤之一。文件路径通常为：

C:\Users\[用户名]\AppData\Local\Arduino15\packages\esp32\hardware\esp32\[版本号]\libraries\SPI\src\SPI.cpp

注意：AppData是隐藏文件夹，需要在文件管理器选项中开启"显示隐藏文件"。

3.2 修改引脚定义

找到SPIClass::begin函数，将其中的默认引脚定义修改为：

#define MISO 2 #define SCK 14 #define MOSI 15 #define SS 13

重要：修改后必须重启Arduino IDE才能使更改生效。我曾因忘记重启而浪费一小时排查"为何修改无效"。

4. 视频文件准备与转换

4.1 视频规格要求

分辨率：240×240（必须严格匹配）
格式：转换为.mjpeg格式
帧率：建议15fps以下以保证流畅度
时长：根据TF卡容量，但建议不超过30秒

4.2 使用FFmpeg转换

这是最可靠的转换方法，命令行示例：

ffmpeg -i input.mp4 -vf "scale=240:240,crop=240:240" -r 10 -q:v 2 output.mjpeg

参数说明：

-r 10：设置帧率为10fps
-q:v 2：质量参数（1-31，越小质量越高）

转换完成后：

将.mjpeg文件复制到TF卡根目录
在代码中相应修改文件名宏定义：
```
#define MJPEG_FILENAME "/output.mjpeg"
```

5. 完整代码解析与调试

5.1 主程序结构剖析

核心代码框架包含三个部分：

硬件初始化：SPI总线、屏幕、SD卡
视频解码循环：逐帧读取并显示
内存管理：防止内存泄漏

关键对象初始化代码：

Arduino_DataBus *bus = new Arduino_ESP32SPI(27 /* DC */, 5 /* CS */, 14 /* SCK */, 15 /* MOSI */, 2 /* MISO */, VSPI); Arduino_GC9A01 *gfx = new Arduino_GC9A01(bus, 33 /* RST */, 1 /* rotation */, true /* IPS */);