ST7789 ESP32: pantalla IPS a color con TFT_eSPI, sprites y reloj
Guía ST7789 ESP32: TFT_eSPI y User_Setup.h, pines SPI rotulados SCL/SDA, indicador y reloj sin parpadeo con sprites, Adafruit en el Uno, Pico y pantalla negra.
La pareja ST7789 ESP32 es la forma más barata de dar a un proyecto pequeño una interfaz a color con calidad de pantalla de móvil. El ST7789 es un chip controlador de TFT fabricado por Sitronix y está en la mayoría de las pantallas IPS del mercado de 1,3 pulgadas 240x240, 1,54 pulgadas 240x240, 1,69 pulgadas 240x280 y 2,0 pulgadas 240x320. Gracias al panel IPS los colores se ven vivos desde cualquier ángulo; con 65 mil colores, alta resolución y una conexión SPI rápida puedes dibujar indicadores, gráficas y animaciones que una OLED o una LCD de caracteres no pueden.
En esta guía verás paso a paso cómo conectar el ST7789 a un ESP32 con la librería TFT_eSPI, cómo configurar User_Setup.h, la parte más confusa de la librería, por qué el módulo usa SPI y no I2C aunque ponga SCL y SDA, cómo animar sin parpadeo con un sprite y cómo crear un indicador analógico para un sensor y un reloj que funciona con NTP. También veremos la librería Adafruit_ST7789 para el Arduino Uno, un controlador MicroPython sin librerías para la Raspberry Pi Pico y todas las causas de la pantalla negra.

¿Qué es el ST7789 y en qué pantallas se usa?
El ST7789 es un chip controlador que gestiona cada píxel de la pantalla y convierte en imagen las órdenes del microcontrolador. Dentro tiene una memoria de imagen de 240x320 píxeles; las pantallas más pequeñas solo usan una parte. Los colores se envían casi siempre en formato RGB565, es decir, 16 bits por píxel (5 bits de rojo, 6 de verde y 5 de azul). La comunicación va por SPI de 4 hilos y el chip admite relojes de unos 60 MHz; en la práctica, con el ESP32, 40 MHz es un valor seguro. A esa velocidad un fotograma completo de 240x240 son 921.600 bits y se envía en unos 23 ms, así que se pueden superar los 40 fotogramas por segundo.
| Pantalla | Resolución | Uso típico |
|---|---|---|
| 1,14 pulgadas | 135x240 | Placas ESP32 con pantalla como la TTGO T-Display |
| 1,3 y 1,54 pulgadas | 240x240 | Relojes inteligentes, indicadores pequeños, interfaces cuadradas |
| 1,69 pulgadas | 240x280 | Pantallas de reloj con esquinas redondeadas |
| 1,9 pulgadas | 170x320 | Barras de estado largas y estrechas |
| 2,0 pulgadas | 240x320 | Menús, gráficas y pantallas de pequeños juegos |
| Característica | Valor |
|---|---|
| Chip controlador | ST7789 (Sitronix) |
| Panel | IPS, amplio ángulo de visión |
| Colores | 65 mil (RGB565), el chip admite hasta 262 mil |
| Interfaz | SPI de 4 hilos (SCK, MOSI, DC, CS) y RESET |
| Alimentación | 3,3 V en la mayoría de los módulos |
| Nivel lógico | 3,3 V |
| Consumo | Unos 20–40 mA con la retroiluminación |
Pines: pone SCL y SDA, pero esta pantalla es SPI
Los módulos ST7789 baratos de 1,3 pulgadas llevan rotulado GND, VCC, SCL, SDA, RES, DC, BLK; algunos tienen además CS. Los rótulos SCL y SDA son lo que más confunde a los principiantes: esta pantalla no usa I2C, sino SPI. SCL es en realidad la línea de reloj SPI (SCK) y SDA la línea de datos (MOSI). Si las conectas a los pines I2C del ESP32, GPIO 21 y 22, la pantalla nunca funcionará. Explicamos cómo funciona el SPI en la guía qué es SPI.
| Pin del módulo | Función | ESP32 (TFT_eSPI) | Arduino Uno (Adafruit) | Raspberry Pi Pico |
|---|---|---|---|---|
| GND | Masa | GND | GND | GND |
| VCC | Alimentación | 3V3 | 3.3V | 3V3 (OUT) |
| SCL | Reloj SPI (SCK) | GPIO 18 | D13 | GP18 |
| SDA | Datos SPI (MOSI) | GPIO 23 | D11 | GP19 |
| RES | Reset | GPIO 4 | D8 | GP21 |
| DC | Selección de datos o comando | GPIO 2 | D9 | GP20 |
| CS | Selección de chip (si lo tiene) | GPIO 5 | D10 | GP17 |
| BLK | Retroiluminación | GPIO 32 | 3.3V | GP22 |
Instalar TFT_eSPI y configurar User_Setup.h

