© 2025

TFT_eSPI  Graphics Library for Arduino Processors

TFT_eSPI  Graphics Library for Arduino Processors

La biblioteca TFT_eSPI

es una biblioteca popular para controladores de pantallas TFT (Thin-Film Transistor) y pantallas táctiles en el entorno de desarrollo Arduino. Fue creada y es mantenida por Bodmer. Está diseñada para trabajar con pantallas que utilizan controladores SPI (Serial Peripheral Interface), lo que permite la comunicación rápida y eficiente entre un microcontrolador y la pantalla.

Compatible con una amplia gama de controladores de pantalla TFT

Aquí abajo podemos ver la siguiente lista de controladores de pantalla soportadas por Library

Aparte Soporta microcontroladores populares como ESP8266, ESP32, STM32, y algunos AVR (Arduino UNO, Mega).

ILI9341_DRIVER
ILI9341_2_DRIVER
ST7735_DRIVER
ILI9163_DRIVER
S6D02A1_DRIVER
RPI_ILI9486_DRIVER
HX8357D_DRIVER
ILI9481_DRIVER
ILI9486_DRIVER
ILI9488_DRIVER
ST7789_DRIVER
ST7789_2_DRIVER
R61581_DRIVER
RM68140_DRIVER
ST7796_DRIVER
SSD1351_DRIVER
SSD1963_480_DRIVER
SSD1963_800_DRIVER
SSD1963_800ALT_DRIVER
ILI9225_DRIVER
GC9A01_DRIVER

Puntos a destacar

  1. Optimización:
    • Altamente optimizada para funcionar con ESP8266 y ESP32, aprovechando las características específicas de estos microcontroladores para mejorar el rendimiento gráfico.
    • Uso eficiente de memoria y recursos del sistema.
  2. Funciones gráficas avanzadas:
    • Dibujar primitivas gráficas como líneas, rectángulos, círculos y triángulos.
    • Mostrar texto con diferentes fuentes y tamaños.
    • Cargar y mostrar imágenes en varios formatos como BMP y JPEG.
    • Soporte para gráficos de 16 bits por color (RGB565).
  3. Interfaz táctil:
    • Soporta pantallas táctiles resistivas y capacitivas.
    • Funciones para detectar toques, obtener coordenadas de toque, y gestionar eventos táctiles.
  4. Configuración flexible:
    • Archivos de configuración personalizados (User_Setup.h) para definir los parámetros de hardware específicos de cada pantalla y microcontrolador.
    • Posibilidad de ajustar la frecuencia del bus SPI para optimizar la velocidad de comunicación.

Instalación

Para instalar TFT_eSPI, sigue estos pasos:

  1. Usando el Library Manager de Arduino:
    • Abre el IDE de Arduino.
    • Ve al menú Sketch > Include Library > Manage Libraries....
    • Busca TFT_eSPI en la barra de búsqueda.
    • Haz clic en Install para instalar la biblioteca.
  2. Manual:
    • Descarga la biblioteca desde su repositorio en GitHub.
    • Extrae el contenido en la carpeta libraries dentro de tu directorio de Arduino.

Estructura y Componentes de TFT_eSPI

La biblioteca TFT_eSPI está organizada en varios archivos, pero los más importantes para la configuración y uso son:

  1. User_Setup.h: Archivo de configuración donde defines los parámetros específicos de la pantalla y microcontrolador que estás usando.
  2. TFT_eSPI.h y TFT_eSPI.cpp: Contienen la implementación de las funciones de la biblioteca.

Configuración de User_Setup.h

Este archivo es crucial ya que en él se definen los pines utilizados para la conexión, el tipo de controlador de la pantalla, la frecuencia del bus SPI y otras configuraciones específicas.

Abrimos el archivo User_Setup.h

TFT_eSPI  Graphics Library for Arduino Processors

Configuración Controlador TFT

