En este tutorial aprenderás cómo configurar el TFT_eSPI Library dentro del IDE de Arduino para controlar pantallas TFT. Te mostraré varios ejemplos para diferentes pantallas TFT.

La biblioteca TFT_eSPI simplifica el proceso de interfaz con pantallas TFT. Proporciona una API sencilla para dibujar formas, mostrar texto y manejar la entrada táctil.

La biblioteca está orientada a procesadores de 32 bits y ha sido optimizada para RP2040, STM32, ESP8266 y ESP32. También funciona con placas Arduino, pero será más lenta.

Además, soporta una variedad de controladores de pantallas TFT, incluyendo ILI9341, ST7735, ST7789, ST7796 y más. Para una lista completa y más información, consulta el Readme de la biblioteca TFT_eSPI.

Overview

Instalación de la biblioteca TFT_eSPI

Para install la TFT_eSPI library abre el Library Manager, busca «TFT_eSPI» y presiona «INSTALL». Después de la instalación debería verse así:

TFT_eSPI library in Library Manager — Biblioteca TFT_eSPI en Library Manager

Configuración de la biblioteca TFT_eSPI mediante User_Setup.h

Antes de poder usar la TFT_eSPI Library debes configurarla específicamente para la pantalla TFT en la que quieres dibujar. Esto incluye el controlador IC de la pantalla, los pines de interfaz y propiedades de la pantalla como dimensiones o el orden de los canales RGB.

Estos parámetros de configuración se almacenan en un archivo llamado User_Setup.h, que forma parte de la carpeta de la biblioteca TFT_eSPI. Normalmente, en Windows estará ubicado en una ruta similar a la siguiente

C:\Users\stefa\OneDrive\Documents\Arduino\libraries\TFT_eSPI

La ruta exacta depende de tu nombre de usuario (en mi caso «stefa«) y de tu sistema operativo y si usas OneDrive o no. Tendrás que buscarlo, pero estará donde se almacenan todas tus bibliotecas de Arduino.

Si abres el archivo User_Setup.h verás muchos parámetros que deben configurarse correctamente para que una pantalla TFT específica funcione:

Puedes editar este archivo, pero cualquier cambio afectará a todos tus proyectos de Arduino que usen la biblioteca TFT_eSPI, ya que la biblioteca y User_Setup.h se comparten entre proyectos. Además, instalar una nueva versión de la biblioteca TFT_eSPI sobrescribirá tus cambios en User_Setup.h.

En su lugar, te sugiero crear un archivo llamado tft_setup.h que sea local a un proyecto y afecte solo a ese proyecto. Cómo hacerlo es el tema de la siguiente sección.

Configuración de la biblioteca TFT_eSPI mediante tft_setup.h

Cualquier cambio en User_Setup.h afectará a todos los proyectos. Sin embargo, si el proyecto contiene un archivo llamado tft_setup.h, las configuraciones en User_Setup.h serán ignoradas.

El archivo tft_setup.h contiene esencialmente las mismas configuraciones, User_Setup.h pero solo serán válidas para ese proyecto específico. Esto significa que puedes tener diferentes proyectos con diferentes pantallas, sin tener que cambiar User_Setup.h cada vez que uses una pantalla distinta.

Estructura del proyecto

Aquí tienes un ejemplo de cómo crear la estructura requerida para el proyecto. Primero crea un nuevo proyecto de Arduino y guárdalo como «tft_test«, por ejemplo. Esto creará una carpeta tft_test con un archivo tft_test.ino dentro:

Arduino Project Folder tft_test — Carpeta del proyecto Arduino tft_test

En esta carpeta, crea ahora un archivo llamado «tft_setup.h» – ¡exactamente con este nombre! Tu carpeta de proyecto debería verse así:

Carpeta del proyecto Arduino con `tft_setup.h`

En tu IDE de Arduino ahora deberías ver dos pestañas; tft_test.ino y tft_setup.h en las que puedes hacer clic para editar los archivos.

Arduino IDE with tft_test.ino and tft_setup.h tabs — IDE de Arduino con pestañas `tft_test.ino and tft_setup.h`

Ejemplo de configuración

En el archivo tft_setup.h copias (por ejemplo desde User_Setup.h o desde un tutorial) todas las configuraciones específicas para tu pantalla. A continuación tienes el archivo de configuración para un 1.8″ ST7735 TFT Display, por ejemplo:

