Guía de Adafruit GFX para ESP32 y Arduino

Este tutorial de Adafruit GFX lleva un proyecto de pantalla para ESP32 o Arduino desde un lienzo vacío de Lopaka hasta un hardware que funciona. Lopaka crea el código de dibujo y los recursos de mapa de bits; tú eliges, cableas e inicializas la biblioteca de pantalla específica de tu hardware.

¿Qué es la biblioteca Adafruit GFX?

Adafruit GFX es la capa gráfica común que usan muchas bibliotecas de pantallas para placas compatibles con Arduino, incluido ESP32. Ofrece métodos para dibujar píxeles, líneas, formas, texto y mapas de bits.

Adafruit GFX no controla una pantalla por sí sola. Funciona junto con una biblioteca específica del hardware, como Adafruit_SSD1306, Adafruit_ST7789 u otro driver para el controlador exacto de tu módulo. El driver se encarga del bus, la inicialización y la transferencia a la pantalla; GFX aporta la API de dibujo común. Consulta la descripción general de la biblioteca de Adafruit para ver ejemplos de esta división.

Antes de empezar

Necesitas:

Un microcontrolador y una pantalla con un driver compatible con Adafruit GFX.
El nombre del controlador, la resolución, la interfaz y la asignación de pines de tu módulo.
Un proyecto de Arduino o ESP32 con el framework de Arduino que pueda compilar y subir el sketch de ejemplo del driver.
Suficiente flash para las fuentes y los recursos de mapa de bits, y suficiente RAM para el framebuffer que use el driver.

Advertencia

Lopaka no detecta tu controlador ni genera el cableado ni la configuración del driver. Pantallas con la misma resolución pueden requerir bibliotecas, constructores, direcciones, pines, llamadas de inicialización u offsets de pantalla distintos.

Paso 0: Instalar y probar el driver de la pantalla

En Arduino IDE, abre Tools → Manage Libraries y busca el driver que usa tu pantalla, como Adafruit SSD1306 o Adafruit ST7735 and ST7789 Library. Las versiones actuales de Arduino IDE instalan junto con el driver las dependencias declaradas, como Adafruit GFX y Adafruit BusIO. Si instalas las bibliotecas a mano, sigue las instrucciones del repositorio de Adafruit GFX y las del repositorio del driver de tu pantalla.

Para las capas de elipse, instala Adafruit GFX 1.12.2 o posterior. La API de 1.12.2 incluye drawEllipse() y fillEllipse(); la 1.12.1 no.

Para ESP32, instala el núcleo de Arduino para ESP32 y selecciona tu placa. Los sketches de ESP32 usan la misma estructura de setup() y loop() que se muestra en esta guía.

Antes de agregar código de Lopaka, compila y sube un ejemplo oficial para tu pantalla exacta. Por ejemplo:

Si el ejemplo del fabricante funciona, la biblioteca, el constructor, el cableado, la dirección, el bus y la inicialización son correctos. Conserva ese ejemplo como sketch base y reemplaza solo sus llamadas de dibujo de demostración por la salida de Lopaka.

Paso 1: Elegir la plataforma de Lopaka

Lopaka tiene dos destinos para Adafruit GFX:

Plataforma de Lopaka	Úsala para	Objeto generado	Salida de color e imágenes
AdafruitGFX Color	Drivers de TFT, OLED o matrices a color	`tft`	Colores RGB565; imágenes de un bit con `drawBitmap()` o RGB565 con `drawRGBBitmap()`
AdafruitGFX Mono	Drivers de OLED o LCD de un bit	`display`	Colores `0` y `1`; imágenes de un bit con `drawBitmap()`

Elige el destino que corresponda al driver, no solo al aspecto del diseño. Un destino monocromático no genera píxeles RGB ni en escala de grises. El destino a color empaqueta los colores en los valores RGB565 de 16 bits que usa Adafruit GFX; consulta el modelo de coordenadas y color de Adafruit.

