ST7789 ESP32: display IPS a colori con TFT_eSPI, sprite, orologio
Guida ST7789 ESP32: TFT_eSPI e User_Setup.h, pin SPI con scritte SCL/SDA, indicatore e orologio senza sfarfallio, Adafruit su Uno, Pico e schermo nero.
La coppia ST7789 ESP32 è il modo più economico per dare a un piccolo progetto un'interfaccia a colori di qualità da smartphone. L'ST7789 è un chip driver TFT prodotto da Sitronix e si trova nella maggior parte dei display IPS in commercio da 1,3 pollici 240x240, 1,54 pollici 240x240, 1,69 pollici 240x280 e 2,0 pollici 240x320. Grazie al pannello IPS i colori restano vivi da ogni angolazione; con 65 mila colori, alta risoluzione e un collegamento SPI veloce puoi disegnare indicatori, grafici e animazioni che un OLED o un LCD a caratteri non riescono a mostrare.
In questa guida vedrai passo dopo passo come collegare l'ST7789 a un ESP32 con la libreria TFT_eSPI, come impostare User_Setup.h, la parte più confusa della libreria, perché il modulo usa SPI e non I2C pur riportando SCL e SDA, come animare senza sfarfallio con uno sprite e come realizzare un indicatore analogico per un sensore e un orologio sincronizzato via NTP. Vedremo anche la libreria Adafruit_ST7789 per Arduino Uno, un driver MicroPython senza librerie per il Raspberry Pi Pico e tutte le cause dello schermo nero.

Cos'è l'ST7789 e in quali display si trova?
L'ST7789 è un chip driver che gestisce ogni pixel del display e trasforma in immagine i comandi del microcontrollore. Al suo interno c'è una memoria video da 240x320 pixel; i display più piccoli ne usano solo una parte. I colori si inviano quasi sempre in formato RGB565, cioè 16 bit per pixel (5 bit di rosso, 6 di verde e 5 di blu). La comunicazione avviene via SPI a 4 fili e il chip regge clock di circa 60 MHz; in pratica con l'ESP32 40 MHz è un valore sicuro. A questa velocità un fotogramma completo 240x240 vale 921.600 bit e viene inviato in circa 23 ms, quindi si possono superare i 40 fotogrammi al secondo.
| Display | Risoluzione | Uso tipico |
|---|---|---|
| 1,14 pollici | 135x240 | Schede ESP32 con display integrato come la TTGO T-Display |
| 1,3 e 1,54 pollici | 240x240 | Smartwatch, piccoli indicatori, interfacce quadrate |
| 1,69 pollici | 240x280 | Display da orologio con angoli arrotondati |
| 1,9 pollici | 170x320 | Barre di stato lunghe e strette |
| 2,0 pollici | 240x320 | Menu, grafici e piccoli giochi |
| Caratteristica | Valore |
|---|---|
| Chip driver | ST7789 (Sitronix) |
| Pannello | IPS, ampio angolo di visione |
| Colori | 65 mila (RGB565), il chip arriva fino a 262 mila |
| Interfaccia | SPI a 4 fili (SCK, MOSI, DC, CS) più RESET |
| Alimentazione | 3,3 V nella maggior parte dei moduli |
| Livello logico | 3,3 V |
| Assorbimento | Circa 20–40 mA con la retroilluminazione |
Pin: c'è scritto SCL e SDA, ma questo display è SPI
I moduli ST7789 economici da 1,3 pollici riportano le scritte GND, VCC, SCL, SDA, RES, DC, BLK; alcuni hanno anche CS. Le scritte SCL e SDA sono ciò che confonde di più i principianti: questo display non usa I2C ma SPI. SCL è in realtà la linea di clock SPI (SCK) e SDA la linea dati (MOSI). Se le colleghi ai pin I2C dell'ESP32, GPIO 21 e 22, il display non funzionerà mai. Spieghiamo come funziona l'SPI nella guida cos'è l'SPI.
| Pin del modulo | Funzione | ESP32 (TFT_eSPI) | Arduino Uno (Adafruit) | Raspberry Pi Pico |
|---|---|---|---|---|
| GND | Massa | GND | GND | GND |
| VCC | Alimentazione | 3V3 | 3.3V | 3V3 (OUT) |
| SCL | Clock SPI (SCK) | GPIO 18 | D13 | GP18 |
| SDA | Dati SPI (MOSI) | GPIO 23 | D11 | GP19 |
| RES | Reset | GPIO 4 | D8 | GP21 |
| DC | Selezione dati o comando | GPIO 2 | D9 | GP20 |
| CS | Selezione chip (se presente) | GPIO 5 | D10 | GP17 |
| BLK | Retroilluminazione | GPIO 32 | 3.3V | GP22 |
Installare TFT_eSPI e impostare User_Setup.h