// tft_setup.h
#define ST7735_DRIVER
#define ST7735_BLACKTAB
   
#define TFT_WIDTH  128
#define TFT_HEIGHT 160

#define TFT_RGB_ORDER TFT_RGB  

// pins
#define TFT_CS    5   
#define TFT_RST   16  
#define TFT_DC    17   
#define TFT_MOSI  23  // SDA // HW MOSI
#define TFT_SCLK  18  // SCL // HW SCLK
#define TFT_MISO  19  // not used
#define TFT_BL    22   // LED back-light
#define TFT_BACKLIGHT_ON HIGH

// fonts
#define LOAD_GLCD   
#define LOAD_FONT2  
#define LOAD_FONT4  
#define LOAD_FONT6  
#define LOAD_FONT7  
#define LOAD_FONT8  
#define LOAD_GFXFF
#define SMOOTH_FONT 

// SPI
#define SPI_FREQUENCY  27000000
#define SPI_READ_FREQUENCY  20000000
#define SPI_TOUCH_FREQUENCY  2500000

La configuración más importante es el controlador de pantalla (ST7735_DRIVER), las dimensiones de la pantalla (320×240) y los pines a los que está conectada la pantalla.

A veces hay variaciones del controlador que se pueden configurar mediante flags especiales (por ejemplo ST7735_BLACKTAB). De igual forma, el orden de los canales RGB puede variar entre pantallas y también puedes especificarlo (TFT_RGB_ORDER TFT_RGB).

La frecuencia SPI generalmente no varía mucho entre pantallas, pero si ves patrones de ruido u otras distorsiones puedes intentar bajar la SPI_FREQUENCY. Frecuencias más altas harán que la pantalla sea más rápida, y puedes experimentar con eso también.

A continuación tienes un ejemplo de las distorsiones que puedes encontrar si la frecuencia SPI es demasiado alta. El primer texto se mostró con una SPI_FREQUENCY de 27000000 y el segundo con una frecuencia de 40000000. Se pueden ver claramente las distorsiones en el segundo texto.

TFT text output with different SPI frequencies — Salida de texto con diferentes frecuencias SPI

Normalmente no tienes que cambiar la lista de fuentes a cargar, pero si te quedas sin memoria puedes eliminar las fuentes que no uses.

Puedes encontrar muchas configuraciones existentes para varias combinaciones de microprocesadores y controladores de pantalla en la carpeta UserSetups de la biblioteca TFT_eSPI. Para una visión general de todas las configuraciones, echa un vistazo al archivo User_Setup.h.

Encontrar pines SPI hardware

La velocidad con la que la pantalla TFT puede mostrar imágenes depende en gran medida de qué tan rápido se pueden transferir los datos desde el microprocesador a la pantalla. Lo más común es que el microprocesador y la pantalla se comuniquen vía SPI (Serial Peripheral Interface), aunque también existe una interfaz paralela.

Microprocesadores como Arduino, ESP8266 o ESP32 soportan SPI hardware, que es más rápido que el SPI por software. Mira un vídeo comparativo de velocidad here.

Sin embargo, el SPI hardware requiere que conectes la pantalla TFT a los pines correctos. Dependiendo del microprocesador, estos pines varían. Pero puedes encontrarlos fácilmente seleccionando tu placa en el IDE de Arduino y luego ejecutando el código que sigue.

void setup() {
  Serial.begin(115200);
  Serial.print("MOSI: ");
  Serial.println(SDA / MOSI);
  Serial.print("MISO: ");
  Serial.println(MISO);
  Serial.print("SCL / SCLK: ");
  Serial.println(SCK);
  Serial.print("CS / SS: ");
  Serial.println(SS);  
}

void loop() { }

Este código imprime los pines que necesitas para SPI hardware, específicamente MOSI y SCLK. Los pines restantes como TFT_CS, TFT_BL, TFT_DC puedes elegirlos libremente y MISO típicamente no se usa.

Niveles lógicos

Finalmente, una advertencia sobre Logic Levels. Las pantallas TFT típicamente operan con lógica CMOS de 3.3V y puedes conectar las líneas SPI directamente a un microprocesador que también use lógica CMOS de 3.3V, como el ESP32, por ejemplo.

Las placas Arduino, en cambio, operan con lógica TTL de 5V y no debes conectar sus pines GPIO directamente a una pantalla TFT que use lógica CMOS de 3.3V. Necesitarás un divisor de voltaje o mejor un logic level converter.