TFT_eSPI, escrita por Bodmer, es una de las librerías TFT más rápidas para el ESP32. Búscala como TFT_eSPI en el Gestor de librerías e instálala. A diferencia de otras librerías, el tipo de pantalla y los pines no se definen en el sketch, sino en el archivo User_Setup.h de la carpeta de la librería. Está en Documentos > Arduino > libraries > TFT_eSPI y por defecto viene configurado para una pantalla ILI9341. Ábrelo con un editor de texto y sustituye su contenido por lo siguiente:
1// User_Setup.h: ST7789 240x240 + ESP32 (dosyanın tamamını bununla değiştir / replace the whole file with this)
2#define ST7789_DRIVER // sürücü yonga / driver chip
3#define TFT_WIDTH 240
4#define TFT_HEIGHT 240 // 240x320 ekranda 320 / 320 for a 240x320 panel
5
6#define TFT_MOSI 23 // modüldeki SDA / SDA on the module
7#define TFT_SCLK 18 // modüldeki SCL / SCL on the module
8#define TFT_CS 5 // CS pini yoksa -1 / -1 if the module has no CS pin
9#define TFT_DC 2 // veri-komut / data-command
10#define TFT_RST 4 // reset (RES)
11#define TFT_BL 32 // arka ışık (BLK) / backlight (BLK)
12#define TFT_BACKLIGHT_ON HIGH
13
14// #define TFT_RGB_ORDER TFT_BGR // kırmızı ve mavi yer değiştirmişse aç / enable if red and blue are swapped
15// #define TFT_INVERSION_OFF // renkler negatif görünüyorsa aç / enable if colours look inverted
16
17#define LOAD_GLCD // 8 px yazı tipi / 8 px font
18#define LOAD_FONT2 // 16 px
19#define LOAD_FONT4 // 26 px
20#define LOAD_FONT7 // 48 px 7 segment rakam / 48 px 7-segment digits
21#define LOAD_GFXFF // Adafruit GFX yazı tipleri / Adafruit GFX fonts
22#define SMOOTH_FONT
23
24#define SPI_FREQUENCY 40000000 // 40 MHz; sorun olursa 27000000 / 40 MHz; drop to 27000000 if unstable- Instala TFT_eSPI y sustituye User_Setup.h por las líneas anteriores.
- Si tu pantalla es de 240x320, pon TFT_HEIGHT a 320; en un módulo sin pin CS, pon TFT_CS a -1.
- Conecta la pantalla como en la tabla: SCL a GPIO 18, SDA a GPIO 23, RES a GPIO 4, DC a GPIO 2, CS a GPIO 5 y BLK a GPIO 32.
- Cierra y vuelve a abrir el Arduino IDE; los ajustes de la librería se leen al compilar.
- Sube el primer sketch de prueba de abajo; deberías ver texto y formas de colores en la pantalla.
Primera prueba: texto, formas y colores
1#include <TFT_eSPI.h> // ayarlar User_Setup.h içinde / settings live in User_Setup.h
2
3TFT_eSPI tft = TFT_eSPI();
4
5void setup() {
6 tft.init();
7 tft.setRotation(0); // 0-3: ekranı 90'ar derece döndürür / rotates in 90° steps
8 tft.fillScreen(TFT_BLACK);
9
10 tft.setTextDatum(MC_DATUM); // metni ortadan hizala / centre-align text
11 tft.setTextColor(TFT_WHITE, TFT_BLACK);
12 tft.drawString("BlueGrays", 120, 30, 4); // metin, x, y, yazı tipi / text, x, y, font
13 tft.drawString("ST7789 240x240", 120, 60, 2);
14
15 tft.fillRect(20, 90, 60, 60, TFT_RED); // dolu kare / filled square
16 tft.fillCircle(120, 120, 30, TFT_GREEN); // dolu daire / filled circle
17 tft.fillTriangle(170, 150, 200, 90, 230, 150, TFT_BLUE);
18 tft.drawRoundRect(10, 170, 220, 50, 10, TFT_YELLOW);
19
20 uint16_t orange = tft.color565(255, 140, 0); // kendi rengin (RGB565) / your own colour (RGB565)
21 tft.setTextColor(orange, TFT_BLACK);
22 tft.drawString("R G B", 120, 195, 4);
23}
24
25void loop() {
26}En TFT_eSPI las coordenadas empiezan en la esquina superior izquierda (0, 0) y la esquina inferior derecha de una pantalla de 240x240 es (239, 239). El último número de drawString(texto, x, y, fuente) elige la fuente: 1 es una fuente pequeña de 8 píxeles, 2 de 16 píxeles, 4 de 26 píxeles y 7 una fuente de dígitos de 7 segmentos de 48 píxeles. setTextDatum(MC_DATUM) centra el texto en el punto indicado, algo muy útil para indicadores y relojes. Los colores se dan con nombres predefinidos como TFT_RED y TFT_GREEN o con tus propios tonos mediante color565(r, g, b).
| Función | ¿Qué hace? |
|---|---|
| fillScreen(color) | Pinta toda la pantalla |
| drawPixel(x, y, color) | Un solo píxel |
| drawLine / drawWideLine | Línea fina o gruesa |
| drawRect / fillRect / fillRoundRect | Rectángulo, relleno y con esquinas redondeadas |
| drawCircle / fillCircle | Círculo |
| fillTriangle | Triángulo relleno |
| drawString / drawNumber / drawFloat | Texto, número entero y decimal |
| setRotation(0-3) | Gira la pantalla en pasos de 90 grados |
Animación sin parpadeo con sprites
Cuando dibujas directamente en la pantalla, para actualizar algo primero borras lo viejo y luego dibujas lo nuevo. Entre esos dos pasos la pantalla se queda vacía un instante y el ojo lo percibe como parpadeo. El sprite soluciona el problema: dibujas primero en un lienzo invisible en la RAM del ESP32 y, cuando el fotograma está listo del todo, lo envías a la pantalla de una vez con pushSprite(). Nunca aparece un dibujo a medias.
El único precio del sprite es la memoria. Un sprite de color de 16 bits usa 2 bytes por píxel: uno de pantalla completa de 240x240 ocupa 115.200 bytes y uno de 240x320, 153.600 bytes. Aunque el ESP32 tiene 520 KB de RAM en total, el bloque más grande que se puede reservar de una pieza suele rondar los 110 KB, así que en una placa sin PSRAM puede que no quepa un sprite de pantalla completa de 16 bits. La solución es bajar a color de 8 bits con setColorDepth(8) (57,6 KB para 240x240) o dibujar como sprite pequeño solo la zona que cambia, por ejemplo los dígitos del reloj. createSprite() devuelve nullptr si no encuentra memoria; comprobarlo evita fallos silenciosos.
| Tamaño del sprite | 16 bits | 8 bits |
|---|---|---|
| 240x240 (pantalla completa) | 115,2 KB | 57,6 KB |
| 240x320 (pantalla completa) | 153,6 KB | 76,8 KB |
| 220x120 (zona del reloj) | 52,8 KB | 26,4 KB |
| 100x50 (un solo valor) | 10 KB | 5 KB |
Proyecto: indicador analógico para un sensor
El sketch siguiente convierte un potenciómetro en GPIO 34 en un valor de 0 a 100 y lo muestra con una aguja sobre un arco de 270 grados, como el velocímetro de un coche. Las marcas de la escala por encima de 80 son rojas. En lugar del potenciómetro puedes pasar a la misma función un valor de temperatura, humedad, gas o humedad del suelo. Como el sprite se borra y se redibuja desde cero en cada fotograma, la aguja se mueve con suavidad y nunca parpadea.
1#include <TFT_eSPI.h>
2
3TFT_eSPI tft = TFT_eSPI();
4TFT_eSprite spr = TFT_eSprite(&tft); // bellekteki çizim alanı / off-screen drawing area
5
6const int POT_PIN = 34; // potansiyometre ya da sensör / potentiometer or sensor
7const int CX = 120, CY = 130, R = 100;
8float smooth = 0;
9
10void pointAt(float v, int radius, int &x, int &y) { // 0-100 değeri yay üzerindeki noktaya çevir / value to a point on the arc
11 float a = radians(225 - v * 2.7); // 270 derecelik yay / 270-degree arc
12 x = CX + cos(a) * radius;
13 y = CY - sin(a) * radius;
14}
15
16void drawGauge(int value) {
17 spr.fillSprite(TFT_BLACK); // her kare temiz başlar / every frame starts clean
18 for (int v = 0; v <= 100; v += 5) { // ölçek çizgileri / scale ticks
19 int x0, y0, x1, y1;
20 pointAt(v, R, x0, y0);
21 pointAt(v, (v % 10 == 0) ? R - 14 : R - 7, x1, y1);
22 spr.drawLine(x0, y0, x1, y1, v >= 80 ? TFT_RED : TFT_LIGHTGREY);
23 }
24 int nx, ny;
25 pointAt(value, R - 20, nx, ny);
26 spr.drawWideLine(CX, CY, nx, ny, 4, TFT_ORANGE); // ibre / needle
27 spr.fillCircle(CX, CY, 8, TFT_DARKGREY);
28
29 spr.setTextDatum(MC_DATUM);
30 spr.setTextColor(TFT_WHITE);
31 spr.drawNumber(value, CX, CY + 55, 7); // 7 segment rakam / 7-segment digits
32 spr.drawString("%", CX + 62, CY + 62, 4);
33 spr.pushSprite(0, 0); // tek seferde ekrana bas / push to the screen in one go
34}
35
36void setup() {
37 tft.init();
38 tft.fillScreen(TFT_BLACK);
39 spr.setColorDepth(8); // 8 bit: 57,6 KB, 16 bit olsa 115 KB / 8-bit: 57.6 KB instead of 115 KB
40 if (spr.createSprite(240, 240) == nullptr) { // bellek yetmezse / if memory runs out
41 tft.drawString("Sprite RAM yok", 10, 10, 2);
42 while (true) delay(100);
43 }
44}
45
46void loop() {
47 float raw = analogRead(POT_PIN) * 100.0 / 4095.0; // 0-100 aralığı / 0-100 range
48 smooth += (raw - smooth) * 0.2; // titremeyi yumuşat / smooth out jitter
49 drawGauge((int)smooth);
50 delay(20); // yaklaşık 40 kare/sn / about 40 frames per second
51}La función pointAt() del código convierte un valor de 0 a 100 en un punto del arco: 0 corresponde a 225 grados (abajo a la izquierda) y 100 a −45 grados (abajo a la derecha). Como en la pantalla el eje y crece hacia abajo, delante del seno hay un signo menos. La variable smooth filtra las pequeñas fluctuaciones del ADC; si bajas el factor 0,2 la aguja se mueve con más pesadez, y si lo subes reacciona más rápido. Para saber más sobre el ADC del ESP32, consulta la guía qué es un ADC.
Proyecto: interfaz de reloj con NTP
Uno de los usos favoritos del ST7789 es un reloj de escritorio. El sketch siguiente conecta el ESP32 al Wi-Fi, obtiene la hora de los servidores NTP de internet, aquí con la zona horaria de Turquía, y la muestra en grandes dígitos de 7 segmentos. Esta vez, en lugar de un sprite de pantalla completa, usamos uno de 220x120 que solo cubre la zona del reloj; el nombre del día se escribe directamente en la pantalla porque cambia solo una vez al día. Para la España peninsular pon TZ_INFO a "CET-1CEST,M3.5.0,M10.5.0/3"; los detalles de NTP y las zonas horarias están en la guía hora NTP con ESP32.
1#include <WiFi.h>
2#include <time.h>
3#include <TFT_eSPI.h>
4
5const char* WIFI_SSID = "AgAdi";
6const char* WIFI_PASS = "Sifre123";
7const char* TZ_INFO = "<+03>-3"; // Türkiye UTC+3 / Turkey UTC+3
8const char* DAYS[] = {"Pazar", "Pazartesi", "Sali", "Carsamba", "Persembe", "Cuma", "Cumartesi"};
9
10TFT_eSPI tft = TFT_eSPI();
11TFT_eSprite clockSpr = TFT_eSprite(&tft); // yalnız saat bölgesi / clock area only
12int lastSecond = -1;
13
14void setup() {
15 tft.init();
16 tft.fillScreen(TFT_NAVY);
17 tft.setTextDatum(MC_DATUM);
18 tft.setTextColor(TFT_WHITE, TFT_NAVY);
19 tft.drawString("Wi-Fi...", 120, 120, 4);
20
21 WiFi.begin(WIFI_SSID, WIFI_PASS);
22 while (WiFi.status() != WL_CONNECTED) delay(300);
23 configTzTime(TZ_INFO, "pool.ntp.org", "time.cloudflare.com");
24
25 tft.fillScreen(TFT_NAVY);
26 clockSpr.createSprite(220, 120); // 16 bit: 52,8 KB / 16-bit: 52.8 KB
27 clockSpr.setTextDatum(MC_DATUM);
28}
29
30void loop() {
31 struct tm t;
32 if (!getLocalTime(&t, 100) || t.tm_sec == lastSecond) return; // saniye değişince çiz / draw on each new second
33 lastSecond = t.tm_sec;
34
35 char hm[6], sec[3], date[11];
36 strftime(hm, sizeof(hm), "%H:%M", &t);
37 strftime(sec, sizeof(sec), "%S", &t);
38 strftime(date, sizeof(date), "%d.%m.%Y", &t);
39
40 clockSpr.fillSprite(TFT_NAVY);
41 clockSpr.fillRoundRect(0, 0, 220, 120, 14, TFT_BLACK);
42 clockSpr.setTextColor(TFT_CYAN);
43 clockSpr.drawString(hm, 95, 45, 7); // büyük saat:dakika / big hours:minutes
44 clockSpr.setTextColor(TFT_ORANGE);
45 clockSpr.drawString(sec, 195, 55, 4); // saniye / seconds
46 clockSpr.setTextColor(TFT_WHITE);
47 clockSpr.drawString(date, 110, 100, 4);
48 clockSpr.pushSprite(10, 40); // titremeden güncelle / update without flicker
49
50 tft.setTextColor(TFT_YELLOW, TFT_NAVY);
51 tft.fillRect(0, 175, 240, 30, TFT_NAVY);
52 tft.drawString(DAYS[t.tm_wday], 120, 190, 4); // gün adı / day name
53}El reloj solo se redibuja cuando cambia el segundo, así que mientras loop() gira el procesador tiene tiempo para otras tareas. Las fuentes integradas de TFT_eSPI no tienen tildes, por eso los nombres de los días en turco del código están escritos sin caracteres especiales; cámbialos por "Lunes", "Martes" y demás si quieres. Si necesitas tildes y la ñ, puedes crear y cargar tu propia fuente con la función smooth font de TFT_eSPI. Para añadir una línea con el tiempo a este reloj, basta con combinarlo con el código de Open-Meteo de la guía API del clima con ESP32.
ST7789 con el Arduino Uno: Adafruit_ST7789
TFT_eSPI no funciona en el Arduino Uno; aquí se usan la Adafruit ST7735 and ST7789 Library y Adafruit GFX. Los 2 KB de RAM del Uno no alcanzan ni para un sprite, así que todo se dibuja directamente en la pantalla y la velocidad es claramente menor que en el ESP32. Aun así sirve para menús, números y gráficos sencillos. Los pines del SPI por hardware son fijos: SDA (MOSI) va a D11 y SCL (SCK) a D13; para CS, DC y RST puedes elegir los pines digitales que quieras.
1#include <Adafruit_GFX.h>
2#include <Adafruit_ST7789.h>
3#include <SPI.h>
4
5#define TFT_CS 10 // CS pini yoksa -1 / -1 if there is no CS pin
6#define TFT_DC 9
7#define TFT_RST 8
8// SDA (MOSI) -> D11, SCL (SCK) -> D13: donanım SPI / hardware SPI
9
10Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_RST);
11
12void setup() {
13 tft.init(240, 240); // CS'siz modülde: tft.init(240, 240, SPI_MODE3) / without CS
14 tft.setRotation(0);
15 tft.fillScreen(ST77XX_BLACK);
16 tft.setTextColor(ST77XX_WHITE);
17 tft.setTextSize(3);
18 tft.setCursor(20, 20);
19 tft.print(F("BlueGrays"));
20 tft.setTextSize(2);
21 tft.setCursor(20, 70);
22 tft.print(F("A0 degeri:"));
23}
24
25void loop() {
26 int value = analogRead(A0);
27 tft.setTextColor(ST77XX_YELLOW, ST77XX_BLACK); // arka plan rengi eski rakamı siler / background colour erases old digits
28 tft.setTextSize(5);
29 tft.setCursor(20, 110);
30 if (value < 1000) tft.print(' '); // basamak sayısı değişince boşluk / pad when digits shrink
31 if (value < 100) tft.print(' ');
32 if (value < 10) tft.print(' ');
33 tft.print(value);
34 delay(200);
35}Este sketch muestra la forma de evitar el parpadeo adecuada para el Uno: cuando se llama a setTextColor(colorTexto, colorFondo) con dos colores, cada carácter se dibuja junto con su propio fondo y escribe encima del dígito anterior. No hace falta borrar la pantalla y el número cambia sin parpadear. Los espacios iniciales evitan que queden restos de los dígitos viejos cuando el número se acorta. Si quieres una pantalla parecida en un panel táctil de 2,4 pulgadas, la guía pantalla TFT ILI9341 sigue la misma lógica.
ST7789 con la Raspberry Pi Pico (MicroPython)
MicroPython no trae un controlador integrado para el ST7789, pero los comandos del chip son lo bastante simples como para escribir tu propio controlador pequeño. Los 264 KB de RAM de la Pico bastan para un búfer de imagen de 115 KB que cubre toda la pantalla de 240x240. El código siguiente inicializa la pantalla, dibuja texto y formas en el búfer con el módulo framebuf de MicroPython y envía el búfer por SPI de una sola vez; un cuadrado que se desplaza muestra cómo animar. La conexión usa el bus SPI0: SCL a GP18 y SDA a GP19.
1from machine import Pin, SPI
2import framebuf
3import time
4
5W, H = 240, 240
6spi = SPI(0, baudrate=40_000_000, polarity=1, phase=1, sck=Pin(18), mosi=Pin(19)) # SPI mod 3 / SPI mode 3
7cs = Pin(17, Pin.OUT, value=1) # CS'siz modülde boşta kalır / unused on modules without CS
8dc = Pin(20, Pin.OUT)
9rst = Pin(21, Pin.OUT, value=1)
10bl = Pin(22, Pin.OUT, value=1) # arka ışık açık / backlight on
11
12def cmd(c, data=None): # komut + isteğe bağlı veri / command + optional data
13 cs(0)
14 dc(0)
15 spi.write(bytes([c]))
16 if data:
17 dc(1)
18 spi.write(data)
19 cs(1)
20
21def init():
22 rst(0); time.sleep_ms(50); rst(1); time.sleep_ms(150)
23 cmd(0x01); time.sleep_ms(150) # SWRESET: yazılım reseti / software reset
24 cmd(0x11); time.sleep_ms(120) # SLPOUT: uykudan çık / exit sleep
25 cmd(0x3A, b'\x55') # COLMOD: 16 bit RGB565
26 cmd(0x36, b'\x00') # MADCTL: yön, RGB sırası / orientation, RGB order
27 cmd(0x21) # INVON: IPS paneller için / for IPS panels
28 cmd(0x13) # NORON: normal mod / normal mode
29 cmd(0x29); time.sleep_ms(50) # DISPON: ekranı aç / display on
30
31def show(buf):
32 cmd(0x2A, bytes([0, 0, 0, W - 1])) # CASET: sütun 0-239 / columns 0-239
33 cmd(0x2B, bytes([0, 0, 0, H - 1])) # RASET: satır 0-239 / rows 0-239
34 cmd(0x2C, buf) # RAMWR: tamponu gönder / send the buffer
35
36def rgb(r, g, b): # RGB565, bayt sırası ekrana göre çevrilmiş / byte-swapped for the panel
37 c = ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)
38 return ((c & 0xFF) << 8) | (c >> 8)
39
40init()
41buf = bytearray(W * H * 2) # 115.200 bayt / 115,200 bytes
42fb = framebuf.FrameBuffer(buf, W, H, framebuf.RGB565)
43
44x, dx = 0, 4
45while True:
46 fb.fill(rgb(0, 0, 40))
47 fb.text("BlueGrays", 84, 20, rgb(255, 255, 255))
48 fb.text("Pico + ST7789", 68, 40, rgb(0, 200, 255))
49 fb.rect(20, 200, 200, 20, rgb(255, 255, 0))
50 fb.fill_rect(20 + x, 100, 40, 40, rgb(255, 60, 0)) # kayan kare / moving square
51 show(buf) # tüm kareyi tek seferde gönder / send the whole frame at once
52 x += dx
53 if x <= 0 or x >= 160:
54 dx = -dxLa función rgb() del código resuelve un detalle importante: framebuf guarda los colores en memoria con el byte bajo primero, mientras que el ST7789 espera primero el byte alto. Si no intercambias los bytes, el rojo se ve azul y el azul verdoso. El comando 0x36 (MADCTL) fija la orientación de la pantalla y el orden RGB o BGR; si giras la imagen 180 grados en un panel de 240x240, la imagen se desplaza a la parte inferior de la memoria y tienes que sumar un desplazamiento de 80 píxeles a la dirección de fila. Si prefieres el Arduino IDE, instala el núcleo arduino-pico en la Pico y usa TFT_eSPI con su configuración para RP2040. Si eres nuevo en MicroPython, empieza por la guía fundamentos de MicroPython.
Pantalla negra y otros problemas: tabla de soluciones
| Síntoma | Causa probable | Solución |
|---|---|---|
| Pantalla totalmente negra, sin retroiluminación | BLK sin conectar o en LOW | Conecta BLK a 3,3 V o al pin TFT_BL, con TFT_BACKLIGHT_ON en HIGH |
| Retroiluminación encendida pero sin imagen | User_Setup.h sigue en ILI9341 o se reinició al actualizar | Revisa de nuevo la línea ST7789_DRIVER y los pines |
| Retroiluminación encendida, sin imagen (módulo sin CS) | Modo SPI incorrecto | Pon TFT_CS a -1; con Adafruit usa init(240, 240, SPI_MODE3) |
| No pasa nada | SCL y SDA conectados a los pines I2C (21, 22) | Conecta SCL a GPIO 18 y SDA a GPIO 23 |
| Funciona a ratos | Pin de reset al aire, cables largos o SPI demasiado rápido | Conecta RES, acorta los cables, baja SPI_FREQUENCY a 27 MHz |
| Colores como un negativo | La inversión de color no coincide con el panel | Prueba TFT_INVERSION_OFF o TFT_INVERSION_ON |
| Rojo y azul intercambiados | El panel usa orden BGR | Activa la línea TFT_RGB_ORDER TFT_BGR |
| Una franja con ruido en parte de la pantalla | Altura incorrecta (320 en un panel de 240x240) o desplazamiento al girar | Pon bien TFT_HEIGHT y prueba con setRotation |
| El ESP32 se cuelga en tft.init() | Incompatibilidad reportada con el núcleo ESP32 3.x | Prueba un núcleo 2.0.x desde el Gestor de placas o pásate a la librería LovyanGFX |
| La pantalla se calienta o se estropea con el Uno | Nivel lógico de 5 V | Usa un conversor de nivel |
Ideas de proyectos con el ST7789
- Reloj de escritorio inteligente: Muestra la hora NTP, la temperatura de la habitación con un BME280 y el tiempo del día desde internet en una sola pantalla.
- Panel de sensores: Presenta temperatura, humedad y gas en indicadores de colores; que el fondo se ponga rojo cuando el MQ-2 supere el umbral.
- Miniconsola de juegos: Juega a la serpiente, al Pong o a un juego espacial con un joystick; los sprites mantienen el juego fluido.
- Interfaz de reproductor de música: Muestra el título de la canción, el volumen y una barra de progreso de un DFPlayer Mini.
- Gráfica tipo osciloscopio: Dibuja los valores de analogRead como una gráfica que se desplaza y observa la forma de la señal.
- Pantalla para lector de tarjetas: Muestra el nombre y el permiso de la tarjeta leída con un RFID RC522 en una ficha de colores.
Junto a un ESP32, el ST7789 convierte una pantalla de pocos euros en una interfaz de aspecto profesional. Cuando configuras bien User_Setup.h y entiendes la idea del sprite, puedes dibujar relojes, indicadores, menús, juegos y cualquier otra interfaz sin parpadeo. Para comparar qué pantalla encaja con tu proyecto, consulta la guía tipos de pantallas para Arduino. En la app BlueGrays encontrarás proyectos ESP32 de clima, reloj, mezclador de colores y sensor de aparcamiento con pantallas OLED y LCD, con su esquema y su código paso a paso, y podrás pasar esos mismos proyectos a color con el ST7789.
Preguntas frecuentes
¿El ST7789 es I2C o SPI?
El ST7789 funciona por SPI. Los rótulos SCL y SDA del módulo engañan: SCL es la línea de reloj SPI (SCK) y SDA la línea de datos (MOSI). En un ESP32 conéctalos a GPIO 18 y GPIO 23, no a los pines I2C 21 y 22.
¿Por qué mi pantalla ST7789 se queda negra?
Las causas más habituales son una retroiluminación (BLK) sin conectar, un User_Setup.h que todavía tiene seleccionado el controlador ILI9341, SCL y SDA conectados a los pines I2C y el modo SPI incorrecto en un módulo sin CS. Primero asegúrate de que la retroiluminación se enciende y después revisa las líneas ST7789_DRIVER, TFT_WIDTH, TFT_HEIGHT y los pines de User_Setup.h.
¿El ST7789 funciona con 5 V?
El chip ST7789 trabaja a 3,3 V y sus pines no toleran 5 V. El ESP32 y la Pico se conectan directamente; con un Arduino Uno, alimenta el módulo a 3,3 V y pon un conversor de nivel en las líneas de señal. Algunos módulos llevan regulador, pero las líneas de datos siguen siendo de 3,3 V.
¿Dónde está el archivo User_Setup.h de TFT_eSPI?
User_Setup.h está dentro de la carpeta TFT_eSPI de tu carpeta de librerías de Arduino, normalmente en Documentos > Arduino > libraries > TFT_eSPI. En él se definen el controlador de pantalla, la resolución, los pines y la velocidad SPI. Se reinicia al actualizar la librería, así que guarda una copia de tu configuración.
¿Qué es un sprite y por qué evita el parpadeo?
Un sprite es una zona de dibujo invisible guardada en la RAM del ESP32. Primero dibujas todo en ella y, cuando está lista, la envías a la pantalla de una vez con pushSprite(), así que la imagen intermedia borrada nunca llega a verse. El precio es la memoria: con color de 16 bits cada píxel ocupa 2 bytes.
¿Se puede usar el ST7789 con un Arduino Uno?
Sí, con las librerías Adafruit ST7789 y Adafruit GFX, pero el dibujo es lento porque los 2 KB de RAM del Uno no dan para un sprite. Sus pines son de 5 V, así que necesitas un conversor de nivel entre ambos. Si quieres una interfaz a color fluida, el ESP32 es una opción mucho mejor.
Proyectos para hacer después de leer esto
Ver todos los proyectos
ESP32 HTTPClient + API del tiempo (con pantalla OLED SSD1306)
El ESP32 hace una llamada REST por internet a una API del tiempo (wttr.in) con HTTPClient.h. A diferencia de la versión con LCD I2C, aquí usamos una pantalla OLED SSD1306 (128×64), con letra grande e iconos vectoriales para una vista más rica. Siete iconos del tiempo (soleado, lluvia, nieve y más) se dibujan al momento, sin archivos bitmap.

