Display E-paper a 4 colori con ESP32

In questo tutorial imparerai come usare il W aveshare 3-inch 4-color E-paper display con un ESP32.

Il modulo display E-paper a 4 colori da 3 pollici di Waveshare è un ottimo componente hardware, ma il Demo software offre solo esempi per Arduino, STM32 e Raspberry. Quindi, se vuoi usare il display con un ESP32, sei sfortunato.

Inoltre, l’esempio Arduino mostra solo come visualizzare un’immagine statica predefinita, ma non come creare e mostrare contenuti dinamici, ad esempio un orologio in tempo reale o una stazione meteo.

Sarebbe bello poter usare la libreria GxEPD2, ma a dicembre 2024 non ha un driver per l’E-paper a 4 colori da 3 pollici. Perciò ho implementato una semplice libreria (epd4c) che fa essenzialmente la stessa cosa.

In questo tutorial ti mostro come far funzionare il codice esempio Arduino con un ESP32, come creare contenuti dinamici usando una canvas e come usare la libreria epd4c.

Componenti necessari

Uso l’ESP32 lite come microprocessore perché è economico e ha un’interfaccia per batteria. Poiché i display e-Paper consumano pochissima energia, sono ideali per progetti a batteria, e l’ESP32 lite si adatta perfettamente. Comunque, qualsiasi altro ESP32 funzionerà.

Ovviamente ti servirà anche il modulo display e-Paper a 4 colori da 3 pollici elencato qui sotto. Ho testato il codice con questo, ma dovrebbe funzionare anche con il 2.13-inch 4-color E-Paper o il 2.66-inch 4-color E-Paper. Tuttavia, non supporta display a 3 colori o bianco e nero.

Makerguides is a participant in affiliate advertising programs designed to provide a means for sites to earn advertising fees by linking to Amazon, AliExpress, Elecrow, and other sites. As an Affiliate we may earn from qualifying purchases.

Display E-paper 4 colori da 3″

Il display E-paper usato in questo progetto è un modulo da 3 pollici, con risoluzione 400×168 pixel, 4 colori (bianco, nero, rosso, giallo), tempo di aggiornamento di 12 secondi (supporta solo aggiornamento completo) e un controller integrato con interfaccia SPI.

Front and Back of 3" 4-color e-Paper display module — Fronte e retro del modulo display e-Paper da 3″ a 4 colori

Nota che il modulo ha un piccolo jumper/interruttore sul retro per passare da SPI a 4 fili a SPI a 3 fili. Useremo il default SPI a 4 fili, quindi non devi modificare nulla.

Back of display module with SPI-interface and controller — Retro del modulo display con interfaccia SPI e controller

Il modulo funziona a 3.3V o 5V, ha una corrente di sleep molto bassa di 0.01µA e consuma circa 60mW durante l’aggiornamento. Per maggiori informazioni sui display E-paper in generale, dai un’occhiata al tutorial Interfacing Arduino To An E-ink Display.

Qui sotto trovi il datasheet del display e anche il Waveshare manual:

Datasheet Waveshare 3-inch 4-color E-paper

Collegare il display E-paper a 4 colori con ESP32

In questa sezione collegheremo il display E-paper a un ESP32 lite. L’immagine seguente mostra il cablaggio completo tra ESP32 e display per alimentazione e interfaccia SPI.

Connecting 4-color e-Paper to ESP32 lite via SPI — Collegamento del display e-Paper a 4 colori all’ESP32 lite via SPI

Puoi alimentare il display con 3.3V o 5V, ma l’ESP32 lite ha solo un’uscita a 3.3V. Nota che devi usare i pin hardware SPI del microcontrollore. Nel caso dell’ESP32 lite sono i pin 18 e 23. Qui sotto una tabella con tutte le connessioni per comodità.

Display e-Paper	ESP32 lite
CS/SS	5
SCL/SCK	18
SDA/DIN/MOSI	23
BUSY	4
RES/RST	16
DC	17
VCC	3.3V
GND	G

Far funzionare il codice demo con ESP32

Se scarichi il Demo software per il display E-paper Waveshare, troverai una cartella dentro quel file zip chiamata Arduino/epd3in0g. Al suo interno c’è uno sketch chiamato epd3in0g.ino che produce essenzialmente l’immagine seguente sul display:

Demo image for 3" 4-color e-Paper — Immagine demo per E-paper a 4 colori da 3″