Algunas pantallas TFT tienen un convertidor de nivel lógico incorporado, pero si no está indicado directamente en la hoja de datos o descripción del producto, no puedes estar seguro. Si la pantalla dice funcionar a 5V puede que tenga o no un convertidor de nivel. Si funciona a 3.3V, probablemente no lo tenga.

Así que, si tu pantalla no funciona correctamente (pantalla en negro, patrones de ruido, parpadeos, …) con un Arduino, puede que necesites un convertidor de nivel lógico.

Ejemplo de conexión para TFT de 1.8″ con controlador ST7735

En esta sección te mostraré un ejemplo de conexión. Vamos a conectar una 1.8″ TFT Display que tiene un controlador ST7735S a un WEMOS Lolin32 lite. Mira el cableado completo en la imagen a continuación:

Connecting TFT ST7735 Display with WEMOS Lolin ESP32 lite — Conexión de pantalla TFT ST7735 con WEMOS Lolin ESP32 lite

Y aquí, para tu comodidad, el cableado nuevamente en forma de tabla:

Pantalla	ESP32
CS / SS	5
RST	16
DC	17
SDA / MOSI	23
SCL / SCLK	18
BKL/BL	22
GND	GND
VCC	3.3V

La pantalla TFT en este ejemplo es una pantalla de 3.3V sin convertidor de nivel lógico. Por lo tanto, debes conectar VCC de la pantalla a 3.3V y no puedes conectarla directamente a un Arduino Uno.

Ejemplo de código para TFT de 1.8″ con controlador ST7735

En esta sección veremos un pequeño ejemplo de código que usa la biblioteca TFT_eSPI. Será útil para probar si la configuración en el archivo tft_setup.h es correcta.

Copia el siguiente código en el archivo tft_test.ino. Este código muestra un cuadrado verde, un círculo rojo, un triángulo azul y el texto «Makerguides».

// tft_test.ino
#include "tft_setup.h"
#include"TFT_eSPI.h"

TFT_eSPI tft = TFT_eSPI();

const int cw = tft.width()/2;
const int ch = tft.height()/2;
const int s = min(cw/3,ch/3);