Pantalla LCD I2C para ESP32 (16x2)
En este proyecto conectamos una pantalla LCD de caracteres 16x2 al ESP32 por I2C para mostrar texto. Con I2C bastan 2 pines de datos (SDA y SCL), en lugar de los 6+ pines de una conexión paralela clásica. El código escribe un mensaje fijo en la primera línea y un contador que sube cada segundo en la segunda. Al arrancar, un escáner I2C muestra la dirección de la pantalla en el Serial Monitor (normalmente 0x27 o 0x3F).

ESP32 TM1637 Pantalla de 4 dígitos y 7 segmentos
Controlamos el módulo de pantalla de 7 segmentos y 4 dígitos con controlador TM1637 mediante un ESP32. Utilizando solo 2 GPIO (CLK y DIO), hacemos funcionar un contador de 0 a 9999, ajustamos el nivel de brillo y mostramos el carácter de dos puntos (:) en el centro en formato de reloj. Gracias a la biblioteca TM1637Display, el control de números, hexadecimales, segmentos y cadenas es muy sencillo.

Modo de suspensión profunda del ESP32 — Ahorro de batería (OLED + contador en RTC RAM)
El modo Deep Sleep del ESP32 apaga la CPU y la mayoría de los periféricos y reduce el consumo a unos 10µA, algo clave para dispositivos IoT con batería. Este proyecto usa tres fuentes de activación: un temporizador (15 s), un pin externo (EXT0, el botón en GPIO 33) y un pin táctil (T0/GPIO 4). Los contadores marcados con RTC_DATA_ATTR se conservan durante el deep sleep.