TFT_eSPI, scritta da Bodmer, è una delle librerie TFT più veloci per l'ESP32. Cercala come TFT_eSPI nel Gestore librerie e installala. A differenza di altre librerie, il tipo di display e i pin non si impostano nello sketch ma nel file User_Setup.h nella cartella della libreria. Si trova in Documenti > Arduino > libraries > TFT_eSPI ed è configurato di default per un display ILI9341. Aprilo con un editor di testo e sostituiscine il contenuto con questo:
1// User_Setup.h: ST7789 240x240 + ESP32 (dosyanın tamamını bununla değiştir / replace the whole file with this)
2#define ST7789_DRIVER // sürücü yonga / driver chip
3#define TFT_WIDTH 240
4#define TFT_HEIGHT 240 // 240x320 ekranda 320 / 320 for a 240x320 panel
5
6#define TFT_MOSI 23 // modüldeki SDA / SDA on the module
7#define TFT_SCLK 18 // modüldeki SCL / SCL on the module
8#define TFT_CS 5 // CS pini yoksa -1 / -1 if the module has no CS pin
9#define TFT_DC 2 // veri-komut / data-command
10#define TFT_RST 4 // reset (RES)
11#define TFT_BL 32 // arka ışık (BLK) / backlight (BLK)
12#define TFT_BACKLIGHT_ON HIGH
13
14// #define TFT_RGB_ORDER TFT_BGR // kırmızı ve mavi yer değiştirmişse aç / enable if red and blue are swapped
15// #define TFT_INVERSION_OFF // renkler negatif görünüyorsa aç / enable if colours look inverted
16
17#define LOAD_GLCD // 8 px yazı tipi / 8 px font
18#define LOAD_FONT2 // 16 px
19#define LOAD_FONT4 // 26 px
20#define LOAD_FONT7 // 48 px 7 segment rakam / 48 px 7-segment digits
21#define LOAD_GFXFF // Adafruit GFX yazı tipleri / Adafruit GFX fonts
22#define SMOOTH_FONT
23
24#define SPI_FREQUENCY 40000000 // 40 MHz; sorun olursa 27000000 / 40 MHz; drop to 27000000 if unstable- Installa TFT_eSPI e sostituisci User_Setup.h con le righe qui sopra.
- Se il tuo display è 240x320, imposta TFT_HEIGHT a 320; su un modulo senza pin CS imposta TFT_CS a -1.
- Collega il display come nella tabella: SCL a GPIO 18, SDA a GPIO 23, RES a GPIO 4, DC a GPIO 2, CS a GPIO 5, BLK a GPIO 32.
- Chiudi e riapri l'Arduino IDE; le impostazioni della libreria vengono lette in fase di compilazione.
- Carica il primo sketch di prova qui sotto; sul display dovresti vedere testo e forme colorate.
Primo test: testo, forme e colori
1#include <TFT_eSPI.h> // ayarlar User_Setup.h içinde / settings live in User_Setup.h
2
3TFT_eSPI tft = TFT_eSPI();
4
5void setup() {
6 tft.init();
7 tft.setRotation(0); // 0-3: ekranı 90'ar derece döndürür / rotates in 90° steps
8 tft.fillScreen(TFT_BLACK);
9
10 tft.setTextDatum(MC_DATUM); // metni ortadan hizala / centre-align text
11 tft.setTextColor(TFT_WHITE, TFT_BLACK);
12 tft.drawString("BlueGrays", 120, 30, 4); // metin, x, y, yazı tipi / text, x, y, font
13 tft.drawString("ST7789 240x240", 120, 60, 2);
14
15 tft.fillRect(20, 90, 60, 60, TFT_RED); // dolu kare / filled square
16 tft.fillCircle(120, 120, 30, TFT_GREEN); // dolu daire / filled circle
17 tft.fillTriangle(170, 150, 200, 90, 230, 150, TFT_BLUE);
18 tft.drawRoundRect(10, 170, 220, 50, 10, TFT_YELLOW);
19
20 uint16_t orange = tft.color565(255, 140, 0); // kendi rengin (RGB565) / your own colour (RGB565)
21 tft.setTextColor(orange, TFT_BLACK);
22 tft.drawString("R G B", 120, 195, 4);
23}
24
25void loop() {
26}In TFT_eSPI le coordinate partono dall'angolo in alto a sinistra (0, 0) e l'angolo in basso a destra di un display 240x240 è (239, 239). L'ultimo numero di drawString(testo, x, y, font) sceglie il font: 1 è un piccolo font da 8 pixel, 2 da 16 pixel, 4 da 26 pixel e 7 un font di cifre a 7 segmenti da 48 pixel. setTextDatum(MC_DATUM) centra il testo sul punto indicato, comodissimo per indicatori e orologi. I colori si indicano con nomi pronti come TFT_RED e TFT_GREEN oppure con le tue tonalità tramite color565(r, g, b).
| Funzione | Cosa fa? |
|---|---|
| fillScreen(colore) | Colora tutto lo schermo |
| drawPixel(x, y, colore) | Un singolo pixel |
| drawLine / drawWideLine | Linea sottile o spessa |
| drawRect / fillRect / fillRoundRect | Rettangolo, pieno e con angoli arrotondati |
| drawCircle / fillCircle | Cerchio |
| fillTriangle | Triangolo pieno |
| drawString / drawNumber / drawFloat | Testo, numero intero e decimale |
| setRotation(0-3) | Ruota lo schermo a passi di 90 gradi |
Animazioni senza sfarfallio con gli sprite
Quando disegni direttamente sullo schermo, per aggiornare qualcosa devi prima cancellare il vecchio e poi disegnare il nuovo. Tra questi due passaggi lo schermo resta vuoto per un attimo e l'occhio lo percepisce come sfarfallio. Lo sprite risolve il problema: disegni prima su una tela invisibile nella RAM dell'ESP32 e, quando il fotogramma è completo, lo invii allo schermo in un colpo solo con pushSprite(). Un disegno a metà non compare mai.
L'unico prezzo dello sprite è la memoria. Uno sprite a colori a 16 bit usa 2 byte per pixel: uno a schermo intero 240x240 occupa 115.200 byte e uno 240x320 153.600 byte. Anche se l'ESP32 ha in tutto 520 KB di RAM, il blocco più grande allocabile in un pezzo unico spesso si aggira sui 110 KB; su una scheda senza PSRAM uno sprite a schermo intero a 16 bit potrebbe quindi non entrare. La soluzione è scendere al colore a 8 bit con setColorDepth(8) (57,6 KB per 240x240) oppure disegnare come piccolo sprite solo la zona che cambia, per esempio le cifre dell'orologio. createSprite() restituisce nullptr se non trova memoria; controllarlo evita errori silenziosi.
| Dimensione dello sprite | 16 bit | 8 bit |
|---|---|---|
| 240x240 (schermo intero) | 115,2 KB | 57,6 KB |
| 240x320 (schermo intero) | 153,6 KB | 76,8 KB |
| 220x120 (zona orologio) | 52,8 KB | 26,4 KB |
| 100x50 (un solo valore) | 10 KB | 5 KB |
Progetto: indicatore analogico per un sensore
Lo sketch qui sotto trasforma un potenziometro su GPIO 34 in un valore da 0 a 100 e lo mostra con una lancetta su un arco di 270 gradi, come il tachimetro di un'auto. Le tacche della scala sopra 80 sono rosse. Al posto del potenziometro puoi passare alla stessa funzione un valore di temperatura, umidità, gas o umidità del terreno. Poiché lo sprite viene cancellato e ridisegnato da zero a ogni fotogramma, la lancetta si muove in modo fluido e non sfarfalla mai.
1#include <TFT_eSPI.h>
2
3TFT_eSPI tft = TFT_eSPI();
4TFT_eSprite spr = TFT_eSprite(&tft); // bellekteki çizim alanı / off-screen drawing area
5
6const int POT_PIN = 34; // potansiyometre ya da sensör / potentiometer or sensor
7const int CX = 120, CY = 130, R = 100;
8float smooth = 0;
9
10void pointAt(float v, int radius, int &x, int &y) { // 0-100 değeri yay üzerindeki noktaya çevir / value to a point on the arc
11 float a = radians(225 - v * 2.7); // 270 derecelik yay / 270-degree arc
12 x = CX + cos(a) * radius;
13 y = CY - sin(a) * radius;
14}
15
16void drawGauge(int value) {
17 spr.fillSprite(TFT_BLACK); // her kare temiz başlar / every frame starts clean
18 for (int v = 0; v <= 100; v += 5) { // ölçek çizgileri / scale ticks
19 int x0, y0, x1, y1;
20 pointAt(v, R, x0, y0);
21 pointAt(v, (v % 10 == 0) ? R - 14 : R - 7, x1, y1);
22 spr.drawLine(x0, y0, x1, y1, v >= 80 ? TFT_RED : TFT_LIGHTGREY);
23 }
24 int nx, ny;
25 pointAt(value, R - 20, nx, ny);
26 spr.drawWideLine(CX, CY, nx, ny, 4, TFT_ORANGE); // ibre / needle
27 spr.fillCircle(CX, CY, 8, TFT_DARKGREY);
28
29 spr.setTextDatum(MC_DATUM);
30 spr.setTextColor(TFT_WHITE);
31 spr.drawNumber(value, CX, CY + 55, 7); // 7 segment rakam / 7-segment digits
32 spr.drawString("%", CX + 62, CY + 62, 4);
33 spr.pushSprite(0, 0); // tek seferde ekrana bas / push to the screen in one go
34}
35
36void setup() {
37 tft.init();
38 tft.fillScreen(TFT_BLACK);
39 spr.setColorDepth(8); // 8 bit: 57,6 KB, 16 bit olsa 115 KB / 8-bit: 57.6 KB instead of 115 KB
40 if (spr.createSprite(240, 240) == nullptr) { // bellek yetmezse / if memory runs out
41 tft.drawString("Sprite RAM yok", 10, 10, 2);
42 while (true) delay(100);
43 }
44}
45
46void loop() {
47 float raw = analogRead(POT_PIN) * 100.0 / 4095.0; // 0-100 aralığı / 0-100 range
48 smooth += (raw - smooth) * 0.2; // titremeyi yumuşat / smooth out jitter
49 drawGauge((int)smooth);
50 delay(20); // yaklaşık 40 kare/sn / about 40 frames per second
51}La funzione pointAt() del codice trasforma un valore da 0 a 100 in un punto dell'arco: 0 corrisponde a 225 gradi (in basso a sinistra) e 100 a −45 gradi (in basso a destra). Poiché sullo schermo l'asse y cresce verso il basso, davanti al seno c'è un segno meno. La variabile smooth filtra le piccole oscillazioni dell'ADC; se riduci il fattore 0,2 la lancetta si muove più lenta, se lo aumenti reagisce più in fretta. Per saperne di più sull'ADC dell'ESP32, guarda la guida cos'è un ADC.
Progetto: interfaccia orologio con NTP
Uno degli usi preferiti dell'ST7789 è l'orologio da scrivania. Lo sketch qui sotto collega l'ESP32 al Wi-Fi, prende l'ora dai server NTP di internet, qui con il fuso orario della Turchia, e la mostra con grandi cifre a 7 segmenti. Questa volta, invece di uno sprite a schermo intero, usiamo uno sprite 220x120 che copre solo la zona dell'orologio; il nome del giorno viene scritto direttamente sullo schermo perché cambia una sola volta al giorno. Per l'Italia imposta TZ_INFO a "CET-1CEST,M3.5.0,M10.5.0/3"; i dettagli su NTP e fusi orari sono nella guida ora NTP con ESP32.
1#include <WiFi.h>
2#include <time.h>
3#include <TFT_eSPI.h>
4
5const char* WIFI_SSID = "AgAdi";
6const char* WIFI_PASS = "Sifre123";
7const char* TZ_INFO = "<+03>-3"; // Türkiye UTC+3 / Turkey UTC+3
8const char* DAYS[] = {"Pazar", "Pazartesi", "Sali", "Carsamba", "Persembe", "Cuma", "Cumartesi"};
9
10TFT_eSPI tft = TFT_eSPI();
11TFT_eSprite clockSpr = TFT_eSprite(&tft); // yalnız saat bölgesi / clock area only
12int lastSecond = -1;
13
14void setup() {
15 tft.init();
16 tft.fillScreen(TFT_NAVY);
17 tft.setTextDatum(MC_DATUM);
18 tft.setTextColor(TFT_WHITE, TFT_NAVY);
19 tft.drawString("Wi-Fi...", 120, 120, 4);
20
21 WiFi.begin(WIFI_SSID, WIFI_PASS);
22 while (WiFi.status() != WL_CONNECTED) delay(300);
23 configTzTime(TZ_INFO, "pool.ntp.org", "time.cloudflare.com");
24
25 tft.fillScreen(TFT_NAVY);
26 clockSpr.createSprite(220, 120); // 16 bit: 52,8 KB / 16-bit: 52.8 KB
27 clockSpr.setTextDatum(MC_DATUM);
28}
29
30void loop() {
31 struct tm t;
32 if (!getLocalTime(&t, 100) || t.tm_sec == lastSecond) return; // saniye değişince çiz / draw on each new second
33 lastSecond = t.tm_sec;
34
35 char hm[6], sec[3], date[11];
36 strftime(hm, sizeof(hm), "%H:%M", &t);
37 strftime(sec, sizeof(sec), "%S", &t);
38 strftime(date, sizeof(date), "%d.%m.%Y", &t);
39
40 clockSpr.fillSprite(TFT_NAVY);
41 clockSpr.fillRoundRect(0, 0, 220, 120, 14, TFT_BLACK);
42 clockSpr.setTextColor(TFT_CYAN);
43 clockSpr.drawString(hm, 95, 45, 7); // büyük saat:dakika / big hours:minutes
44 clockSpr.setTextColor(TFT_ORANGE);
45 clockSpr.drawString(sec, 195, 55, 4); // saniye / seconds
46 clockSpr.setTextColor(TFT_WHITE);
47 clockSpr.drawString(date, 110, 100, 4);
48 clockSpr.pushSprite(10, 40); // titremeden güncelle / update without flicker
49
50 tft.setTextColor(TFT_YELLOW, TFT_NAVY);
51 tft.fillRect(0, 175, 240, 30, TFT_NAVY);
52 tft.drawString(DAYS[t.tm_wday], 120, 190, 4); // gün adı / day name
53}L'orologio viene ridisegnato solo quando cambia il secondo; mentre loop() gira a vuoto, il processore ha tempo per altri compiti. I font integrati di TFT_eSPI non hanno lettere accentate, per questo i nomi dei giorni in turco nel codice sono scritti senza caratteri speciali; sostituiscili pure con "Lunedi", "Martedi" e così via. Se vuoi gli accenti, puoi creare e caricare un tuo font con la funzione smooth font di TFT_eSPI. Per aggiungere una riga con il meteo a questo orologio basta combinarlo con il codice Open-Meteo della guida API meteo con ESP32.
ST7789 con Arduino Uno: Adafruit_ST7789
TFT_eSPI non funziona su Arduino Uno; qui si usano la Adafruit ST7735 and ST7789 Library e Adafruit GFX. I 2 KB di RAM della Uno non bastano nemmeno per uno sprite, quindi tutto viene disegnato direttamente sullo schermo e la velocità è nettamente inferiore all'ESP32. Va comunque bene per menu, numeri e grafici semplici. I pin dell'SPI hardware sono fissi: SDA (MOSI) va a D11 e SCL (SCK) a D13; per CS, DC e RST puoi scegliere i pin digitali che preferisci.
1#include <Adafruit_GFX.h>
2#include <Adafruit_ST7789.h>
3#include <SPI.h>
4
5#define TFT_CS 10 // CS pini yoksa -1 / -1 if there is no CS pin
6#define TFT_DC 9
7#define TFT_RST 8
8// SDA (MOSI) -> D11, SCL (SCK) -> D13: donanım SPI / hardware SPI
9
10Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_RST);
11
12void setup() {
13 tft.init(240, 240); // CS'siz modülde: tft.init(240, 240, SPI_MODE3) / without CS
14 tft.setRotation(0);
15 tft.fillScreen(ST77XX_BLACK);
16 tft.setTextColor(ST77XX_WHITE);
17 tft.setTextSize(3);
18 tft.setCursor(20, 20);
19 tft.print(F("BlueGrays"));
20 tft.setTextSize(2);
21 tft.setCursor(20, 70);
22 tft.print(F("A0 degeri:"));
23}
24
25void loop() {
26 int value = analogRead(A0);
27 tft.setTextColor(ST77XX_YELLOW, ST77XX_BLACK); // arka plan rengi eski rakamı siler / background colour erases old digits
28 tft.setTextSize(5);
29 tft.setCursor(20, 110);
30 if (value < 1000) tft.print(' '); // basamak sayısı değişince boşluk / pad when digits shrink
31 if (value < 100) tft.print(' ');
32 if (value < 10) tft.print(' ');
33 tft.print(value);
34 delay(200);
35}Questo sketch mostra il metodo anti-sfarfallio adatto alla Uno: quando setTextColor(coloreTesto, coloreSfondo) viene chiamata con due colori, ogni carattere viene disegnato insieme al proprio sfondo e sovrascrive la cifra precedente. Non serve cancellare lo schermo e il numero cambia senza sfarfallare. Gli spazi aggiunti davanti evitano che restino tracce delle vecchie cifre quando il numero si accorcia. Se vuoi un display simile su un pannello touch da 2,4 pollici, la guida display TFT ILI9341 segue la stessa logica.
ST7789 con il Raspberry Pi Pico (MicroPython)
MicroPython non ha un driver integrato per l'ST7789, ma i comandi del chip sono abbastanza semplici da scrivere un piccolo driver tutto tuo. I 264 KB di RAM del Pico bastano per un buffer video da 115 KB che copre l'intero display 240x240. Il codice qui sotto inizializza il display, disegna testo e forme nel buffer con il modulo framebuf di MicroPython e invia il buffer via SPI in un colpo solo; un quadrato che scorre mostra come animare. Il collegamento usa il bus SPI0: SCL a GP18 e SDA a GP19.
1from machine import Pin, SPI
2import framebuf
3import time
4
5W, H = 240, 240
6spi = SPI(0, baudrate=40_000_000, polarity=1, phase=1, sck=Pin(18), mosi=Pin(19)) # SPI mod 3 / SPI mode 3
7cs = Pin(17, Pin.OUT, value=1) # CS'siz modülde boşta kalır / unused on modules without CS
8dc = Pin(20, Pin.OUT)
9rst = Pin(21, Pin.OUT, value=1)
10bl = Pin(22, Pin.OUT, value=1) # arka ışık açık / backlight on
11
12def cmd(c, data=None): # komut + isteğe bağlı veri / command + optional data
13 cs(0)
14 dc(0)
15 spi.write(bytes([c]))
16 if data:
17 dc(1)
18 spi.write(data)
19 cs(1)
20
21def init():
22 rst(0); time.sleep_ms(50); rst(1); time.sleep_ms(150)
23 cmd(0x01); time.sleep_ms(150) # SWRESET: yazılım reseti / software reset
24 cmd(0x11); time.sleep_ms(120) # SLPOUT: uykudan çık / exit sleep
25 cmd(0x3A, b'\x55') # COLMOD: 16 bit RGB565
26 cmd(0x36, b'\x00') # MADCTL: yön, RGB sırası / orientation, RGB order
27 cmd(0x21) # INVON: IPS paneller için / for IPS panels
28 cmd(0x13) # NORON: normal mod / normal mode
29 cmd(0x29); time.sleep_ms(50) # DISPON: ekranı aç / display on
30
31def show(buf):
32 cmd(0x2A, bytes([0, 0, 0, W - 1])) # CASET: sütun 0-239 / columns 0-239
33 cmd(0x2B, bytes([0, 0, 0, H - 1])) # RASET: satır 0-239 / rows 0-239
34 cmd(0x2C, buf) # RAMWR: tamponu gönder / send the buffer
35
36def rgb(r, g, b): # RGB565, bayt sırası ekrana göre çevrilmiş / byte-swapped for the panel
37 c = ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)
38 return ((c & 0xFF) << 8) | (c >> 8)
39
40init()
41buf = bytearray(W * H * 2) # 115.200 bayt / 115,200 bytes
42fb = framebuf.FrameBuffer(buf, W, H, framebuf.RGB565)
43
44x, dx = 0, 4
45while True:
46 fb.fill(rgb(0, 0, 40))
47 fb.text("BlueGrays", 84, 20, rgb(255, 255, 255))
48 fb.text("Pico + ST7789", 68, 40, rgb(0, 200, 255))
49 fb.rect(20, 200, 200, 20, rgb(255, 255, 0))
50 fb.fill_rect(20 + x, 100, 40, 40, rgb(255, 60, 0)) # kayan kare / moving square
51 show(buf) # tüm kareyi tek seferde gönder / send the whole frame at once
52 x += dx
53 if x <= 0 or x >= 160:
54 dx = -dxLa funzione rgb() del codice risolve un dettaglio importante: framebuf salva i colori in memoria con il byte basso per primo, mentre l'ST7789 si aspetta prima il byte alto. Se non scambi i byte, il rosso appare blu e il blu verdastro. Il comando 0x36 (MADCTL) imposta l'orientamento del display e l'ordine RGB o BGR; se ruoti l'immagine di 180 gradi su un pannello 240x240, l'immagine scivola nella parte bassa della memoria e devi aggiungere uno scostamento di 80 pixel all'indirizzo di riga. Se preferisci l'Arduino IDE, installa sul Pico il core arduino-pico e usa TFT_eSPI con le impostazioni per RP2040. Se sei nuovo di MicroPython, parti dalla guida basi di MicroPython.
Schermo nero e altri problemi: tabella delle soluzioni
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Schermo tutto nero, retroilluminazione spenta | BLK scollegato o a LOW | Collega BLK a 3,3 V o al pin TFT_BL, con TFT_BACKLIGHT_ON a HIGH |
| Retroilluminazione accesa ma nessuna immagine | User_Setup.h ancora impostato su ILI9341 o azzerato da un aggiornamento | Ricontrolla la riga ST7789_DRIVER e i pin |
| Retroilluminazione accesa, nessuna immagine (modulo senza CS) | Modalità SPI sbagliata | Imposta TFT_CS a -1; con Adafruit usa init(240, 240, SPI_MODE3) |
| Non succede nulla | SCL e SDA collegati ai pin I2C (21, 22) | Collega SCL a GPIO 18 e SDA a GPIO 23 |
| Funziona a intermittenza | Pin di reset scollegato, cavi lunghi o SPI troppo veloce | Collega RES, accorcia i cavi, abbassa SPI_FREQUENCY a 27 MHz |
| Colori come un negativo | L'inversione dei colori non corrisponde al pannello | Prova TFT_INVERSION_OFF o TFT_INVERSION_ON |
| Rosso e blu scambiati | Il pannello usa l'ordine BGR | Attiva la riga TFT_RGB_ORDER TFT_BGR |
| Una banda disturbata su parte dello schermo | Altezza sbagliata (320 su un pannello 240x240) o scostamento in rotazione | Imposta bene TFT_HEIGHT, prova con setRotation |
| L'ESP32 va in crash su tft.init() | Incompatibilità segnalata con il core ESP32 3.x | Prova un core 2.0.x dal Gestore schede o passa alla libreria LovyanGFX |
| Il display scalda o si guasta con la Uno | Livello logico a 5 V | Usa un convertitore di livello |
Idee di progetti con l'ST7789
- Orologio da scrivania smart: Mostra l'ora NTP, la temperatura della stanza letta da un BME280 e il meteo del giorno da internet su un solo schermo.
- Cruscotto sensori: Presenta temperatura, umidità e gas su indicatori colorati; lo sfondo diventa rosso quando si supera la soglia del MQ-2.
- Mini console di giochi: Gioca a snake, Pong o a un gioco spaziale con un joystick; gli sprite mantengono il gioco fluido.
- Interfaccia per lettore musicale: Mostra titolo del brano, volume e barra di avanzamento di un DFPlayer Mini.
- Grafico stile oscilloscopio: Disegna i valori di analogRead come un grafico che scorre e osserva la forma del segnale.
- Display per lettore di tessere: Mostra nome e autorizzazione della tessera letta con un RFID RC522 su una scheda colorata.
Insieme a un ESP32, l'ST7789 trasforma un display da pochi euro in un'interfaccia dall'aspetto professionale. Una volta impostato bene User_Setup.h e capito il principio dello sprite, puoi disegnare orologi, indicatori, menu, giochi e qualsiasi altra interfaccia senza sfarfallio. Per confrontare quale display si adatta al tuo progetto, guarda la guida tipi di display per Arduino. Nell'app BlueGrays trovi progetti ESP32 di meteo, orologio, miscelatore di colori e sensore di parcheggio con display OLED e LCD, con schema elettrico e codice passo dopo passo, e puoi trasformare gli stessi progetti in versioni a colori con l'ST7789.
Domande frequenti
L'ST7789 è I2C o SPI?
L'ST7789 funziona in SPI. Le scritte SCL e SDA sul modulo ingannano: SCL è la linea di clock SPI (SCK) e SDA la linea dati (MOSI). Su un ESP32 collegale a GPIO 18 e GPIO 23, non ai pin I2C 21 e 22.
Perché il mio display ST7789 resta nero?
Le cause più comuni sono la retroilluminazione (BLK) scollegata, un User_Setup.h in cui è ancora selezionato il driver ILI9341, SCL e SDA collegati ai pin I2C e la modalità SPI sbagliata su un modulo senza CS. Prima assicurati che la retroilluminazione si accenda, poi controlla le righe ST7789_DRIVER, TFT_WIDTH, TFT_HEIGHT e i pin in User_Setup.h.
L'ST7789 funziona a 5 V?
Il chip ST7789 lavora a 3,3 V e i suoi pin non tollerano i 5 V. ESP32 e Pico si collegano direttamente; con Arduino Uno alimenta il modulo a 3,3 V e metti un convertitore di livello sulle linee di segnale. Alcuni moduli hanno un regolatore, ma le linee dati restano a 3,3 V.
Dove si trova il file User_Setup.h di TFT_eSPI?
User_Setup.h si trova nella cartella TFT_eSPI dentro la cartella delle librerie di Arduino, di solito Documenti > Arduino > libraries > TFT_eSPI. Nel file si definiscono driver del display, risoluzione, pin e velocità SPI. Viene azzerato a ogni aggiornamento della libreria, quindi conserva una copia delle tue impostazioni.
Cos'è uno sprite e perché evita lo sfarfallio?
Uno sprite è un'area di disegno invisibile conservata nella RAM dell'ESP32. Disegni tutto prima lì e, quando è pronta, la invii allo schermo in un colpo solo con pushSprite(), così l'immagine intermedia cancellata non si vede mai. Il prezzo è la memoria: con il colore a 16 bit ogni pixel occupa 2 byte.
Si può usare l'ST7789 con Arduino Uno?
Sì, con le librerie Adafruit ST7789 e Adafruit GFX, ma il disegno è lento perché i 2 KB di RAM della Uno non bastano per uno sprite. I suoi pin sono a 5 V, quindi serve un convertitore di livello in mezzo. Se vuoi un'interfaccia a colori fluida, l'ESP32 è una scelta molto migliore.
Progetti da realizzare dopo questo articolo
Vedi tutti i progetti
ESP32 HTTPClient + API meteo (con display OLED SSD1306)
L'ESP32 effettua via internet una chiamata REST a un'API meteo (wttr.in) con HTTPClient.h. A differenza della versione con LCD I2C, qui usiamo un display OLED SSD1306 (128×64), con testo grande e icone vettoriali per una resa più ricca. Sette icone meteo (sole, pioggia, neve e altre) vengono disegnate al volo, senza file bitmap.