void setup(void) {  
  tft.init();
  tft.fillScreen(TFT_BLACK);  
  tft.setRotation(1);

  tft.setTextFont(1);
  tft.setTextSize(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextDatum(CC_DATUM);
  tft.drawString("Makerguides", ch, cw+s);

  tft.fillCircle(ch, cw/2+s/2, s/2, TFT_RED);
  tft.fillRect(1.5*ch-s, cw/2, s, s, TFT_GREEN);
  tft.fillTriangle(ch/2, cw/2, ch/2+s, cw/2, ch/2, cw/2+s, TFT_BLUE);
}

void loop() { }

Ten en cuenta que tft_setup.h está incluido al inicio del programa. El código es fácil de entender. Creamos un objeto TFT_eSPI y constantes para el centro (cw, ch) y el tamaño s de los objetos a dibujar.

En la función setup inicializamos la pantalla TFT, llenamos la pantalla de negro y la rotamos a modo retrato.

Luego, configuramos la fuente, su tamaño, color y alineación, y escribimos el texto «Makerguides» en la pantalla. En las siguientes tres líneas dibujamos el círculo rojo, el cuadrado verde y el triángulo azul. La salida en tu pantalla TFT debería verse similar a esto:

Output of test code on TFT — Salida del código de prueba en TFT

Si no es así, algo está mal con la configuración en tft_test.ino o con el cableado de la pantalla TFT.

Ejemplo de conexión para pantalla TFT ST7789 de 1.3″

En este siguiente ejemplo, te muestro cómo conectar la común 1.3″ ST7789 TFT Display a un WEMOS Lolin32 lite (ESP32):

Connecting TFT ST7789 Display with WEMOS Lolin ESP32 lite — Conexión de pantalla TFT ST7789 con WEMOS Lolin ESP32 lite

Y aquí están las conexiones requeridas nuevamente en forma de tabla. Ten en cuenta que este módulo de pantalla no tiene chip select (CS) y por lo tanto no se necesita pin para ello.

Pantalla	ESP32
RST	16
DC	17
SDA / MOSI	23
SCL / SCLK	18
BKL/BL	22
GND	GND
VCC	3.3V

Asegúrate de conectar VCC de la pantalla a 3.3V. No es compatible con 5V y no puedes usarla directamente con un Arduino UNO. También deberías usar los pines hardware SPI. Dependiendo del microcontrolador, los pines hardware SPI variarán.

Ejemplo de código para pantalla TFT ST7789 de 1.3″

Aquí está la configuración y el código para la 1.3″ ST7789 TFT Display. Copia la siguiente configuración en el archivo tft_setup.h.

// 1.3" TFT Display (GMT130 V.10), 
// no CS pin
// 240x240, ST7789
// tft_setup.h
#define ST7789_DRIVER

#define TFT_WIDTH  240
#define TFT_HEIGHT 240

#define TFT_RGB_ORDER TFT_BGR

#define TFT_CS    -1   
#define TFT_RST   16  
#define TFT_DC    17  
#define TFT_MOSI  23  // SDA // HW MOSI
#define TFT_SCLK  18  // SCL // HW SCL
#define TFT_MISO  19  // not used
#define TFT_BL    22  // LED back-light
#define TFT_BACKLIGHT_ON HIGH


#define LOAD_GLCD   
#define LOAD_FONT2  
#define LOAD_FONT4  
#define LOAD_FONT6  
#define LOAD_FONT7  
#define LOAD_FONT8  
#define LOAD_GFXFF
#define SMOOTH_FONT 

#define SPI_FREQUENCY  27000000
#define SPI_READ_FREQUENCY  20000000
#define SPI_TOUCH_FREQUENCY  2500000

Y el código de prueba para el sketch va en el archivo tft_test.ino:

// tft_test.ino
#include "tft_setup.h"
#include"TFT_eSPI.h"

TFT_eSPI tft = TFT_eSPI();

const int cw = tft.width()/2;
const int ch = tft.height()/2;
const int s = min(cw/4,ch/4);

void setup(void) {  
  tft.init();
  tft.fillScreen(TFT_BLACK);  
  tft.setRotation(1);

  tft.setTextFont(1);
  tft.setTextSize(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextDatum(CC_DATUM);
  tft.drawString("Makerguides", ch, cw+s);

  tft.fillCircle(ch, cw/2+s/2, s/2, TFT_RED);
  tft.fillRect(1.5*ch-s, cw/2, s, s, TFT_GREEN);
  tft.fillTriangle(ch/2, cw/2, ch/2+s, cw/2, ch/2, cw/2+s, TFT_BLUE);
}

void loop() { }

Deberías ver la siguiente salida en tu pantalla:

Ejemplo de conexión para pantalla táctil TFT ILI9341 de 2.8″

En este último ejemplo, te muestro cómo conectar una 2.8″ TFT ILI9341 Touch Display a un WEMOS Lolin32 lite (ESP32):

Connecting the TFT ILI9341 Touch Display to ESP32 — Conexión de pantalla táctil TFT ILI9341 a ESP32

Hay bastantes conexiones que hacer y la siguiente tabla debería ayudar. Ten en cuenta que las líneas SDI(MOSI) y SCK de la interfaz SPI se comparten entre el controlador táctil y el controlador de la pantalla TFT:

ESP32	TFT	Táctil
5	CS	–
4	–	T_CS
17	RESET	–
16	DC	–
23	SDI(MOSI)	T_DIN
18	SCK	T_CLK
19	–	T_DO
22	LED	–

Podrías conectar el pin 19 del ESP32 a SDO(MISO) también, pero no lo necesitamos y se han reportado casos en que esto causa problemas. Yo no conecté el pin 19 a SDO(MISO) y la pantalla funcionó bien.

Ejemplo de código para pantalla táctil TFT ILI9341 de 2.8″

Aquí está la configuración y el código para la 2.8″ TFT ILI9341 Touch Display. Copia la siguiente configuración en el archivo tft_setup.h.

// tft_setup.h
// 2.8" TFT Touch Display
// 240x 320, Driver: ILI9341 

#define ILI9341_DRIVER      
//#define ILI9341_2_DRIVER  

#define TFT_WIDTH  240
#define TFT_HEIGHT 320
#define TFT_RGB_ORDER TFT_BGR  

// WEMOLS Lolin32 lite
#define TFT_CS    5   
#define TFT_RST   17  
#define TFT_DC    16   
#define TFT_MOSI  23  // SDA // HW MOSI
#define TFT_SCLK  18  // SCL // HW SCLK
#define TFT_MISO  19  // HW MISO
#define TFT_BL    22  // LED back-light
#define TFT_BACKLIGHT_ON HIGH

#define TOUCH_CS 4 
#define TOUCH_CLK TFT_SCLK
#define TOUCH_DIN TFT_MOSI
#define TOUCH_DO TFT_MISO

#define LOAD_GLCD   
#define LOAD_FONT2  
#define LOAD_FONT4  
#define LOAD_FONT6  
#define LOAD_FONT7  
#define LOAD_FONT8  
#define LOAD_GFXFF
#define SMOOTH_FONT 

#define SPI_FREQUENCY  27000000
#define SPI_READ_FREQUENCY  20000000
#define SPI_TOUCH_FREQUENCY  2500000

Y aquí tienes un código de prueba para la pantalla que va en el archivo tft_test.ino:

// tft_test.ino
#include "tft_setup.h"
#include "TFT_eSPI.h"

TFT_eSPI tft = TFT_eSPI();
uint16_t cal[5] = { 0, 0, 0, 0, 0 };

void calibrate_touch() {
  if (!cal[1]) {
    tft.fillScreen(TFT_BLACK);
    tft.calibrateTouch(cal, TFT_YELLOW, TFT_BLACK, 20);
    Serial.printf("cal[5] = {%d, %d, %d, %d, %d};\n",
                  cal[0], cal[1], cal[2], cal[3], cal[4]);
  }
}

void setup(void) {
  Serial.begin(115200);

  tft.init();
  tft.setRotation(1);
  calibrate_touch();
  tft.setTouch(cal);

  tft.fillScreen(TFT_BLACK);
  tft.setTextFont(1);
  tft.setTextSize(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextDatum(CC_DATUM);
  tft.drawString("Makerguides", TFT_HEIGHT / 2, TFT_WIDTH / 2);
}

void loop() {
  uint16_t x, y;
  if (tft.getTouch(&x, &y)) {
    Serial.printf("%d %d\n", x, y);
    tft.fillCircle(x, y, 2, TFT_YELLOW);
  }
}

Este código te permite calibrar la pantalla táctil y detectar toques en la pantalla:

Touch input on TFT ILI9341 Touch Display — Entrada táctil en pantalla TFT ILI9341

Para información más detallada, consulta el tutorial Interface TFT ILI9341 Touch Display with ESP32.

Conclusiones

En este tutorial has aprendido cómo configurar el TFT_eSPI Library dentro del IDE de Arduino para controlar pantallas TFT.

La TFT_eSPI Library es muy versátil y soporta muchas pantallas TFT diferentes. Sin embargo, encontrar la configuración correcta para una pantalla TFT nueva puede no ser fácil.

Empieza por identificar el controlador IC que usa la pantalla. Los controladores comunes son ST7735, ST7789, ST7796 y el ILI9341. Busca estos nombres en la descripción del producto, la hoja de datos y en el PCB de la pantalla.

Luego, averigua la resolución (ancho, alto) de la pantalla en píxeles, por ejemplo 128×160. De nuevo, deberías poder encontrar esta información en la descripción del producto, la hoja de datos o en el PCB de la pantalla.

Después conecta la pantalla a tu microcontrolador. Si hay un pin de retroiluminación, asegúrate de que esté conectado a 3.3V (o 5V, según la pantalla). Si no sabes si la pantalla es compatible con 5V, no uses un Arduino sino un ESP32 con 3.3V. De lo contrario, podrías dañar el controlador IC de la pantalla.

Finalmente, sube el código de prueba y observa qué sucede. Hay algunos escenarios comunes:

Pantalla en negro: Revisa el pin de retroiluminación y configura #define TFT_BACKLIGHT_ON HIGH
Colores incorrectos: Prueba #define TFT_RGB_ORDER TFT_RGB o TFT_BGR
Blanco y negro invertidos: #define TFT_INVERSION_ON or TFT_INVERSION_OFF
El texto del código de prueba no está centrado o está cortado: Las dimensiones de la pantalla son incorrectas.
Configura TFT_HEIGHT y TFT_WIDTH correctamente.
Patrones de ruido, distorsiones o parpadeos: SPI_FREQUENCY es demasiado alta
Pines faltantes: Si no hay pin para reset (RST), chip select (CS) o retroiluminación (BL) en la pantalla, entonces configura las constantes correspondientes a -1, por ejemplo #define TFT_RST -1

Si tienes algún comentario, no dudes en dejarlo en la sección de comentarios.

¡Feliz bricolaje ; )

Stefan Maetschke