El nombre del objeto generado forma parte del contrato de integración. Lo más sencillo es llamar tft a la instancia del driver para la salida a color o display para la salida monocromática. Si no, cambia ese identificador en el bloque generado.

Paso 2: Crear el proyecto de Lopaka

Abre lopaka.app y crea un proyecto.
Selecciona AdafruitGFX Color o AdafruitGFX Mono.
Ajusta Tamaño de pantalla al ancho y alto lógicos que usará tu sketch.
En un proyecto a color, elige el color de fondo de la pantalla. En un proyecto monocromático, diseña con la paleta fija en blanco y negro.

Las coordenadas de Adafruit GFX empiezan en (0, 0) en la esquina superior izquierda; X aumenta hacia la derecha e Y hacia abajo. Lopaka usa la misma orientación.

Si el sketch llama a setRotation(), ajusta el lienzo de Lopaka a las dimensiones lógicas rotadas que devuelven width() y height(). Lopaka no genera setRotation() ni rota el hardware por ti. Adafruit documenta las cuatro orientaciones en Rotating the Display.

Paso 3: Diseñar una pantalla

Coloca capas con la barra de herramientas, ordénalas en el panel Capas y edita sus valores en el inspector. Cambia el nombre de las capas importantes antes de exportar: los nombres se convierten en comentarios, identificadores de mapas de bits, nombres de funciones auxiliares de polígonos, encabezados de animaciones y nombres opcionales de variables.

Los generadores actuales de Adafruit GFX producen estos elementos:

Capa de Lopaka	Salida de Adafruit GFX
Línea	`drawLine()`
Rectángulo	`drawRect()` / `fillRect()`
Rectángulo redondeado	`drawRoundRect()` / `fillRoundRect()`
Círculo	`drawCircle()` / `fillCircle()`
Elipse	`drawEllipse()` / `fillEllipse()`
Triángulo	`drawTriangle()` / `fillTriangle()`
Polígono	Una función auxiliar hecha con llamadas `drawLine()` cerradas; solo contorno
Texto	`setTextColor()`, `setTextSize()`, `setFont()`, `setCursor()`, `print()`
Capa de pintura, ícono, imagen	`drawBitmap()` o, en el destino a color, `drawRGBBitmap()`
Animación	Datos de fotogramas de un bit más funciones auxiliares para elegir y dibujar fotogramas

Usa la herramienta Elipse para formas ovaladas en ambos destinos de Adafruit. Pon iguales sus radios horizontal y vertical para dibujar un círculo; las capas de círculo importadas siguen generando drawCircle() o fillCircle().

Comportamiento del texto

La fuente predeterminada de Adafruit es la fuente integrada de ancho fijo de 5×7. Las demás fuentes GFX usan una línea base: la coordenada Y del cursor es la línea sobre la que se apoyan los glifos, no la parte superior de las letras visibles. Lopaka ajusta la coordenada Y generada a la fuente seleccionada, pero aun así conviene comprobar la alineación en la pantalla real.

El destino a color permite un color de fondo para el texto y genera la forma de dos argumentos setTextColor(foreground, background). Adafruit GFX ignora ese argumento de fondo con las fuentes GFX personalizadas; solo funciona con la fuente integrada clásica. Para sobrescribir texto con una fuente personalizada, borra sus límites anteriores con un rectángulo relleno antes de volver a dibujarlo. El destino monocromático de Lopaka no ofrece fondos de texto. Consulta las notas de Adafruit sobre el comportamiento de las fuentes y la línea base.

Paso 4: Configurar el código generado

Abre Ajustes de código. Los destinos de Adafruit GFX tienen dos plantillas de C++ y estas opciones:

Sintaxis elige el framework de destino. Arduino (C++) es la opción predeterminada. ESP-IDF (C++) genera las mismas llamadas de dibujo para un componente de ESP-IDF: los arreglos de imágenes, máscaras y animaciones son arreglos static const uint8_t / uint16_t simples sin PROGMEM, la temporización de las animaciones usa esp_timer_get_time() de esp_timer.h y no se genera setup() / loop(): llama a draw{ScreenName}() y drawAnimations() desde tu propio bucle de tarea. Los encabezados de imágenes y animaciones descargados siguen la plantilla seleccionada.