Schermo LCD I2C per ESP32 (16x2)
In questo progetto colleghiamo un display LCD 16x2 a caratteri all'ESP32 tramite I2C per mostrare del testo. Con l'I2C bastano 2 pin dati (SDA e SCL) invece dei 6+ pin di un collegamento parallelo classico. Il codice scrive un messaggio fisso sulla prima riga e un contatore che sale ogni secondo sulla seconda. All'avvio uno scanner I2C stampa l'indirizzo del display sul Serial Monitor (di solito 0x27 o 0x3F).

ESP32 TM1637 Display a 7 segmenti a 4 cifre
Stiamo controllando un modulo display a 7 segmenti a 4 cifre con driver TM1637 tramite ESP32. Utilizzando solo 2 GPIO (CLK e DIO), gestiamo un contatore compreso tra 0 e 9999, regoliamo il livello di luminosità e visualizziamo il carattere dei due punti centrali (:) in formato orologio. Grazie alla libreria TM1637Display, il controllo di numeri, valori esadecimali, segmenti e stringhe è molto semplice.

ESP32 Deep Sleep — Risparmio della batteria (OLED + contatore in RTC RAM)
La modalità Deep Sleep dell'ESP32 spegne la CPU e quasi tutte le periferiche e riduce il consumo a circa 10µA, un aspetto cruciale per i dispositivi IoT a batteria. Il progetto usa tre sorgenti di risveglio: un timer (15 s), un pin esterno (EXT0, il pulsante su GPIO 33) e un pin touch (T0/GPIO 4). I contatori marcati con RTC_DATA_ATTR restano salvati durante il deep sleep.

