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
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
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.
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:
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...yPantalla 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
- Cambia
setRotation(0)por1,2y3y observa cómo gira el dibujo. - Dibuja una barra que crezca con el contador usando
fillRect(). - Combina este ejemplo con el Ejemplo 1: muestra en la pantalla qué botón está presionado.