Ajuste	Qué cambia
Función contenedora	Envuelve la pantalla activa en `void draw{ScreenName}(void)`
Incluir fuentes	Agrega includes de encabezados locales para las fuentes GFX no predeterminadas
Declarar imágenes	Genera los arreglos de mapa de bits de un bit o RGB565 que usan las capas de imagen
Incluir archivos de imagen	Genera `#include "<symbol>.h"` en lugar de los arreglos de mapa de bits en línea
Funciones auxiliares de animación	Agrega includes de encabezados de animación, funciones auxiliares de temporización y un setup/loop inicial
Declarar variables	Genera declaraciones para las propiedades de capa compatibles marcadas como variables
Comentarios, títulos de capas	Agrega comentarios con el nombre de cada capa a la salida de dibujo estática
Borrar/rellenar pantalla	Borra la salida monocromática o rellena la salida a color al principio del bloque de dibujo

Mantén activadas Función contenedora, Incluir fuentes, Declarar imágenes y Borrar/rellenar pantalla para el primer renderizado.

La función contenedora a color empieza con tft.fillScreen(...). La función contenedora monocromática empieza con display.clearDisplay() y termina con display.display(), para que se actualice una pantalla con búfer como la SSD1306. Otros drivers monocromáticos usan un método de refresco distinto; adapta la llamada final al ejemplo oficial de tu driver.

Paso 5: Agregar fuentes, imágenes y animaciones

Fuentes

La fuente integrada Adafruit de 5×7 no necesita encabezado. Lopaka también ofrece fuentes GFX y acepta encabezados de fuentes importados en formato GFX. Puede convertir al formato GFX las fuentes BDF y vectoriales compatibles que importes; consulta la guía de fuentes de Lopaka para ver las formas de importarlas.

Para cada fuente no predeterminada que use la pantalla:

Abre Ajustes de código → Fuentes y descarga el archivo .h.
Coloca el archivo junto a tu sketch o al código fuente generado.
Mantén activada Incluir fuentes para que se conserve el #include "FontName.h" generado.

Los datos de las fuentes ocupan memoria de programa, y las fuentes más grandes ocupan más. La guía de fuentes de Adafruit explica la familia Free incluida y el formato de fuentes GFX.

Imágenes

Usa la herramienta Imagen para importar y recortar una imagen a su tamaño final en píxeles. La salida depende del destino de Lopaka seleccionado y del modo de color de la imagen:

Monocromo: un arreglo PROGMEM de un bit que se dibuja con el color de primer plano seleccionado. Los píxeles no activados son transparentes en la llamada drawBitmap() generada.
RGB en AdafruitGFX Color: un arreglo RGB565 uint16_t PROGMEM que se dibuja con drawRGBBitmap(). Una imagen importada rellena sus píxeles transparentes con el fondo de la pantalla, tanto en el lienzo como en el dispositivo. Para que sigan siendo transparentes, marca Transparencia junto a Superposición en el inspector (aparece cuando la imagen tiene píxeles transparentes): Lopaka genera entonces también un arreglo de un bit image_<Name>_mask y usa la sobrecarga de drawRGBBitmap() con máscara, de modo que esos píxeles conserven lo que ya muestra la pantalla. La máscara ocupa un bit de flash por píxel, y la llamada con máscara dibuja píxel a píxel, lo que es más lento.

Mantén activada Declarar imágenes para incluir los arreglos en el código copiado. RGB565 usa dos bytes por píxel antes de la sobrecarga del compilador y del almacenamiento, así que las imágenes grandes de pantalla completa pueden ocupar mucha flash. La guía de importación de imágenes de Lopaka explica el cambio de tamaño, el recorte, el remuestreo, el tramado y las estimaciones de tamaño. Adafruit documenta las llamadas de mapa de bits subyacentes en Graphics Primitives.