Ecco il pezzo ridotto di quel codice esempio che produce l’immagine. Puoi vedere che crea l’oggetto display epd, lo inizializza, mostra i dati dell’immagine e poi manda il display in sleep:

#include "epd3in0g.h"
#include "imagedata.h"

Epd epd;

void setup() {
  epd.Init();
  epd.Display(IMAGE_DATA);
  epd.Sleep();
}

void loop() { }

Questo codice non funziona su ESP32. Tuttavia puoi farlo funzionare seguendo i passaggi elencati sotto (vedi questo blog post per maggiori dettagli):

Cambia const unsigned char in unsigned char in imagedata.cpp e imagedata.h
Cambia #include <avr/pgmspace> in #include <pgmspace> in imagedata.h
Cambia le definizioni dei pin in epdif.h per usare i pin hardware SPI dell’ESP32
Aggiungi SPI.endTransaction(); alla funzione IfInit() in epdif.cpp

Ecco le definizioni dei pin da usare in epdif.h:

#define RST_PIN         16
#define DC_PIN          17
#define CS_PIN          5
#define BUSY_PIN        4

e qui il codice in epdif.cpp che devi cambiare da

int EpdIf::IfInit(void) {
    ...
    SPI.begin();
    SPI.beginTransaction(SPISettings(2000000, MSBFIRST, SPI_MODE0));
    return 0;
}

a questo codice aggiungendo una riga (endTransaction):

int EpdIf::IfInit(void) {
   ...
    SPI.begin();
    SPI.endTransaction(); // <== ADD THIS LINE
    SPI.beginTransaction(SPISettings(2000000, MSBFIRST, SPI_MODE0));
    return 0;
}

Con queste modifiche il codice esempio dovrebbe funzionare. Tuttavia, è ancora limitato alla visualizzazione di immagini statiche. Nella sezione successiva ti mostro una piccola aggiunta che ti permette di usare la libreria grafica Adafruit_GFX per mostrare dinamicamente contenuti come testo e grafica.

Disegnare sul display E-paper a 4 colori usando la canvas di Adafruit_GFX

La libreria Adafruit_GFX è una libreria grafica che fornisce un set comune di graphics primitives (testo, punti, linee, cerchi, ecc.). Basta installarla tramite il Library Manager come al solito. Dopo l’installazione dovrebbe apparire nel Library Manager così:

Adafruit_GFX in Library Manager — Adafruit_GFX nel Library Manager

La libreria Adafruit_GFX ha il concetto di “canvas” che ti permette di disegnare su un buffer del display (=canvas) in background (senza mostrarlo). Qui sotto un estratto di codice che crea una canvas a 8 bit di profondità con le dimensioni del display E-paper.

#include "Adafruit_GFX.h"

GFXcanvas8 canvas(EPD_WIDTH, EPD_HEIGHT);

void setup() {
  canvas.setRotation(1);
  canvas.fillScreen(WHITE);
  canvas.fillCircle(200, 84, 60, RED);
}

Poi imposta l’orientamento del buffer/display, riempie il buffer con bianco e disegna un cerchio rosso. Poiché il buffer è essenzialmente un’immagine, sarebbe bello poter usare questo codice per mostrare il disegno sul display E-paper:

 epd.Display(canvas.getBuffer());

Tuttavia, l’E-paper a 4 colori usa un’immagine compressa, dove quattro pixel sono compressi in un byte per risparmiare memoria. Poiché ci sono solo quattro colori, ciascuno è rappresentato da 2 bit:

Colore	Bit
nero	`00`
bianco	`01`
giallo	`10`
rosso	`11`

Questo significa che, se abbiamo una sequenza di quattro pixel con i colori nero, bianco, giallo e rosso nell’immagine originale, possiamo comprimerla in un byte (00011011 = 0x1B) così:

Four pixels with 2-bit color codes — Quattro pixel con codici colore a 2 bit

Devi fare questo per tutti i blocchi di 4 pixel nell’immagine originale per creare un’immagine compressa che può essere mostrata sull’E-paper tramite epd.Display(image). La seguente funzione compress() prende il buffer del display della canvas e lo comprime come descritto:

uint8_t* compress(GFXcanvas8& canvas) {
  uint8_t* buf = canvas.getBuffer();
  int n = canvas.width() * canvas.height();
  int ci = 0;
  for (int i = 0; i < n; i += 4) {
    uint8_t com = buf[i];
    com = (com << 2) | buf[i + 1];
    com = (com << 2) | buf[i + 2];
    com = (com << 2) | buf[i + 3];
    buf[ci++] = com;
  }
  return buf;
}