Contatore di raka'at per la preghiera con ESP32 (HC-SR04 + OLED SSD1306 + 2 pulsanti)
Ti capita di perdere il conto delle rakat durante la preghiera? Questo contatore si mette accanto al tuo tappeto e conta le prosternazioni quando avvicini la mano. Il sensore a ultrasuoni HC-SR04 rileva la mano, il display OLED SSD1306 mostra il numero e con due pulsanti scegli 2, 3 o 4 rakat e azzeri. Un debounce di 2,5 secondi e il controllo della mano allontanata evitano di contare due volte la stessa prosternazione.

Lampada con miscelatore di colori ESP32 (3 potenziometri + LED RGB + OLED)
Una lampada mixer di colori smart: gira 3 potenziometri sull'ESP32 e mescola il colore che vuoi! Mentre ruoti i potenziometri rosso, verde e blu, il LED RGB a catodo comune cambia colore all'istante. Il display OLED SSD1306 mostra in tempo reale il valore 0-255 di ogni colore, barre di riempimento e il codice colore web HEX (come #FF8040).

Sensore di parcheggio ESP32 (HC-SR04 + barra a 5 LED + cicalino + OLED)
La versione ESP32 di un sensore di parcheggio! Il sensore a ultrasuoni HC-SR04 misura la distanza dall'oggetto davanti. Più si avvicina, più si riempie una barra di 5 LED (verde → giallo → rosso) e più il buzzer suona rapido. Molto vicino (sotto i 10 cm) parte un allarme continuo e si accendono tutti i LED. Il display OLED SSD1306 mostra i cm in tempo reale a caratteri grandi, insieme a un messaggio di stato.

Gioco delle Racchette - SSD1306
Una pallina, due racchette e tu: giochi a ping pong, uno dei primissimi videogiochi, su un piccolo display OLED.
Altri articoli
App BlueGrays
Costruisci questo circuito passo passo sul telefono
Schema, codice ed elenco componenti in un’unica schermata. Oltre 500 progetti Arduino, ESP32 e Pico da realizzare.
Inquadra con il telefono
Punta la fotocamera sul codice: si apre lo store del tuo telefono.
oppure apri lo store