Ajustes de código → Imágenes también muestra cada imagen con su archivo de recurso (image_<Name>_bits.h para datos de un bit, image_<Name>_pixels.h para RGB565), con exactamente los mismos bytes que el arreglo en línea. Activa Incluir archivos de imagen para generar #include "image_<Name>_bits.h" en lugar del arreglo y dejar los píxeles en el encabezado descargado.

Animaciones

Los dos destinos de Adafruit en Lopaka admiten animaciones por fotogramas. Los fotogramas exportados son mapas de bits de un bit, también en el destino a color; el color de capa seleccionado se aplica al dibujar cada fotograma. No es una reproducción de video a todo color.

Descarga todos los archivos .h de la lista Ajustes de código → Animaciones y guárdalos con el sketch. La función auxiliar elige un fotograma con millis() en la sintaxis Arduino (C++) y con esp_timer_get_time() en la sintaxis ESP-IDF (C++).

Advertencia

Con la sintaxis Arduino (C++), la exportación de animaciones agrega los puntos de entrada estándar de Arduino setup() y loop(), que también funcionan en ESP32 con el núcleo de Arduino. El código de pantalla dentro del setup() generado es solo un punto de partida: los drivers de Adafruit usan llamadas de inicialización distintas. Incorpora los includes de animación, la función auxiliar de actualización y las de dibujo al ejemplo del fabricante que funciona, conserva el constructor y la inicialización de ese driver y deja un solo setup() y un solo loop().

Consulta Animaciones para el flujo de trabajo en el editor y los controles de exportación.

Paso 6: Copiar e integrar el código

Crea una pantalla llamada Main, agrega una capa de texto y un rectángulo sin relleno, y haz clic en Copiar en el panel de código. Tu salida exacta usará tus capas, colores, fuentes y coordenadas.

Ejemplo a color con TFT ST7789

Para AdafruitGFX Color, una función típica de Lopaka se ve así:

cpp

void drawMain(void) {
    tft.fillScreen(0x0);
    // Greeting
    tft.setTextColor(0xFFFF);
    tft.setCursor(8, 12);
    tft.print("Hello!");
    // Border
    tft.drawRect(0, 0, 240, 240, 0xFFFF);
}

El siguiente sketch mínimo sigue el ejemplo oficial de Adafruit para la ST7789 de 240×240. Reemplaza las definiciones de pines y los argumentos de init() por los del ejemplo que funciona con tu módulo.

cpp

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

#define TFT_CS 10
#define TFT_DC 8
#define TFT_RST 9

Adafruit_ST7789 tft(TFT_CS, TFT_DC, TFT_RST);

// Paste the complete Lopaka-generated block here.
void drawMain(void) {
    tft.fillScreen(0x0);
    // Greeting
    tft.setTextColor(0xFFFF);
    tft.setCursor(8, 12);
    tft.print("Hello!");
    // Border
    tft.drawRect(0, 0, 240, 240, 0xFFFF);
}

void setup(void) {
    tft.init(240, 240);
    tft.setRotation(0);
    drawMain();
}

void loop(void) {}

Los drivers de TFT a color suelen dibujar directamente en la pantalla, así que este ejemplo no necesita una llamada aparte para mostrar o volcar el contenido. Sigue el ejemplo específico de tu hardware si tu driver usa un búfer de salida.

Ejemplo monocromático con OLED SSD1306

Para AdafruitGFX Mono, la función contenedora incluye las llamadas de borrado y refresco:

cpp

void drawMain(void) {
    display.clearDisplay();
    // Greeting
    display.setTextColor(1);
    display.setCursor(8, 12);
    display.print("Hello!");
    // Border
    display.drawRect(0, 0, 128, 64, 1);
    display.display();
}

Este sketch mínimo sigue el ejemplo oficial de Adafruit para la SSD1306 de 128×64 por I2C. Reemplaza el pin de reset y la dirección I2C por los valores de tu módulo.