Nota che riutilizza il buffer del display. Quindi non serve memoria aggiuntiva per l’immagine compressa, ma non puoi disegnare sulla canvas dopo la compressione. Devi prima cancellarla.

Con la funzione compress() puoi creare contenuti dinamici e mostrarli sull’E-Paper. Lo schema del codice è questo:

Epd epd;
GFXcanvas8 canvas(EPD_WIDTH, EPD_HEIGHT);

void setup() {
  canvas.setRotation(1);
  canvas.fillScreen(WHITE);
  ...  // more graphics code

  epd.Init();
  epd.Display(compress(canvas));  // display compressed image
  epd.Sleep();
}

Ecco un esempio completo con tutto incluso:

#include "Adafruit_GFX.h"
#include "epd3in0g.h"

Epd epd;
GFXcanvas8 canvas(EPD_WIDTH, EPD_HEIGHT);

uint8_t* compress(GFXcanvas8& canvas) {
  uint8_t* buf = canvas.getBuffer();
  int n = canvas.width() * canvas.height();
  int ci = 0;
  for (int i = 0; i < n; i += 4) {
    uint8_t com = buf[i];
    com = (com << 2) | buf[i + 1];
    com = (com << 2) | buf[i + 2];
    com = (com << 2) | buf[i + 3];
    buf[ci++] = com;
  }
  return buf;
}

void setup() {
  canvas.setRotation(1);
  canvas.fillScreen(red);
  canvas.fillCircle(200, 84, 50, yellow);
  canvas.setCursor(190, 80);
  canvas.setTextColor((black));
  canvas.print("Test");

  epd.Init();
  epd.Display(compress(canvas));
  epd.Sleep();
}

void loop() {
}

Se carichi ed esegui questo codice, vedrai un cerchio giallo su sfondo rosso con la scritta “Test” al centro:

Output example for compress() function — Esempio di output per la funzione `compress()`

Anche se il codice sopra funziona, è un po’ scomodo da usare. Prima di tutto devi integrare i file demo Waveshare (epd3in0g.h, epd3in0g.cpp, epdif.h, epdif.cpp) in ogni nuovo progetto che usa il display E-paper. In secondo luogo, devi anche reimplementare la funzione compress() ogni volta.

Perciò ho creato una piccola libreria chiamata epd4c, che evita tutto questo. Basta installarla e puoi usarla indipendentemente dal codice demo. Nella prossima sezione ti mostro come funziona.

Disegnare sul display E-paper a 4 colori usando la libreria epd4c

Per installare la epd4c Library vai al epd4c_arduino_lib github repo e clicca sul pulsante verde “Code“. Poi clicca su “Download Zip” come mostrato qui sotto:

Download EPD4c Library library — Scarica la libreria EPD4c

Poi vai su “Sketch" -> "Include Library" -> "Add .Zip Library..” e seleziona il file “epd4c_arduino_lib-main.zip” che hai appena scaricato:

Adding TOF10120 library to sketch — Aggiunta della libreria EPD4c allo sketch

Con la libreria epd4c (e la libreria Adafruit_GFX), scrivere testo e disegnare sul display E-paper a 4 colori diventa molto più semplice.

Esempio di codice

Ecco un esempio di codice. Disegna una serie di cerchi colorati insieme a un testo centrato sullo schermo. Come vedi non serve più una canvas separata e non devi usare nessuno dei codici demo Waveshare.

#include "epd4c.h"

#define RST_PIN 16
#define DC_PIN 17
#define CS_PIN 5
#define BUSY_PIN 4

#define EPD_WIDTH 168
#define EPD_HEIGHT 400

Epd4c epd(EPD_WIDTH, EPD_HEIGHT, RST_PIN, DC_PIN, CS_PIN, BUSY_PIN);

void setup() {
  epd.init();
  epd.setRotation(1);
  epd.fillScreen(WHITE);

  epd.fillCircle(200, 84, 60, RED);
  epd.fillCircle(200, 84, 50, YELLOW);
  epd.fillCircle(200, 84, 40, BLACK);
  epd.fillCircle(200, 84, 30, WHITE);

  epd.setCursor(190, 80);
  epd.setTextColor((BLACK));
  epd.print("Test");

  epd.display();
  epd.sleep();
}

