Saltar a contenido

Ejemplo 2: Pantalla TFT ST7789

En este ejemplo encendemos la pantalla a color de la placa y dibujamos en ella texto, rectángulos, un círculo y un contador que se actualiza cada segundo. Es la prueba básica para comprobar que la pantalla está bien conectada antes de usarla en proyectos más grandes.

Qué vas a aprender:

  • Iniciar el bus SPI con pines personalizados en el ESP32-S3.
  • Configurar la pantalla ST7789 de 240×240 píxeles.
  • Escribir texto y dibujar figuras con la librería Adafruit GFX.
  • Actualizar una zona de la pantalla sin borrarla entera.

1. Mapa de pines

La pantalla se comunica por SPI. Solo necesita hablarle a la pantalla, nunca escucharla, así que no usa la línea MISO.

Pin de la pantalla GPIO del ESP32-S3 Constante Función
SDA 11 TFT_MOSI Datos del ESP32 hacia la pantalla
SCL / SCK 12 TFT_SCLK Reloj del bus SPI
CS 10 TFT_CS Selecciona la pantalla en el bus
DC 15 TFT_DC Indica si se envía un comando (LOW) o datos (HIGH)
RES / RST 9 TFT_RST Reinicia la pantalla al arrancar
BLK 3,3 V — Retroiluminación siempre encendida
VCC 3,3 V — Alimentación
GND GND — Tierra común

SDA y SCL no son I2C

Muchos módulos ST7789 rotulan los pines como SDA y SCL, como si fueran I2C. En realidad son las líneas MOSI y SCK del bus SPI.

2. Preparar el entorno

Librerías

Instálalas desde Herramientas → Administrar bibliotecas en el Arduino IDE:

Librería Para qué sirve
Adafruit ST7735 and ST7789 Controlador de la pantalla (Adafruit_ST7789.h)
Adafruit GFX Library Funciones de dibujo: texto, líneas, rectángulos, etc.

La librería SPI.h viene incluida con el soporte del ESP32.

Configuración de la placa

En el menú Herramientas:

Opción Valor
Placa ESP32S3 Dev Module
Flash Size 16MB (128Mb)
PSRAM OPI PSRAM
USB CDC On Boot Enabled

Monitor serie

Con USB CDC On Boot activado, los mensajes de Serial salen por el puerto USB nativo. Si conectas el cable al puerto UART de la placa, puedes dejarlo en Disabled.

3. Código

#include <SPI.h>
#include <Adafruit_GFX.h>
#include <Adafruit_ST7789.h>

// Pines de la pantalla en la placa ESP32 AI-V1
#define TFT_MOSI 11
#define TFT_SCLK 12
#define TFT_CS   10
#define TFT_DC   15
#define TFT_RST   9

// Tamaño de la pantalla
#define TFT_WIDTH  240
#define TFT_HEIGHT 240

Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_RST);

unsigned long ultimoCambio = 0;
int contador = 0;

void setup() {
  Serial.begin(115200);
  delay(1000);
  Serial.println("Iniciando pantalla ST7789...");

  // Bus SPI con los pines de la placa (sin MISO: -1)
  SPI.begin(TFT_SCLK, -1, TFT_MOSI, TFT_CS);

  // Inicia la pantalla de 240x240
  tft.init(TFT_WIDTH, TFT_HEIGHT);
  tft.setRotation(0);
  tft.fillScreen(ST77XX_BLACK);

  // Texto
  tft.setTextColor(ST77XX_WHITE);
  tft.setTextSize(2);
  tft.setCursor(20, 20);
  tft.println("ESP32-S3");
  tft.setCursor(20, 50);
  tft.println("LCD 240x240");

  // Marco y rectángulos de colores
  tft.drawRect(10, 90, 220, 60, ST77XX_RED);
  tft.fillRect(20, 100, 60, 40, ST77XX_BLUE);
  tft.fillRect(90, 100, 60, 40, ST77XX_GREEN);
  tft.fillRect(160, 100, 60, 40, ST77XX_RED);

  // Círculo
  tft.drawCircle(60, 195, 30, ST77XX_YELLOW);

  Serial.println("Pantalla OK");
}

void loop() {
  // Cada segundo actualiza el contador
  if (millis() - ultimoCambio >= 1000) {
    ultimoCambio = millis();
    contador++;

    // Texto con color de fondo: sobrescribe el número anterior
    tft.setTextColor(ST77XX_CYAN, ST77XX_BLACK);
    tft.setTextSize(3);
    tft.setCursor(110, 185);
    tft.printf("%4d", contador);
  }
}

