In questo tutorial imparerai come configurare la TFT_eSPI Library all’interno dell’IDE Arduino per controllare display TFT. Ti mostrerò diversi esempi per vari display TFT.

La libreria TFT_eSPI semplifica il processo di interfacciamento con i display TFT. Fornisce un’API semplice per disegnare forme, visualizzare testo e gestire l’input touch.

La libreria è pensata per processori a 32 bit ed è stata ottimizzata per prestazioni su RP2040, STM32, ESP8266 e ESP32. Funziona anche con schede Arduino, ma sarà più lenta.

Inoltre, supporta una varietà di controller per display TFT, inclusi ILI9341, ST7735, ST7789, ST7796 e altri. Per un elenco completo e maggiori informazioni consulta la Readme della libreria TFT_eSPI.

Overview

Installazione della libreria TFT_eSPI

Per install la TFT_eSPI library apri il Library Manager, cerca “TFT_eSPI” e premi “INSTALL”. Dopo l’installazione dovrebbe apparire così:

TFT_eSPI library in Library Manager — Libreria TFT_eSPI nel Library Manager

Configurazione della libreria TFT_eSPI tramite User_Setup.h

Prima di poter usare la TFT_eSPI Library devi configurarla specificamente per il display TFT su cui vuoi disegnare. Questo include il driver IC del display, i pin di interfaccia e le proprietà del display come dimensioni o ordine dei canali RGB.

Questi parametri di configurazione sono memorizzati in un file chiamato User_Setup.h, che fa parte della cartella della libreria TFT_eSPI. Tipicamente, su Windows si trova in un percorso simile al seguente

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

Il percorso esatto dipende dal tuo nome utente (nel mio caso “stefa“) e dal sistema operativo e se usi OneDrive o meno. Dovrai cercarlo, ma sarà nella cartella dove sono archiviate tutte le tue librerie Arduino.

Se apri il file User_Setup.h vedrai molti parametri che devono essere impostati correttamente per far funzionare un display TFT specifico:

Puoi modificare questo file, ma ogni cambiamento influenzerà tutti i tuoi progetti Arduino che usano la libreria TFT_eSPI, dato che la libreria e User_Setup.h sono condivisi tra i progetti. Inoltre, installare una nuova versione della libreria TFT_eSPI sovrascriverà le tue modifiche a User_Setup.h.

Invece, ti suggerisco di creare un file chiamato tft_setup.h che sia locale a un progetto e influenzi solo quel progetto. Come fare, è l’argomento della sezione seguente.

Configurazione della libreria TFT_eSPI tramite tft_setup.h

Qualsiasi modifica a User_Setup.h influenzerà tutti i progetti. Tuttavia, se il progetto contiene un file chiamato tft_setup.h le impostazioni in User_Setup.h saranno ignorate.

Il file tft_setup.h contiene essenzialmente le stesse impostazioni di User_Setup.h ma saranno valide solo per il progetto specifico. Questo significa che puoi avere progetti diversi con display diversi, senza dover cambiare User_Setup.h ogni volta che usi un display differente.

Struttura del progetto

Ecco un esempio di come creare la struttura richiesta per il progetto. Prima crea un nuovo progetto Arduino e salvalo come “tft_test“, per esempio. Questo creerà una cartella tft_test con un file tft_test.ino al suo interno:

Arduino Project Folder tft_test — Cartella progetto Arduino tft_test

In questa cartella, crea ora un file chiamato “tft_setup.h” – esattamente con questo nome! La tua cartella progetto dovrebbe quindi apparire così:

Cartella progetto Arduino con `tft_setup.h`

Nell’IDE Arduino ora dovresti vedere due schede; tft_test.ino e tft_setup.h su cui puoi cliccare per modificare i file.

Arduino IDE with tft_test.ino and tft_setup.h tabs — IDE Arduino con schede `tft_test.ino and tft_setup.h`

Esempio di impostazioni

Nel file tft_setup.h copi (ad esempio da User_Setup.h o da un tutorial) tutte le impostazioni specifiche per il tuo display. Qui sotto c’è il file di impostazioni per un 1.8″ ST7735 TFT Display, per esempio:

// 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

L’impostazione più importante è il driver del display (ST7735_DRIVER), le dimensioni del display (320×240) e i pin a cui il display è collegato.

A volte ci sono variazioni del driver che possono essere impostate tramite flag speciali (ad esempio ST7735_BLACKTAB). Allo stesso modo, l’ordine dei canali RGB può variare tra i display e puoi specificarlo (TFT_RGB_ORDER TFT_RGB).