Contador de rak'ahs para la oración con ESP32 (HC-SR04 + OLED SSD1306 + 2 botones)
¿A veces pierdes la cuenta de los rakats durante la oración? Este proyecto es un contador de rakats que va junto a tu alfombra y cuenta las postraciones cuando acercas la mano. El sensor ultrasónico HC-SR04 detecta la mano, la pantalla OLED SSD1306 muestra el número y con dos botones eliges 2, 3 o 4 rakats y reinicias. Un antirrebote de 2,5 segundos y una comprobación de mano retirada evitan contar dos veces la misma postración.

Lámpara con mezclador de colores ESP32 (3 potenciómetros + LED RGB + OLED)
Una lámpara mezcladora de colores inteligente: gira 3 potenciómetros en el ESP32 y mezcla el color que quieras. Al girar los potenciómetros rojo, verde y azul, el LED RGB de cátodo común cambia de color al instante. La pantalla OLED SSD1306 muestra en vivo el valor de 0-255 de cada color, barras de relleno y el código de color web HEX (como #FF8040).

Sensor de aparcamiento ESP32 (HC-SR04 + barra de 5 LED + zumbador + OLED)
¡La versión ESP32 de un sensor de aparcamiento! El sensor ultrasónico HC-SR04 mide la distancia al objeto que tiene delante. Cuanto más cerca está, más se llena una barra de 5 LED (verde → amarillo → rojo) y más rápido pita el zumbador. Muy cerca (por debajo de 10 cm) suena una alarma continua y se encienden todos los LED. La OLED SSD1306 muestra los cm en tiempo real con letra grande y un texto de estado.

Juego de Raquetas - SSD1306
Una pelota, dos palas y tú: juegas al tenis de mesa, uno de los primeros videojuegos de la historia, en una pequeña pantalla OLED.
Más artículos
App BlueGrays
Monta este circuito paso a paso en tu teléfono
Esquema, código y lista de piezas en una sola pantalla. Más de 500 proyectos de Arduino, ESP32 y Pico listos para montar.
Escanea con tu teléfono
Apunta la cámara al código y se abrirá la tienda de apps de tu teléfono.
o ábrela en la tienda