cpp

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3D

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// Paste the complete Lopaka-generated block here.
void drawMain(void) {
    display.clearDisplay();
    // Greeting
    display.setTextColor(1);
    display.setCursor(8, 12);
    display.print("Hello!");
    // Border
    display.drawRect(0, 0, 128, 64, 1);
    display.display();
}

void setup(void) {
    if (!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
        for (;;) {}
    }
    drawMain();
}

void loop(void) {}

Paso 7: Agregar datos en tiempo de ejecución y más pantallas

Para que una propiedad compatible sea dinámica, activa su interruptor de variable en el inspector y mantén activada Declarar variables. Lopaka reemplaza el literal por una declaración basada en el nombre de la capa. Actualiza ese valor en tu aplicación antes de volver a llamar a la función de dibujo.

Cada pantalla de Lopaka se exporta por separado, y su título se convierte en el nombre de la función contenedora. Copia la función de cada pantalla en el sketch, combina los includes y recursos duplicados y luego deja que tu aplicación decida qué función llamar:

cpp

enum Screen { MAIN, DETAILS };
Screen currentScreen = MAIN;

void drawCurrentScreen(void) {
    if (currentScreen == MAIN) {
        drawMain();
    } else {
        drawDetails();
    }
}

Qué hace Lopaka y qué haces tú

Lopaka se encarga de	Tú te encargas de
Distribución de píxeles, orden de las capas y llamadas GFX compatibles	Driver de pantalla exacto, constructor, pines, bus y voltaje
Colores RGB565 para el destino a color	Orden de colores, offsets e inicialización específicos del driver
Declaraciones de mapas de bits de un bit y RGB565	Presupuesto de flash y RAM, y cualquier carga desde un sistema de archivos o una tarjeta SD
Selección de fuentes GFX y encabezados locales descargables	Instalar las bibliotecas y mantener los encabezados junto al código fuente
Variables opcionales y funciones auxiliares de animación de un bit	Temporización del refresco, entradas, navegación y estado de la aplicación
Una función de dibujo con nombre por cada pantalla exportada	Llamar a esa función y mostrar correctamente la salida con búfer

Compilar, subir e iterar

Compila antes de subir. Resuelve primero los encabezados que falten, los objetos sin definir y los errores de métodos específicos del driver.
Sube el sketch y compara la pantalla física con el lienzo de Lopaka.
Ajusta la variante del driver, la dirección, la rotación, el tamaño del lienzo o la posición de las capas según haga falta.
Cuando cambie el diseño, reemplaza todo el bloque generado en lugar de mantener a mano llamadas de dibujo sueltas.

Mantén el código de hardware y de la aplicación fuera de la sección generada:

cpp

// BEGIN LOPAKA GENERATED CODE
// Replace this entire block after exporting again.
// END LOPAKA GENERATED CODE

Solución de problemas

La pantalla está en blanco

Restaura y sube el ejemplo oficial del driver. Si también queda en blanco, revisa la alimentación, el voltaje, la tierra, el cableado, el controlador, la dirección, el reset y los pines del bus.
Confirma que el método de inicialización del driver se ejecuta correctamente antes de llamar a la función de Lopaka.
Confirma que el nombre del objeto generado coincide con tu instancia: tft para color o display para monocromo.
Con un driver con búfer como el SSD1306, llama a su método de refresco después de dibujar. La plantilla monocromática de Lopaka genera display.display(); otro driver puede requerir un método distinto.

La imagen aparece desplazada, recortada, reflejada o girada

Ajusta el lienzo de Lopaka a las dimensiones lógicas después de setRotation(). Usa la variante de driver exacta para el panel: la RAM del controlador puede ser mayor que el área visible, y algunos módulos necesitan offsets específicos del driver.

Los colores salen mal

