Pantalla e-paper Waveshare con ESP32: conexión SPI, GxEPD2 y ejemplos

Publicado originalmente en iot.gripe.

Una pantalla e-paper (tinta electrónica) conserva la imagen sin consumir energía. Solo gasta cuando cambia el contenido. Por eso encaja con un ESP32 a batería: un marcador de estado, un calendario, un panel de sensores o una etiqueta de precio que se actualiza cada pocos minutos.

Esta guía conecta un módulo Waveshare de 2,9" (296×128) por SPI a un ESP32 con la librería GxEPD2. Sirve para casi cualquier tamaño: cambia solo la clase del modelo.

Qué necesitas

• Un ESP32 (cualquier DevKit).
• Una pantalla e-paper de Waveshare (2,13", 2,9", 4,2", 7,5"…). Las de blanco y negro son las más rápidas; las de tres colores (negro, blanco y rojo o amarillo) tardan unos 15 segundos en refrescar.

• Cables Dupont. El módulo suele venir con un cable plano de 8 hilos.

• Pantalla e-paper Waveshare 2,9 pulgadas

Conexión por SPI

El módulo trae ocho señales. Con el SPI por hardware del ESP32 (VSPI):

Los pines de la pantalla funcionan a 3,3 V, así que no necesitas conversor de nivel con el ESP32. DIN es la línea de datos (MOSI) del SPI.

Los pines elegidos evitan los de arranque (0, 2, 12, 15) y los de la flash. Para elegir otros, mira el pinout del ESP32 DevKit.

Instalar la librería

En el gestor de librerías del IDE de Arduino, instala GxEPD2 (de Jean-Marc Zingg). Instala también Adafruit GFX Library, de la que depende para dibujar texto y formas.

Elegir la clase del modelo

Este es el paso donde más gente se equivoca. GxEPD2 tiene una clase distinta por modelo de pantalla, y las versiones de Waveshare (V1, V2, V3…) usan controladores diferentes. Si eliges una incorrecta, la pantalla queda en blanco, con ruido o tarda una eternidad.

Busca tu modelo en el archivo GxEPD2_display_selection.h de los ejemplos de la librería. Para la pantalla de 2,9" blanco y negro V2 se usa:

#include <GxEPD2_BW.h>
#include <Fonts/FreeMonoBold12pt7b.h>

// CS, DC, RST, BUSY
GxEPD2_BW<GxEPD2_290_T94_V2, GxEPD2_290_T94_V2::HEIGHT> display(
    GxEPD2_290_T94_V2(5, 17, 16, 4));

Si tu pantalla es de otro tamaño o versión, cambia GxEPD2_290_T94_V2 por la clase que corresponda a la etiqueta de tu módulo. Para pantallas de tres colores se usa GxEPD2_3C en lugar de GxEPD2_BW.

Primer texto

void setup() {
  SPI.begin(18, -1, 23, 5);        // SCK, MISO (no se usa), MOSI, SS
  display.init(115200);            // velocidad para mensajes de depuración
  display.setRotation(1);          // horizontal
  display.setFont(&FreeMonoBold12pt7b);
  display.setTextColor(GxEPD_BLACK);

  display.setFullWindow();
  display.firstPage();
  do {
    display.fillScreen(GxEPD_WHITE);
    display.setCursor(10, 40);
    display.print("Hola ESP32");
  } while (display.nextPage());

  display.hibernate();             // apaga el controlador de la pantalla
}

void loop() {}

El bloque firstPage() / nextPage() dibuja la pantalla por trozos, para no gastar tanta memoria RAM. Se repite todo el dibujo en cada vuelta del do … while. No pongas aquí lecturas de sensores lentas ni delay(): calcula los valores antes y dibuja después.

Actualización completa y parcial

Las pantallas e-paper tienen dos modos de refresco:

Para actualizar solo una zona:

void mostrarTemperatura(float t) {
  const int x = 10, y = 20, w = 140, h = 40;
  display.setPartialWindow(x, y, w, h);
  display.firstPage();
  do {
    display.fillRect(x, y, w, h, GxEPD_WHITE);
    display.setCursor(x, y + 28);
    display.print(t, 1);
    display.print(" C");
  } while (display.nextPage());
}

Con el modo parcial aparece el ghosting (restos fantasma de la imagen anterior). Haz un refresco completo cada 10 o 20 parciales, o cada hora, para limpiarlo.

Consumo y deep sleep

La pantalla no gasta energía para mantener la imagen. El ESP32 sí, así que lo normal es:

1. Despertar del sueño profundo.
2. Leer los sensores y conectarse si hace falta.
3. Refrescar la pantalla.
4. Llamar a display.hibernate() y volver a dormir.

esp_sleep_enable_timer_wakeup(10ULL * 60 * 1000000);   // 10 minutos
esp_deep_sleep_start();

Más sobre el ahorro en ESP32 con batería y deep sleep. Al despertar, usa display.init(115200, false) (segundo parámetro en false) para que la librería no reinicie la pantalla y conserve la imagen.

Cuánto refrescar

Waveshare recomienda no refrescar más de una vez cada 180 segundos y hacer un refresco completo al menos una vez cada 24 horas. Si vas a guardar la pantalla, déjala en blanco (refresco completo) en lugar de con una imagen fija.

Problemas típicos

Preguntas frecuentes

¿Puedo mostrar una imagen o una foto?

Sí, convirtiendo la imagen a un arreglo de bytes (por ejemplo con la herramienta de conversión de la propia librería) y mostrándola con drawBitmap. Solo blanco y negro, o los colores que soporte tu pantalla.

¿Sirve en 5 V?

No. Las e-paper de Waveshare para ESP32 funcionan a 3,3 V. Con un Arduino UNO (5 V) necesitarías adaptar las señales.

¿Cuánto dura la batería?

Depende del tiempo de sueño del ESP32 y de lo que haga al despertar. Con refrescos cada 10 minutos y deep sleep el consumo medio es muy bajo, y la pantalla no suma casi nada.

¿Y si quiero una pantalla con luz?

Una e-paper no tiene luz propia: se lee con luz ambiente. Para un panel luminoso usa una OLED o una TFT.

• Placa de controlador e-Paper Waveshare para ESP32