4. Cómo funciona

Iniciar el bus SPI

SPI.begin(TFT_SCLK, -1, TFT_MOSI, TFT_CS);

El ESP32-S3 puede llevar el bus SPI a casi cualquier GPIO, así que hay que indicarle cuáles usa la placa. El orden de los parámetros es SCK, MISO, MOSI, SS. MISO va en -1 porque la pantalla no envía datos de vuelta.

Crear e iniciar la pantalla

Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_RST);
tft.init(TFT_WIDTH, TFT_HEIGHT);

El objeto tft recibe los tres pines de control y usa el bus SPI que acabamos de configurar. init() reinicia la pantalla y le indica su resolución.

Sistema de coordenadas

La esquina superior izquierda es el punto (0, 0). La X crece hacia la derecha y la Y hacia abajo, hasta (239, 239) en la esquina inferior derecha.

(0,0) ────────────────► X (239)
  │
  │     ┌─────────┐
  │     │ (x, y)  │ alto
  │     └─────────┘
  │        ancho
  ▼
  Y (239)

setRotation() gira ese sistema: 0 es la posición normal y 1, 2 y 3 giran 90°, 180° y 270°.

Funciones de dibujo usadas

Función Qué hace
fillScreen(color) Pinta toda la pantalla de un color
setCursor(x, y) Coloca el punto donde empieza el texto
setTextSize(n) Escala la letra: 1 mide 6×8 píxeles, 2 el doble, etc.
setTextColor(texto, fondo) Color del texto y, opcionalmente, del fondo
println() / printf() Escribe texto en la posición del cursor
drawRect(x, y, ancho, alto, color) Rectángulo solo con borde
fillRect(x, y, ancho, alto, color) Rectángulo relleno
drawCircle(x, y, radio, color) Círculo con centro en (x, y)

Las funciones draw… dibujan solo el contorno y las fill… lo rellenan. También existen drawLine, drawTriangle, fillCircle y drawRoundRect, entre otras.

Colores

La pantalla usa colores de 16 bits (RGB565): 5 bits para rojo, 6 para verde y 5 para azul. La librería trae constantes listas: ST77XX_BLACK, ST77XX_WHITE, ST77XX_RED, ST77XX_GREEN, ST77XX_BLUE, ST77XX_CYAN, ST77XX_MAGENTA, ST77XX_YELLOW y ST77XX_ORANGE.

Para un color propio, conviértelo desde RGB:

uint16_t morado = tft.color565(128, 0, 255);

Actualizar sin parpadeo

En el loop(), el contador se escribe con setTextColor(ST77XX_CYAN, ST77XX_BLACK). Al indicar un color de fondo, cada carácter pinta también su recuadro y borra el número anterior. Así no hace falta llamar a fillScreen(), que redibuja los 57 600 píxeles y produce parpadeo.

Además, millis() en lugar de delay() hace que el loop() no se bloquee, por lo que podrías leer botones o hacer otras tareas al mismo tiempo.

5. Resultado esperado

  • Fondo negro con los textos ESP32-S3 y LCD 240x240 en blanco.
  • Un marco rojo con tres rectángulos rellenos: azul, verde y rojo.
  • Un círculo amarillo abajo a la izquierda.
  • Un contador en cian que aumenta cada segundo.
  • En el monitor serie, a 115200 baudios: Iniciando pantalla ST7789... y Pantalla OK.

6. Solución de problemas

Síntoma Causa probable y solución
La pantalla queda totalmente negra La retroiluminación está apagada: comprueba que BLK llegue a 3,3 V.
Se ilumina pero no dibuja nada Revisa los pines SDA, SCL, DC y CS, y que SPI.begin() esté antes de init().
Los colores salen invertidos Algunos módulos invierten los colores: añade tft.invertDisplay(false); después de init().
La imagen aparece desplazada o recortada El módulo puede ser de 240×320: usa tft.init(240, 320);.
No aparece nada en el monitor serie Activa USB CDC On Boot o conecta el cable al puerto UART.

7. Retos

  1. Cambia setRotation(0) por 1, 2 y 3 y observa cómo gira el dibujo.
  2. Dibuja una barra que crezca con el contador usando fillRect().
  3. Combina este ejemplo con el Ejemplo 1: muestra en la pantalla qué botón está presionado.