# ESP32-S3 与 2.8 英寸 SPI 触摸屏接线记录

更新：2026-09-14。

## 设备与当前状态

- 主控：ESP32-S3 N16R8 开发板，已焊排针。
- 屏幕：2.8英寸、240×320、SPI TFT，带触摸和SD卡座。
- 显示驱动：当前程序按ILI9341配置，用户提供的型号尚未通过芯片读取确认。
- 触摸驱动：当前按XPT2046兼容控制器配置；具体芯片型号尚未独立确认。
- 用户已反馈屏幕接好并点亮、触摸线已接好；动态眼睛程序将X/Y同时翻转后，用户确认点击与视线方向正确。
- SD卡功能暂不连接、不初始化。

## 接线表

GPIO编号指开发板丝印数字，不是排针从一端数起的序号。插拔杜邦线前先断开USB供电。

### 显示部分

| 屏幕标注 | ESP32-S3 | 说明 |
|---|---|---|
| VCC | 3V3（此前试接方案） | 用户反馈已亮，但未单独确认最终电源接法；按实物补核，不据此改接5V |
| GND | GND | 公共地 |
| CS | GPIO10 | 显示片选，低有效 |
| RESET | GPIO8 | 显示复位，由程序控制 |
| DC | GPIO9 | 显示数据/命令选择 |
| SDI〈MOSI〉 | GPIO11 | 主控向屏幕发送数据 |
| SCK | GPIO12 | SPI时钟 |
| LED | ESP32-S3 的 3V3（用户已确认） | 直接接3.3V，背光常亮；不接GPIO，当前程序不控制背光亮度或开关 |
| SDO〈MISO〉 | 不接 | 暂不读取显示芯片寄存器或像素，不影响写入图像 |

### 触摸部分

| 屏幕标注 | ESP32-S3 | 说明 |
|---|---|---|
| T_CLK | GPIO12 | 与显示SCK共用 |
| T_DIN | GPIO11 | 与显示SDI/MOSI共用 |
| T_DO | GPIO13 | 触摸数据返回，即MISO |
| T_CS | GPIO7 | 触摸独立片选，不能与显示CS合并 |
| T_IRQ | GPIO6 | 触摸通知；现有程序以轮询读取，暂不依赖中断 |

### 共用连线示意

```text
ESP32-S3 GPIO12 ─┬─ 屏幕 SCK
                └─ 触摸 T_CLK

ESP32-S3 GPIO11 ─┬─ 屏幕 SDI / MOSI
                └─ 触摸 T_DIN

ESP32-S3 GPIO13 ─── 触摸 T_DO
ESP32-S3 GPIO10 ─── 屏幕 CS
ESP32-S3 GPIO7  ─── 触摸 T_CS
ESP32-S3 GPIO9  ─── 屏幕 DC
ESP32-S3 GPIO8  ─── 屏幕 RESET
ESP32-S3 GPIO6  ─── 触摸 T_IRQ
ESP32-S3 GND    ─── 屏幕 GND
```

GPIO11、GPIO12各需要分接两根线，可通过面包板或分线连接。触摸T_DO与显示SDO是不同引脚，目前只连接T_DO。SD卡接口所有信号保持不接，测试时不插SD卡。

## 软件配置

Arduino IDE开发板：`ESP32S3 Dev Module`（安装Espressif Systems提供的esp32开发板包）。

库管理器安装：

- Adafruit ILI9341
- Adafruit GFX Library，以及安装提示中的依赖
- XPT2046_Touchscreen，作者Paul Stoffregen

与接线对应的关键配置：

```cpp
Adafruit_ILI9341 tft(&SPI, 9, 10, 8); // DC, CS, RESET
XPT2046_Touchscreen touch(7);         // T_CS；采用轮询

// 初始化总线前，两个片选均设为输出高电平。
pinMode(10, OUTPUT);
digitalWrite(10, HIGH);
pinMode(7, OUTPUT);
digitalWrite(7, HIGH);
pinMode(6, INPUT_PULLUP);

SPI.begin(12, 13, 11, 10); // SCK, MISO, MOSI, SS
tft.begin(10000000);       // 显示SPI初始10MHz
tft.setRotation(1);       // 横屏320×240
touch.begin(SPI);
touch.setRotation(1);
```

## 测试程序

### 笑脸与触摸基础测试

文件：`esp32_smile_test/esp32_smile_test.ino`。

- 启动切换红、绿、蓝，再显示笑脸。
- 按下屏幕时笑脸在黄色/青色之间切换，显示触摸次数。
- 串口115200输出原始坐标、压力及IRQ电平；原始坐标不是屏幕像素坐标。

### 动态眼睛测试

文件：`esp32_touch_eyes/esp32_touch_eyes.ino`。

- 已取消开机三点校准，直接显示眼睛，使用代码顶部的默认触摸范围。
- 点击时眨眼，视线朝向触摸位置；按住移动可跟随。
- 最后一次有效触摸后3秒，视线平滑回到正前方。
- 连续15秒没有触摸后，随机眨眼、向周围看，并间歇回正；触摸立即接管。当前“无人互动”仅按触摸计时，不代表摄像头检测到无人。
- 根据用户实测上下左右均反向，已设TOUCH_FLIP_X=true、TOUCH_FLIP_Y=true，TOUCH_SWAP_XY仍为false；重新上传后用户确认方向正确。边缘误差调整TOUCH_MIN/MAX_X/Y。IDLE_AFTER_MS控制闲置等待时间。

两个程序分别打开、分别上传，不将两个ino复制到同一草图目录。动态眼睛程序已获用户实机反馈：触摸与视线方向正确；长期运行及完整功能验收尚未记录。

## 排查提示

- 背光亮不代表显示初始化成功；白屏时检查ILI9341型号、CS/DC/RESET和SPI连线。
- `XPT2046_Touchscreen.h: No such file or directory`表示缺库，先安装触摸库。
- 显示正常但触摸无响应：检查T_DO→GPIO13、T_CS→GPIO7，以及共用的T_CLK/T_DIN。
- 触摸方向不对：调整动态眼睛程序顶部的轴交换/翻转和范围参数，更改屏幕旋转方向后需重新检查映射。
- 当前不要将触摸信号接5V，也不要用显示GPIO给电机供电。

## 参考与适用边界

同类[MSP2807模块接口说明](https://www.lcdwiki.com/2.8inch_SPI_Module_ILI9341_SKU:MSP2807)与实物照片的引脚名称相符，但不能由外观证明具体板卡版本完全一致。用户已确认LED直接接ESP32-S3的3V3，背光常亮；VCC的最终接法和触摸芯片型号仍需单独核对，不能由LED接法推定。

本记录仅适用于当前2.8英寸模块，不能直接套用到此前的GC9A01小圆屏。