Le impostazioni della frequenza SPI di solito non differiscono molto tra i display, ma se noti disturbi o altre distorsioni puoi provare a ridurre la SPI_FREQUENCY. Frequenze più alte rendono il display più veloce, e puoi sperimentare anche questo.

Qui sotto un esempio delle distorsioni che potresti incontrare se la frequenza SPI è troppo alta. Il primo testo è stato visualizzato con una SPI_FREQUENCY di 27000000 e il secondo con una frequenza di 40000000. Si vedono chiaramente le distorsioni nel secondo testo.

TFT text output with different SPI frequencies — Output testo con frequenze SPI diverse

Di solito non devi cambiare la lista di font da caricare, ma se la memoria scarseggia puoi rimuovere i font che non usi.

Puoi trovare molte impostazioni esistenti per varie combinazioni di microprocessori e driver display nella cartella UserSetups della libreria TFT_eSPI. Per una panoramica di tutte le impostazioni dai un’occhiata al file User_Setup.h.

Individuare i pin Hardware SPI

La velocità con cui lo schermo TFT può visualizzare dipende in gran parte da quanto velocemente i dati possono essere trasferiti dal microprocessore al display. Più comunemente il microprocessore e il display comunicano via SPI (Serial Peripheral Interface), anche se esiste un’interfaccia parallela.

Microprocessori come Arduino, ESP8266 o ESP32 supportano Hardware SPI, che è più veloce del Software SPI. Guarda un video di confronto velocità here.

Tuttavia, l’Hardware SPI richiede che il display TFT sia collegato ai pin corretti. A seconda del microprocessore questi pin variano. Puoi però trovarli facilmente selezionando la tua scheda nell’IDE Arduino e poi eseguendo il codice qui sotto.

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() { }

Il codice stampa i pin necessari per l’hardware SPI – specificamente MOSI e SCLK. Gli altri pin come TFT_CS, TFT_BL, TFT_DC puoi sceglierli liberamente e MISO di solito non si usa.

Livelli logici

Infine un avviso sui Logic Levels. I display TFT tipicamente funzionano con logica CMOS a 3.3V e puoi collegare le linee SPI direttamente a un microprocessore che usa anch’esso logica CMOS a 3.3V come l’ESP32, per esempio.

Le schede Arduino, invece, funzionano con logica TTL a 5V e non devi collegare direttamente i loro pin GPIO a un display TFT che usa logica CMOS a 3.3V. Ti servirà un partitore di tensione o meglio un logic level converter.

Alcuni display TFT hanno un convertitore di livello logico integrato, ma se non è indicato chiaramente nel datasheet o nella descrizione del prodotto, non puoi esserne sicuro. Se il display è dichiarato per 5V potrebbe averlo o meno. Se funziona a 3.3V, molto probabilmente non ce l’ha.

Quindi, se il tuo display non funziona correttamente (schermo nero, disturbi, sfarfallio, …) con un Arduino, potresti aver bisogno di un convertitore di livello logico.

Esempio di cablaggio per TFT 1.8″ con driver ST7735

In questa sezione ti mostro un esempio di cablaggio. Collegheremo un 1.8″ TFT Display con un driver ST7735S a un WEMOS Lolin32 lite. Vedi il cablaggio completo nell’immagine qui sotto:

Connecting TFT ST7735 Display with WEMOS Lolin ESP32 lite — Collegamento display TFT ST7735 con WEMOS Lolin ESP32 lite

E qui per comodità il cablaggio di nuovo in tabella:

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

Il display TFT in questo esempio è un display a 3.3V senza convertitore di livello logico. Devi quindi collegare VCC del display a 3.3V e non puoi collegarlo direttamente a un Arduino Uno.

Esempio di codice per TFT 1.8″ con driver ST7735

In questa sezione vediamo un piccolo esempio di codice che usa la libreria TFT_eSPI. Sarà utile per testare se le impostazioni nel file tft_setup.h sono corrette.

Copia il seguente codice nel file tft_test.ino. Questo codice visualizza un quadrato verde, un cerchio rosso, un triangolo blu e il testo “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() { }

Nota che tft_setup.h è incluso in cima al programma. Il codice è facile da capire. Creiamo un oggetto TFT_eSPI e costanti per il centro (cw, ch) e la dimensione s degli oggetti da disegnare.

Nella funzione setup inizializziamo lo schermo TFT, lo riempiamo di nero e lo ruotiamo in modalità verticale.

Poi impostiamo il font, la sua dimensione, colore e allineamento, e scriviamo il testo “Makerguides” sullo schermo. Nelle tre righe successive disegniamo il cerchio rosso, il quadrato verde e il triangolo blu. L’output sul tuo schermo TFT dovrebbe essere simile a questo:

Output of test code on TFT — Output del codice di test sul TFT

