LilyGo logo

🌟T-Display-S3

English | 中文

[![PlatformIO CI](https://github.com/Xinyuan-LilyGO/T-Display-S3/actions/workflows/platformio.yml/badge.svg)](https://github.com/Xinyuan-LilyGO/T-Display-S3/actions/workflows/platformio.yml) [![Arduino_CI](https://github.com/Xinyuan-LilyGO/T-Display-S3/actions/workflows/arduino_ci.yml/badge.svg)](https://github.com/Xinyuan-LilyGO/T-Display-S3/actions/workflows/arduino_ci.yml) ## 1. 支持的产品 | 产品 (PinMap) | SOC | Flash | PSRAM | 分辨率 | 尺寸 | | ----------------------- | ---------- | ----- | -------- | ------- | -------- | | [T-Display-S3][1] | ESP32-S3R8 | 16MB | 8MB(OPI) | 170x320 | 1.9 英寸 | | [T-Display-S3-Touch][2] | ESP32-S3R8 | 16MB | 8MB(OPI) | 170x320 | 1.9 英寸 | | [T-Display-S3-MIDI][3] | | | | | | [1]: https://www.lilygo.cc/products/t-display-s3?variant=42589373268149 [2]: https://www.lilygo.cc/products/t-display-s3?variant=42351558590645 [3]: https://www.lilygo.cc/products/t-display-s3?variant=43164741632181 ## 2. 示例程序 ```bash ./examples/ ├── Arduino_GFXDemo # Arduino_GFX 示例 ├── Arduino_GFX_PDQgraphicstest # Arduino_GFX 示例 ├── GetBatteryVoltage # 获取电池电压示例 ├── I2CScan # I2C 外部设备扫描 ├── ImageScroll # 图片滚动示例 (by @Rudi Ackermann) ├── MPR121TouchSensor # MPR121 电容触摸示例 ├── PCBClock # TFT_eSPI PCBClock 示例 (by @VolosR) ├── PokerS3 # TFT_eSPI PokerS3 示例 (by @VolosR) ├── SerialExample # 串口通信示例 ├── T-Display-S3-MIDI # T-Display-S3-MIDI Shield 示例 ├── T-Display-S3-BLE-Receiver # BLE MIDI 无线接收器 + 钢琴显示 (ESP32_Host_MIDI) ├── T-Display-S3-BLE-Sender # BLE MIDI 发送器 + 自动播放序列 (ESP32_Host_MIDI) ├── T-Display-S3-Piano # USB MIDI 钢琴可视化 + 和弦检测 (ESP32_Host_MIDI + Gingoduino) ├── T-Display-S3-Piano-Debug # MIDI 事件监控 + 原始数据包检测 (ESP32_Host_MIDI) ├── T-Display-S3-Gingoduino # 实时和弦检测与和声分析 (ESP32_Host_MIDI + Gingoduino) ├── T-Display-S3-Queue # MIDI 事件队列可视化调试 (ESP32_Host_MIDI) ├── T-Display-S3-USB-Device # BLE 转 USB MIDI 桥接 (ESP32_Host_MIDI) ├── T-Display-S3-Music-Explorer # 交互式音乐理论探索 + 音频合成 (Gingoduino) ├── TFT_Rainbow # TFT_eSPI 示例 ├── factory # 出厂示例 ├── lv_demos # LVGL 演示 ├── nes # NES 游戏模拟器 ├── ota # OTA 无线升级示例 ├── sd # T-Display-TF Shield 示例 ├── tft # TFT_eSPI 示例 ├── touch_test # 电容触摸测试示例 ├── usb_hid_pad # 电容触摸屏模拟 USB HID 示例 ├── ULP_ADC # ULP-FSM ADC 检测 (arduino_esp32 版本: 3.0.0-rc3) └── ULP_Count # ULP-FSM 寄存器计数 (arduino_esp32 版本: 3.0.0-rc3) ``` ## 3. PlatformIO 快速开始(推荐) 1. 安装 [Visual Studio Code](https://code.visualstudio.com/) 和 [Python](https://www.python.org/)。 2. 在 VS Code 扩展市场中搜索 `PlatformIO` 插件并安装。 3. 安装完成后,重启 VS Code。 4. 在 VS Code 中,选择 `File` > `Open Folder` > 选择 `T-Display-S3` 目录。 5. 等待第三方依赖库安装完成。 6. 打开 `platformio.ini` 文件。 7. 取消注释其中一行 `default_envs = xxxx`,确保只有一行生效。 8. 点击左下角的(对勾)图标进行编译。 9. 通过 USB 将开发板连接到电脑。 10. 点击(箭头)上传固件。 11. 点击(插头图标)监控串口输出。 12. 如果无法上传或 USB 设备持续闪烁,请查看下方 **FAQ**。 > [!TIP] > 如果遇到异常的编译错误,建议先重新克隆(或重新下载)本仓库。编译前请先点击 PlatformIO 工具栏中的 **Clean** 按钮清除旧的构建产物,然后再尝试编译。 ## 4. Arduino IDE 手动安装 1. 安装 [Arduino IDE](https://www.arduino.cc/en/software)。 2. 在 Arduino 偏好设置中,打开设置选项卡,在 `Additional boards manager URLs` 输入框中输入以下 URL: ``` https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json ``` > **注意:** 测试阶段使用的是 2.0.14 版本。高于 2.0.14 的版本可能无法正常运行,如遇到问题请降级。截至 2024/08/02,TFT_eSPI 在高于 2.0.14 的版本上无法工作(参见 [TFT_eSPI#3329](https://github.com/Bodmer/TFT_eSPI/issues/3329))。 3. 下载 `T-Display-S3`,将其移动到 Arduino 库文件夹(例如 `C:\Users\YourName\Documents\Arduino\libraries`)。 4. 将 [lib 文件夹](./lib/) 中的所有文件夹复制到 Arduino 库文件夹。 5. 进入下载的 `T-Display-S3/examples` 目录。 6. 选择任意示例,双击 `.ino` 文件打开。 7. 在 Arduino IDE 中,打开 `Tools` 菜单,按以下表格配置: | Arduino IDE 设置项 | 值 | | ------------------------------------ | ---------------------------------- | | Board | **ESP32S3 Dev Module** | | Port | 选择你的串口 | | USB CDC On Boot | Enable | | CPU Frequency | 240MHz (WiFi) | | Core Debug Level | None | | USB DFU On Boot | Disable | | Erase All Flash Before Sketch Upload | Disable | | Events Run On | Core1 | | Flash Mode | QIO 80MHz | | Flash Size | **16MB (128Mb)** | | Arduino Runs On | Core1 | | USB Firmware MSC On Boot | Disable | | Partition Scheme | **16M Flash (3M APP/9.9MB FATFS)** | | PSRAM | **OPI PSRAM** | | Upload Mode | **UART0/Hardware CDC** | | Upload Speed | 921600 | | USB Mode | **CDC and JTAG** | > **加粗** 的选项为必选项,其余根据实际情况选择。 8. 点击 `Upload`,等待编译和写入完成。 9. 如果无法上传或 USB 设备持续闪烁,请查看下方 **FAQ**。 - 也可以选择 `LilyGo T-Display-S3` 作为开发板,但分区表固定为 **16M Flash (3M APP/9.9MB FATFS)**。 - [T-Display-S3 Arduino IDE 视频教程](https://www.youtube.com/watch?v=PgtxisFvMcc) ## 5. ESP-IDF T-Display-S3 的 ESP-IDF 版本示例,请前往 [LilyGo-Display-IDF](https://github.com/Xinyuan-LilyGO/LilyGo-Display-IDF)。 ## 6. MicroPython - [russhughes/st7789s3_mpy](https://github.com/russhughes/st7789s3_mpy) - [lilygo-micropython](https://github.com/Xinyuan-LilyGO/lilygo-micropython) ## 引脚定义 | 名称 | GPIO | 说明 | | ------------ | ---- | ------------ | | LCD BL | 38 | 背光控制 | | LCD D0 | 39 | | | LCD D1 | 40 | | | LCD D2 | 41 | | | LCD D3 | 42 | | | LCD D4 | 45 | | | LCD D5 | 46 | | | LCD D6 | 47 | | | LCD D7 | 48 | | | LCD RST | 5 | 复位 | | LCD CS | 6 | 片选 | | LCD DC | 7 | 数据/命令 | | LCD WR | 8 | 写使能 | | LCD RD | 9 | 读使能 | | Power On | 15 | 外设电源控制 | | Button 1 | 0 | BOOT 按钮 | | Button 2 | 14 | | | Battery Volt | 4 | 电池电压 ADC | | IIC SCL | 17 | | | IIC SDA | 18 | | | Touch INT | 16 | 触摸中断 | | Touch RES | 21 | 触摸复位 | | SD CMD | 13 | SD 卡 | | SD CLK | 11 | SD 卡 | | SD D0 | 12 | SD 卡 | > [!IMPORTANT] > > **注意:** GPIO15 是外设电源控制引脚,使用前必须将其设置为高电平,否则 LCD 和其他外设将无法工作。使用电池或 5V 排针供电时,请在 `setup()` 中添加: > ```c > pinMode(15, OUTPUT); > digitalWrite(15, HIGH); > ``` > SD 卡引脚(SD CMD/CLK/D0)仅适用于带 SD Shield 扩展板的型号,标准版 T-Display-S3 板载没有 SD 卡槽。 > > 电池ADC引脚只能没有插入USB-C的时候读取电池电压,插入USB-C之后无法读取电池的电压 ## 7. ESP32 基础示例 - [BLE 示例](https://github.com/espressif/arduino-esp32/tree/master/libraries/BLE) - [WiFi 示例](https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi) - [SPIFFS 示例](https://github.com/espressif/arduino-esp32/tree/master/libraries/SPIFFS) - [FFat 示例](https://github.com/espressif/arduino-esp32/tree/master/libraries/FFat) - 更多 ESP32 芯片功能示例,请参阅 [arduino-esp32-libraries](https://github.com/espressif/arduino-esp32/tree/master/libraries) ## 8. 资料 | 产品 (PinMap) | 原理图 | 尺寸图 | PCB 3D | 引脚图 | | ----------------------- | ---------------------------------------------------- | --------------------------- | ----------------------------------------- | ---------------------------------------- | | [T-Display-S3][1] | [原理图](./schematic/T_Display_S3.pdf) | [DWG](./dimensions/PCB.dwg) | [STP](./dimensions/t-display-s3-full.stp) | [引脚图](./image/T-DISPLAY-S3.jpg) | | [T-Display-S3-Touch][2] | [原理图](./schematic/T_Display_S3.pdf) | [DWG](./dimensions/PCB.dwg) | [STP](./dimensions/t-display-s3-full.stp) | [引脚图](./image/T-DISPLAY-S3-TOUCH.png) | | [T-Display-S3-MIDI][3] | [原理图](./schematic/SCH_T-Display-S3-MIDI_V1.1.pdf) | N.A | N.A | N.A | ## 9. 常见问题 1. **使用电池供电时屏幕不亮。** - 使用电池或 5V 排针为 T-Display-S3 供电时,GPIO15 必须设置为高电平才能打开背光。 - 请在 `setup()` 开头添加以下代码: ```cpp void setup() { // 打开显示屏电源 pinMode(15, OUTPUT); digitalWrite(15, HIGH); } ``` 2. **程序可以正常烧录,但屏幕没有显示。** - 如果使用的是 **TFT_eSPI**,可以先尝试运行 `Arduino_GFXDemo`。如果烧录后仍然没有显示,说明可能是硬件问题。 - 如果 `Arduino_GFXDemo` 正常显示但 **TFT_eSPI** 不显示,说明 `User_Setup_Select` 配置可能被覆盖了。请参阅 FAQ 第 3 条重新配置 **TFT_eSPI**。 3. **如何更新 TFT_eSPI 或确认引脚配置是否正确?** - 在 Arduino IDE 库管理器中搜索 **TFT_eSPI** 并点击更新。 - 进入 TFT_eSPI 安装目录(例如 `C:\Users\YourName\Documents\Arduino\libraries\TFT_eSPI`)。 - 打开 `User_Setup_Select.h`,注释掉(或删除)默认的 `#include ` 行。 - 找到 `Setup206_LilyGo_T_Display_S3.h`,取消注释,保存并关闭: ```cpp #include // LilyGo T-Display S3 (ESP32S3 + ST7789 170x320 TFT) ``` 4. **无法上传程序 — 请手动进入上传模式。** - 通过 USB 线连接开发板 - 按住 **BOOT** 按钮 - 在按住 **BOOT** 的同时,按下 **RST** 按钮 - 松开 **RST**。 - 松开 **BOOT** - 上传程序。 - 按下 **RST** 退出下载模式 5. **如果使用外部电源而非 USB-C,请关闭 CDC 选项。** 因为开启 CDC 时,开发板在启动时会等待 USB 连接。 - Arduino IDE:`Tools` > `USB CDC On Boot` > `Disable` > 关闭 USB CDC 后,串口将不再通过 USB-C 输出,而是通过 GPIO43 和 GPIO44 输出。 - PlatformIO:在 `platformio.ini` 中添加以下配置: ```ini build_flags = ; -DARDUINO_USB_CDC_ON_BOOT=1 ; 开启:启动时打印并等待终端 -UARDUINO_USB_CDC_ON_BOOT ; 关闭:启动时不阻塞 ``` 6. **如果以上方法都无效,请刷写出厂固件快速验证。** 参见 [这里](https://github.com/Xinyuan-LilyGO/T-Display-S3/tree/main/firmware)。 7. **能否使用外部 5V 引脚供电?** 参见 [issues/205](https://github.com/Xinyuan-LilyGO/T-Display-S3/issues/205)。 8. **如何调整充电电流?** 默认充电电流为 500mA。参见 [issues/230](https://github.com/Xinyuan-LilyGO/T-Display-S3/issues/230)。 ## LED 说明 | 功能 | 颜色 | | ---------- | ---- | | 充电指示灯 | 红色 | | V3V 指示灯 | 绿色 | ### 充电指示灯状态 1. 未连接电池时闪烁或微亮。 2. 充电时常亮。 3. 充满电后熄灭。 ### V3V 指示灯 1. USB 供电模式下,绿色指示灯常亮。 2. 电池供电模式下,GPIO15 为高时点亮,为低时熄灭。 ### WiFi 天线 * 默认为板载天线,如果需要使用外置天线,需要把下图红色位置的电阻旋转到黄色高亮显示的位置,才能切换到外置天线模式。 antenna ### 电气参数 | 特点 | 详情 | | ----------------- | ------------- | | 🔗USB-C 输入电压 | 5V | | 🔋电池电压 | 3.7V~4.2V | | 🔋电池连接器型号 | JST 1.25 毫米 | | 📍**VBUS**(排针) | 5V | | 📍**VBAT**(排针) | 4.2V | * 3V排针负载不超过100mA * 5V 排针电源来源于USB-C ,负载能力取决于 USB-C 适配器