Primero al abrir el archivo User_Setup.h nos debemos dirigir a la línea 44 <= 65. En el archivo de configuración de la biblioteca TFT_eSPI, debes definir un único controlador para tu pantalla TFT. Esto se hace mediante las directivas de preprocesador #define. La biblioteca soporta múltiples controladores de pantalla, pero solo uno debe estar activo a la vez.

  • Identifica tu pantalla: Debes saber cuál es el controlador que utiliza tu pantalla TFT. Esto normalmente está especificado en la documentación de la pantalla o en el sitio web del fabricante.
  • Comenta y descomenta: Una vez que sepas qué controlador utiliza tu pantalla, descomenta la línea correspondiente a ese controlador (quita // al inicio) y asegúrate de que todos los demás estén comentados (con // al inicio de la línea).
/ Display type -  only define if RPi display
//#define RPI_DISPLAY_TYPE // 20MHz maximum SPI

// Only define one driver, the other ones must be commented out
//#define ILI9341_DRIVER       // Generic driver for common displays
//#define ILI9341_2_DRIVER     
//#define ST7735_DRIVER      // Define additional parameters below for this display
//#define ILI9163_DRIVER     // Define additional parameters below for this display
//#define S6D02A1_DRIVER
//#define RPI_ILI9486_DRIVER // 20MHz maximum SPI
//#define HX8357D_DRIVER
//#define ILI9481_DRIVER
//#define ILI9486_DRIVER
//#define ILI9488_DRIVER     // WARNING: Do not connect ILI9488 display SDO to MISO if other devices share the SPI bus (TFT SDO does NOT tristate when CS is high)
#define ST7789_DRIVER      // Full configuration option, define additional parameters below for this display
//#define ST7789_2_DRIVER    // Minimal configuration option, define additional parameters below for this display
//#define R61581_DRIVER
//#define RM68140_DRIVER
//#define ST7796_DRIVER
//#define SSD1351_DRIVER
//#define SSD1963_480_DRIVER
//#define SSD1963_800_DRIVER
//#define SSD1963_800ALT_DRIVER
//#define ILI9225_DRIVER
//#define GC9A01_DRIVER

Colour order

Bajamos un poco mas abajo hasta la línea 76 y 77 donde podemos ver las definiciones TFT_RGB_ORDER en el archivo de configuración de la biblioteca TFT_eSPI determinan el orden en que los colores se organizan en cada píxel de la pantalla TFT. Este orden es importante porque diferentes controladores de pantalla pueden manejar los colores en distintos órdenes. La correcta configuración de este parámetro asegura que los colores se muestren correctamente en la pantalla

//#define TFT_RGB_ORDER TFT_RGB  // Colour order Red-Green-Blue
  #define TFT_RGB_ORDER TFT_BGR  // Colour order Blue-Green-Red
  1. #define TFT_RGB_ORDER TFT_RGB
    • Esta línea de código (comentada en tu ejemplo) define el orden de los colores como Rojo-Verde-Azul (Red-Green-Blue).
    • Es decir, en cada píxel, los datos de color se envían primero el componente Rojo, luego el Verde y finalmente el Azul.
    • Este es un orden común en muchas pantallas, pero no todas.
  2. #define TFT_RGB_ORDER TFT_BGR
    • Esta línea de código (activa en tu ejemplo) define el orden de los colores como Azul-Verde-Rojo (Blue-Green-Red).
    • Es decir, en cada píxel, los datos de color se envían primero el componente Azul, luego el Verde y finalmente el Rojo.
    • Este orden puede ser necesario para algunas pantallas TFT que esperan los datos de color en este orden específico.

¿Por qué es Importante? El orden de los colores es crucial para que la pantalla muestre los colores correctamente. Si el orden no coincide con lo que espera el controlador de la pantalla, los colores pueden aparecer distorsionados. Por ejemplo, un rojo puede aparecer como azul y viceversa, lo que lleva a una imagen incorrecta.

Ejemplo Práctico Supongamos que tienes una pantalla TFT que usa el controlador ST7789 y esta pantalla espera los colores en el orden BGR (Azul-Verde-Rojo). En tu archivo de configuración, debes definir TFT_RGB_ORDER como TFT_BGR para que la biblioteca envíe los datos de color en el orden correcto. Aquí es como se vería tu configuración:

#define TFT_RGB_ORDER TFT_BGR  // Colour order Blue-Green-Red

Si por alguna razón te das cuenta de que los colores no se muestran correctamente, puedes cambiar esta definición a TFT_RGB para ver si el problema se resuelve:

#define TFT_RGB_ORDER TFT_RGB  // Colour order Red-Green-Blue

La definición TFT_RGB_ORDER es esencial para asegurar que los colores se muestran correctamente en la pantalla TFT. Dependiendo del controlador de la pantalla y cómo este maneja los datos de color, deberás ajustar esta configuración a TFT_RGB o TFT_BGR. Siempre revisa la documentación específica de tu pantalla o realiza pruebas para determinar el orden de color correcto.

Configuración Pinout Microcontrolador

La biblioteca TFT_eSPI es una biblioteca ampliamente utilizada para controlar pantallas TFT utilizando la interfaz SPI (Serial Peripheral Interface). Soporta una variedad de placas y microcontroladores, entre ellos están ESP32 – ESP8266 – STM32 – Arduino – RP2040 (Raspberry Pi Pico) lo que la hace muy versátil para diferentes proyectos de hardware. Entre la línes 122 <= 300 podemos configurar libremente microcontrolador que vamos a usar.

En este ejemplo voy hacer una configuración para ESP32 y Explicare paso a paso. 

// For ESP32 Dev board (only tested with ILI9341 display)
// The hardware SPI can be mapped to any pins

//#define TFT_MISO 19
#define TFT_MOSI 23
#define TFT_SCLK 18
#define TFT_CS   5  // Chip select control pin
#define TFT_DC   15  // Data Command control pin
#define TFT_RST   12  // Reset pin (could connect to RST pin)
//#define TFT_RST  -1  // Set TFT_RST to -1 if display RESET is connected to ESP32 board RST
  1. TFT_MISO (Master In Slave Out):
    • Comentado: //#define TFT_MISO 19
    • Este pin se usa para la comunicación SPI desde la pantalla hacia el ESP32. En esta configuración, no está definido, lo cual es aceptable si no necesitas leer datos de la pantalla.
  2. TFT_MOSI (Master Out Slave In):
    • Definido: #define TFT_MOSI 23
    • Este es el pin que envía datos desde el ESP32 hacia la pantalla. Está configurado en el pin GPIO 23.
  3. TFT_SCLK (Serial Clock):
    • Definido: #define TFT_SCLK 18
    • Este pin es la línea de reloj que sincroniza la comunicación SPI. Está configurado en el pin GPIO 18.
  4. TFT_CS (Chip Select):
    • Definido: #define TFT_CS 5
    • Este pin selecciona la pantalla TFT para la comunicación SPI, activando la pantalla cuando se pone en bajo (LOW). Está configurado en el pin GPIO 5.
  5. TFT_DC (Data Command):
    • Definido: #define TFT_DC 15
    • Este pin determina si la información enviada es un comando o datos. Cuando está en bajo (LOW), se envían comandos; cuando está en alto (HIGH), se envían datos. Está configurado en el pin GPIO 15.
  6. TFT_RST (Reset):
    • Definido: #define TFT_RST 12
    • Este pin reinicia la pantalla. Está configurado en el pin GPIO 12. Alternativamente, puede conectarse al pin RST del ESP32.
    • Opción comentada: //#define TFT_RST -1
    • Si se conecta el pin de reinicio de la pantalla al pin de reinicio del ESP32, se puede configurar como -1 para indicar que no se usa un pin separado para el reinicio de la pantalla.
Definición Pin GPIO Función
TFT_MOSI 23 Master Out Slave In (envío de datos)
TFT_SCLK 18 Serial Clock (reloj SPI)
TFT_CS 5 Chip Select (selección de dispositivo)
TFT_DC 15 Data/Command (datos o comandos)
TFT_RST 12 Reset (reinicio de pantalla)

Frecuencia del Reloj SPI (SPI_FREQUENCY)

La frecuencia del reloj SPI afecta la velocidad de renderización de los gráficos en la pantalla TFT. Es importante encontrar un equilibrio entre una frecuencia lo suficientemente alta para una respuesta rápida y una frecuencia que la pantalla pueda manejar sin corrupción en la visualización. Aquí hay algunas consideraciones para diferentes tipos de pantallas:

  • ILI9341: Esta pantalla suele funcionar bien con una frecuencia de hasta 40 MHz, aunque a veces puede fallar a 80 MHz.
  • ST7735: Más de 27 MHz puede provocar problemas como píxeles y líneas espurias.
  • ILI9163: Una frecuencia de 27 MHz suele ser aceptable.

En la configuración proporcionada, la frecuencia del reloj SPI se establece en 27 MHz (#define SPI_FREQUENCY 27000000), que es adecuada para pantallas ILI9163. Las otras opciones están comentadas.

Frecuencia del Reloj SPI para Lectura (SPI_READ_FREQUENCY)

Esta es la frecuencia del reloj SPI reducida opcionalmente para la lectura de datos desde la pantalla TFT. Puede ser útil reducir esta frecuencia para mejorar la estabilidad en la lectura de datos, especialmente en pantallas ILI9341 y similares.

Frecuencia del Reloj SPI para el Panel Táctil (SPI_TOUCH_FREQUENCY)

El panel táctil XPT2046 requiere una frecuencia de reloj SPI más baja de 2.5 MHz (#define SPI_TOUCH_FREQUENCY 2500000).

Puerto SPI Utilizado en ESP32 (USE_HSPI_PORT)

El ESP32 tiene dos puertos SPI disponibles: VSPI y HSPI. Por defecto, se utiliza el puerto VSPI. Si el puerto VSPI está en uso y los pines no están accesibles, puedes descomentar la línea //#define USE_HSPI_PORT para utilizar el puerto HSPI en su lugar.

// Define the SPI clock frequency, this affects the graphics rendering speed. Too
// fast and the TFT driver will not keep up and display corruption appears.
// With an ILI9341 display 40MHz works OK, 80MHz sometimes fails
// With a ST7735 display more than 27MHz may not work (spurious pixels and lines)
// With an ILI9163 display 27 MHz works OK.

// #define SPI_FREQUENCY   1000000
// #define SPI_FREQUENCY   5000000
// #define SPI_FREQUENCY  10000000
// #define SPI_FREQUENCY  20000000
#define SPI_FREQUENCY  27000000
// #define SPI_FREQUENCY  40000000
// #define SPI_FREQUENCY  55000000 // STM32 SPI1 only (SPI2 maximum is 27MHz)
// #define SPI_FREQUENCY  80000000

// Optional reduced SPI frequency for reading TFT
#define SPI_READ_FREQUENCY  20000000

// The XPT2046 requires a lower SPI clock rate of 2.5MHz so we define that here:
#define SPI_TOUCH_FREQUENCY  2500000

// The ESP32 has 2 free SPI ports i.e. VSPI and HSPI, the VSPI is the default.
// If the VSPI port is in use and pins are not accessible (e.g. TTGO T-Beam)
// then uncomment the following line:
//#define USE_HSPI_PORT

Ejemplo Practico

Usando Protoboard del otro proyecto una Pantalla ST7789 veamos un ejemplo Practico usando TFT_eSPI Graphics Library y con la ayuda de ESP32. A continuación tenemos el Sketch del Ejemplo.

Este sketch utiliza la biblioteca TFT_eSPI para controlar una pantalla TFT. En el Setup, inicializamos la pantalla, la orientamos horizontalmente y la llenamos de color negro. Luego, dibujamos un cuadro azul que ocupa toda la pantalla. Después, definimos y centramos el texto «DIYMAKE» en la pantalla.

Más información se puede consultar la documentación en el siguiente enlace. User_Manual_TFT_eSPI

#include <TFT_eSPI.h>  // Incluye la biblioteca

TFT_eSPI tft = TFT_eSPI();  // Crea una instancia de la clase TFT_eSPI

void setup() {
  tft.init();  // Inicializa la pantalla
  tft.setRotation(4);  // Establece la orientación de la pantalla
  tft.fillScreen(TFT_BLACK);  // Llena la pantalla con el color negro

  // Dimensiones de la pantalla
  int width = tft.width();
  int height = tft.height();

  // Dibuja un cuadro rojo que ocupe los laterales de la pantalla
  tft.drawRect(0, 0, width, height, TFT_BLUE);

 String texto = "DIYMAKE";

  // Tamaño del texto
  int textSize = 4;

  // Longitud del texto en píxeles
  int textLength = texto.length() * 6 * textSize; // 6 píxeles por carácter en tamaño 2

  // Coordenadas x e y del punto de inicio del texto para centrarlo
  int x = (width - textLength) / 2;
  int y = height / 2;

  // Establece la posición del cursor y muestra el texto
  tft.setCursor(x, y);
  tft.setTextColor(TFT_WHITE, TFT_BLACK); // Establece color del texto y del fondo
  tft.setTextSize(textSize);  // Establece el tamaño del texto
  tft.println(texto);
 
}

void loop() {
  // El loop está vacío ya que no necesitamos hacer nada continuamente
}
TFT_eSPI  Graphics Library for Arduino Processors
TFT_eSPI  Graphics Library for Arduino Processors

© 2025 ALL RIGHT RESERVED BY DIY MAKE

→ Índice