LILYGO T-Display-S3 Pinout

The LILYGO T-Display-S3 is an ESP32-S3 board with a 1.9 inch colour display built in, a USB-C port and a battery connector, in one small board. It has 16 MB of flash and 8 MB of PSRAM, two buttons, and a header with the free pins. It is a popular base for small dashboards, remotes, badges and anything that needs a screen without extra wiring.

This guide covers every pin, the display bus, the power-on pin you must set, the battery, the buttons, programming settings, code and the traps. The pin data comes from the LILYGO GitHub repository, and the chip limits from the Espressif ESP32-S3 datasheet. The repository does not state the board size.

System-on-chip and board

Source: LILYGO T-Display-S3 GitHub repository and the Espressif ESP32-S3 datasheet.

Getting started

Specifications

Chip limits (ESP32-S3 datasheet)

Source: LILYGO T-Display-S3 repository and the Espressif ESP32-S3 datasheet.

Dimensions

The LILYGO repository does not state the size of the board in text. The mechanical drawings are in the repository as DWG and STP files, so use those before you design a case. The display is 1.9 inch (170 × 320 pixels) and the board is long and narrow, with the USB-C port on one short edge and a header on both long edges.

Source: LILYGO T-Display-S3 repository. The size is only in the DWG and STP files.

Pin reference

Display (8-bit parallel)

Other signals

GPIO39 to GPIO42 are the default JTAG pins of the S3, and GPIO45 and GPIO46 are strapping pins, so the display bus shares pins with debugging and boot configuration. Avoid hanging anything else on them.

Source: LILYGO T-Display-S3 repository.

Power and battery

• USB-C powers the board and charges the battery at 500 mA by default.
• Battery. A 3.7 V to 4.2 V lithium cell on the JST 1.25 mm connector. Mind the polarity of the connector: it is not standardised.
• GPIO15 must be HIGH. This pin powers the display and some peripherals. It is required with a battery or the 5V pin header, not only with USB.
• Battery voltage. GPIO4 reads the battery through a divider, but only when USB-C is unplugged.
• External supply. With an external supply, disable USB CDC in the code, because serial output then moves to GPIO43 and GPIO44.
• The 3V pin supports at most 100 mA.

Programming

Example code

#include <TFT_eSPI.h>          // use the LILYGO configuration for this board
TFT_eSPI tft;

void setup() {
  pinMode(15, OUTPUT);
  digitalWrite(15, HIGH);          // power on the display and peripherals
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_WHITE);
  tft.drawString("T-Display-S3", 10, 10, 4);
}

void loop() {}

Without digitalWrite(15, HIGH) the display stays black. I did not run this sketch on a board. The display needs the LILYGO pin configuration for TFT_eSPI, not the default one.

Tips

• Set GPIO15 HIGH before anything else.
• Use the LILYGO TFT_eSPI setup files, or the repository examples.
• Pin the Arduino core to 2.0.14 if TFT_eSPI fails on a newer one.
• Use the PSRAM for a frame buffer (a sprite) to avoid flicker.
• Dim the backlight with PWM on GPIO38 to save battery.
• For battery operation read GPIO4 when USB is unplugged.

Real gotchas

• The display stays black without GPIO15. This is the most common problem. Set GPIO15 HIGH in setup.
• TFT_eSPI is picky. LILYGO reports it did not work on core versions above 2.0.14 (August 2024). Use their tested version or check for an update.
• The battery ADC only works on battery. With USB-C plugged in GPIO4 does not give the battery voltage.
• Serial moves with an external supply. Disable USB CDC to get serial on GPIO43 and GPIO44.
• Many pins are taken. Eight data lines, six control lines, the backlight and I2C use most pins. Count the free pins on the header before you plan a project.
• The touch pins belong to the Touch version. Do not wire something else to GPIO16 and GPIO21 on that board.
• The battery connector polarity. Check the polarity of the battery plug before you connect it.
• The 3V pin is for 100 mA. Do not power a motor or LED strip from it.
• Antenna. The on-board antenna is the default. An external antenna means moving a resistor.

Compared with other boards with a screen

The second row is a bare display module that you wire to a board of your own.

What to build with it

• A small weather or sensor dashboard.
• A remote control with a screen and two buttons.
• A battery-powered badge or name tag.
• A Wi-Fi scanner or a BLE tool with a display.
• A HomeKit device with a status display.

Safety notes

Conclusion

The built-in display makes this a genuinely different board from a bare breakout, most of its GPIOs are already spoken for by the screen, plan your project’s wiring around what’s actually left rather than assuming the ESP32-S3’s full pin count is available. For a board with the same chip and no display, more free GPIOs, see the AI-S3.

Board data is from the LILYGO T-Display-S3 repository and chip limits from the Espressif ESP32-S3 datasheet.