void loop() {}

Analizziamo il codice per capire meglio.

Inclusione libreria

Iniziamo includendo la libreria epd4c per controllare il display E-paper, che è un’estensione di una libreria Adafruit_GFX canvas, e quindi supporta tutte le graphics primitives della libreria Adafruit_GFX.

#include "epd4c.h"

Definizione pin

Poi definiamo i pin usati per collegare il display E-paper all’ESP32. Nota che i pin SPI non possono essere definiti manualmente. Devi usare e collegarti ai pin hardware SPI di default del tuo microcontrollore.

#define RST_PIN 16
#define DC_PIN 17
#define CS_PIN 5
#define BUSY_PIN 4

Dimensioni display

Definiamo anche larghezza e altezza del display E-paper. Come detto, il codice dovrebbe funzionare anche con altri display E-paper a 4 colori con dimensioni diverse, ma non l’ho testato.

#define EPD_WIDTH 168
#define EPD_HEIGHT 400

Creazione oggetto display

Qui creiamo un’istanza della classe Epd4c, passando le dimensioni del display e le definizioni dei pin come parametri. Questo oggetto controllerà il display per tutto il programma.

Epd4c epd(EPD_WIDTH, EPD_HEIGHT, RST_PIN, DC_PIN, CS_PIN, BUSY_PIN);

Funzione setup

Nella funzione setup() inizializziamo il display E-paper e configuriamo le sue impostazioni. Qui impostiamo la rotazione del display, riempiamo lo schermo di bianco e disegniamo diversi cerchi sovrapposti di colori e dimensioni diverse.

void setup() {
  epd.init();
  epd.setRotation(1);
  epd.fillScreen(WHITE);

  epd.fillCircle(200, 84, 60, RED);
  epd.fillCircle(200, 84, 50, YELLOW);
  epd.fillCircle(200, 84, 40, BLACK);
  epd.fillCircle(200, 84, 30, WHITE);

  epd.setCursor(190, 80);
  epd.setTextColor((BLACK));
  epd.print("Test");

  epd.display();
  epd.sleep();
}

L’output sul display E-paper sarà il seguente

Output on 3" 4-color E-paper Display — Output su display E-paper a 4 colori da 3″

dove

epd.init(); inizializza il display.
epd.setRotation(1); imposta l’orientamento del display.
epd.fillScreen(WHITE); riempie tutto lo schermo di bianco.
Le funzioni fillCircle() disegnano cerchi di raggi e colori diversi alle coordinate specificate (200, 84).
epd.setCursor(190, 80); imposta la posizione del testo da stampare.
epd.setTextColor((BLACK)); imposta il colore del testo a nero.
epd.print("Test"); stampa il testo “Test” sul display.
epd.display(); aggiorna il display con la grafica disegnata
epd.sleep(); mette il display in modalità sleep per risparmiare energia.

Funzione loop

La funzione loop() è vuota in questo esempio, quindi una volta completato il setup il programma non eseguirà altre azioni. Il display rimarrà in modalità sleep e continuerà a mostrare l’immagine, anche se l’ESP32 è spento.

void loop() {}

Se vuoi aggiornare continuamente il contenuto, ad esempio per mostrare un orologio in tempo reale, devi mettere il codice grafico nella funzione loop. Vedi i tutorial Digital Clock on e-Paper Display o Weather Station on e-Paper Display per esempi.

E questo è tutto!

Conclusioni

In questo tutorial hai imparato a controllare il display E-paper a 4 colori da 3 pollici di Waveshare con un ESP32.

Ti ho mostrato come modificare il codice demo Arduino per farlo funzionare con un ESP32. Abbiamo anche usato la libreria Adafruit_GFX canvas per creare contenuti dinamici per il display E-paper. Infine, ti ho presentato la libreria epd4c.

La libreria epd4c fa essenzialmente la stessa cosa della libreria GxEPD2, ma purtroppo quest’ultima attualmente non supporta il display E-paper a 4 colori da 3 pollici di Waveshare. Avrei preferito usare quella. Avrei potuto estendere la libreria GxEPD2 ma ero troppo pigro e ho semplicemente ripulito ed esteso il codice demo Waveshare per creare la libreria epd4c.

Se hai domande, sentiti libero di lasciarle nella sezione commenti.

Buon divertimento con il tinkering ; )

Stefan Maetschke