El destino a color genera valores RGB565. Confirma que la biblioteca específica del hardware espera los valores de color estándar de 16 bits de Adafruit GFX y que su inicialización selecciona la variante de panel correcta. Si el rojo y el azul están intercambiados, revisa el orden de colores o la configuración del panel en el driver en lugar de cambiar todos los colores de Lopaka.

Una fuente personalizada no compila o no se alinea

Descarga su archivo .h desde Ajustes de código → Fuentes y colócalo junto al sketch.
Mantén activada Incluir fuentes y confirma que coincidan el nombre del archivo, el nombre incluido y el símbolo GFX.
Recuerda que las fuentes GFX personalizadas usan una línea base e ignoran el argumento de fondo de setTextColor().
Usa menos fuentes o fuentes más pequeñas si el programa supera la capacidad de la flash.

Una imagen no compila o usa demasiada flash

Mantén activada Declarar imágenes si la llamada de dibujo generada hace referencia a un mapa de bits en línea. Recorta y redimensiona la imagen de origen a sus dimensiones finales. Pasa un ícono sencillo de RGB a monocromo cuando baste con un solo color de primer plano.

El código de animación choca con mi sketch

Conserva un solo setup() y un solo loop(). Mantén la inicialización del driver del ejemplo oficial del hardware y luego incorpora el encabezado de animación, la función de actualización y las funciones de dibujo generados. Las animaciones de Lopaka usan fotogramas de un bit; no conservan fotogramas de video RGB.

Preguntas frecuentes

¿Lopaka es compatible con todas las pantallas de Adafruit?

Lopaka genera código para la API de dibujo común de Adafruit GFX, no para una lista de módulos de pantalla. Una pantalla encaja en la práctica cuando tiene un driver compatible con Adafruit GFX para tu entorno de Arduino o ESP32 y ese driver admite los métodos que se generan para tu diseño. Comprueba el módulo exacto con su ejemplo oficial del driver.

¿Lopaka instala o configura Adafruit GFX?

No. Instala el driver específico del hardware y sus dependencias, crea el objeto de pantalla e inicialízalo en tu sketch. Lopaka aporta las llamadas de dibujo y los recursos.

¿El destino a color puede exportar imágenes a todo color?

Sí. Las capas de imagen RGB generan arreglos RGB565 y llamadas drawRGBBitmap(), con una máscara opcional de un bit para los píxeles transparentes en el destino a color (la casilla Transparencia). Las capas de imagen monocromáticas y todos los fotogramas de animación siguen siendo de un bit por píxel. Las plantillas de Adafruit de Lopaka no admiten la exportación de mapas de bits en escala de grises.

Guía de Adafruit GFX para ESP32 y Arduino ​

¿Qué es la biblioteca Adafruit GFX? ​

Antes de empezar ​

Paso 0: Instalar y probar el driver de la pantalla ​

Paso 1: Elegir la plataforma de Lopaka ​

Paso 2: Crear el proyecto de Lopaka ​

Paso 3: Diseñar una pantalla ​

Comportamiento del texto ​

Paso 4: Configurar el código generado ​

Paso 5: Agregar fuentes, imágenes y animaciones ​

Fuentes ​

Imágenes ​

Animaciones ​

Paso 6: Copiar e integrar el código ​

Ejemplo a color con TFT ST7789 ​

Ejemplo monocromático con OLED SSD1306 ​

Paso 7: Agregar datos en tiempo de ejecución y más pantallas ​

Qué hace Lopaka y qué haces tú ​

Compilar, subir e iterar ​

Solución de problemas ​

La pantalla está en blanco ​

La imagen aparece desplazada, recortada, reflejada o girada ​

Los colores salen mal ​

Una fuente personalizada no compila o no se alinea ​

Una imagen no compila o usa demasiada flash ​

El código de animación choca con mi sketch ​

Preguntas frecuentes ​

¿Lopaka es compatible con todas las pantallas de Adafruit? ​

¿Lopaka instala o configura Adafruit GFX? ​

¿El destino a color puede exportar imágenes a todo color? ​

¿Dónde puedo aprender más? ​