Se non è così, allora c’è qualcosa che non va nelle impostazioni di tft_test.ino o nel cablaggio del display TFT.

Esempio di cablaggio per TFT 1.3″ ST7789

Nel prossimo esempio ti mostro come collegare il comune 1.3″ ST7789 TFT Display a un WEMOS Lolin32 lite (ESP32):

Connecting TFT ST7789 Display with WEMOS Lolin ESP32 lite — Collegamento display TFT ST7789 con WEMOS Lolin ESP32 lite

Ecco di nuovo le connessioni necessarie in tabella. Nota che questo modulo display non ha chip select (CS) e quindi non serve un pin per questo.

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

Assicurati di collegare VCC del display a 3.3V! Non è compatibile con 5V e non puoi usarlo direttamente con un Arduino UNO. Inoltre dovresti usare i pin hardware SPI. A seconda del microcontrollore i pin hardware SPI variano.

Esempio di codice per TFT 1.3″ ST7789

Ecco la configurazione e il codice per il 1.3″ ST7789 TFT Display. Copia la seguente configurazione nel file 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

Il codice di test per lo sketch va nel file 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() { }

Dovresti vedere il seguente output sul display:

Esempio di cablaggio per TFT 2.8″ ILI9341 Touch Display

In questo ultimo esempio ti mostro come collegare un 2.8″ TFT ILI9341 Touch Display a un WEMOS Lolin32 lite (ESP32):

Connecting the TFT ILI9341 Touch Display to ESP32 — Collegamento TFT ILI9341 Touch Display a ESP32

Ci sono parecchie connessioni da fare e la tabella seguente dovrebbe aiutarti. Nota che le linee SDI(MOSI) e SCK dell’interfaccia SPI sono condivise tra il controller touch e quello del display TFT:

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

Potresti collegare il pin 19 dell’ESP32 anche a SDO(MISO) ma non ne abbiamo bisogno e ci sono segnalazioni che in alcuni casi questo causa problemi. Io non l’ho collegato a SDO(MISO) e il display ha funzionato bene.

Esempio di codice per TFT 2.8″ ILI9341 Touch Display

Ecco la configurazione e il codice per il 2.8″ TFT ILI9341 Touch Display. Copia la seguente configurazione nel file 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

E qui un codice di test per il display che va nel file 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);
  }
}

Questo codice ti permette di calibrare il touch screen e di rilevare i tocchi sul display:

Touch input on TFT ILI9341 Touch Display — Input touch su TFT ILI9341 Touch Display

Per informazioni più dettagliate consulta il tutorial Interface TFT ILI9341 Touch Display with ESP32.

Conclusioni

In questo tutorial hai imparato come configurare la TFT_eSPI Library all’interno dell’IDE Arduino per controllare display TFT.

La TFT_eSPI Library è molto versatile e supporta molti display TFT diversi. Tuttavia, trovare l’impostazione giusta per un nuovo display TFT potrebbe non essere semplice.

Inizia identificando il driver IC usato dal display. Driver comuni sono ST7735, ST7789, ST7796 e ILI9341. Cerca questi nomi nella descrizione del prodotto, nel datasheet e sul PCB del display stesso.

Poi scopri la risoluzione (larghezza, altezza) del display in pixel, ad esempio 128×160. Anche queste informazioni dovresti trovarle nella descrizione del prodotto, nel datasheet o sul PCB del display.

Quindi collega il display al microcontrollore. Se c’è un pin per la retroilluminazione, assicurati che sia collegato a 3.3V (o 5V, a seconda del display). Se non sai se il display è compatibile con 5V, non usare un Arduino ma un ESP32 con 3.3V. Altrimenti potresti danneggiare il driver IC del display.

Infine, carica il codice di test e vedi cosa succede. Ci sono alcuni scenari comuni:

Display nero: Controlla il pin della retroilluminazione e imposta #define TFT_BACKLIGHT_ON HIGH
Colori errati: Prova #define TFT_RGB_ORDER TFT_RGB o TFT_BGR
Bianco e nero invertiti: #define TFT_INVERSION_ON or TFT_INVERSION_OFF
Testo del codice di test non centrato o tagliato: Dimensioni del display errate.
Imposta correttamente TFT_HEIGHT e TFT_WIDTH.
Disturbi, distorsioni o sfarfallio: SPI_FREQUENCY è troppo alta
Pin mancanti: Se sul display non ci sono pin per reset (RST), chip select (CS) o retroilluminazione (BL), imposta le costanti corrispondenti a -1, ad esempio #define TFT_RST -1

Se hai commenti, sentiti libero di lasciarli nella sezione commenti.

Buon divertimento con il tinkering ; )

Stefan Maetschke