ESP32-S3 con GC9A01 display circolare + VL53L0X-V2 misura della distanza laser — tutorial completo (cablaggio SPI + insidie I2C)
Usa l'ESP32-S3 per pilotare un GC9A01 da 1.28 pollici circolare, insieme al sensore VL53L0X-V2 per la misura della distanza laser, e costruisci un tachimetro cyberpunk con ago che si muove in tempo reale e un arco che cambia colore in base alla distanza. In guida: risoluzione dei conflitti di pin SPI+I2C e tutto il codice sorgente Arduino.

ESP32-S3 con GC9A01 display circolare + VL53L0X-V2 misura della distanza laser: dal cablaggio all’accensione di un tachimetro cyberpunk (codice completo)
Difficoltà: ⭐⭐⭐☆☆ (adatto a un maker con un po’ di basi, serve un po’ di pazienza con i cavetti) Tempo stimato: 45 minuti Ambiente di test: Arduino IDE 2.3.8 + ESP32 Core 3.3.10 + Arduino_GFX_Library v1.6.5 + Adafruit_VL53L0X v1.2.5
TL;DR (avvio rapido):
- Cablaggio schermo: GPIO12→SCL, GPIO11→SDA, GPIO9→CS, GPIO10→DC, GPIO18→RST, GPIO7→BL
- Cablaggio sensore: GPIO13→SDA, GPIO14→SCL (attenzione, non sono i pin I2C predefiniti, perché GPIO9 è già usato dal CS dello schermo)
- Installa due librerie:
Arduino_GFX_Library,Adafruit_VL53L0X- Prima carica lo “sketch di test del sensore”: quando la porta seriale mostra i valori di distanza, carica il programma principale
- Carica il programma principale: sul display circolare apparirà un tachimetro lidar con ago rotante e colore variabile
Premessa: perché sbattersi con questo tachimetro circolare
I moduli per la misura della distanza laser (ToF) sono molto usati, ma la maggior parte della gente si ferma alla fase “stampo i numeri sulla porta seriale”. L’obiettivo di questo progetto è semplice: sfruttare le prestazioni dell’ESP32-S3 e l’impatto visivo del GC9A01 circolare per trasformare dati di distanza astratti in un tachimetro ad alta frequenza di aggiornamento, utile e dall’estetica cyberpunk.
La difficoltà centrale del progetto non sta nella logica, ma nel conflitto di pin tra l’interfaccia SPI dello schermo e l’interfaccia I2C del sensore. Per risolvere il problema dell’inizializzazione fallita causata dai pin predefiniti della scheda “in conflitto tra loro”, ho rimappato l’hardware. Seguono la guida agli errori comuni e l’implementazione del programma principale.
Anteprima del risultato finale
Il risultato finale è questo: sul display circolare viene disegnato un quadrante ad arco simile al contagiri di un’auto da corsa; l’ago punta in tempo reale alla distanza attualmente misurata, il colore dell’arco passa dal rosso (vicino/pericolo) al verde (lontano/sicuro) e al centro compaiono i millimetri esatti e il testo di stato (DANGER / WARNING / CAUTION / SAFE / CLEAR). Muovi la mano davanti al sensore e l’ago ondeggia in tempo reale — piuttosto rilassante.
Descrizione dei componenti
Della scheda di sviluppo (ESP32-S3) non parliamo oltre, concentriamoci sugli altri due protagonisti.
GC9A01 240×240 display circolare
Il GC9A01 è un chip display driver pensato apposta per gli schermi circolari: si occupa di “tradurre” i dati pixel che gli invii nell’immagine sul display — tu gli dici cosa disegnare, lui si occupa di come disegnarlo; tutto il refresh e la scansione intermedia sono gestiti da lui, tu ti limiti a chiamare le API.
| Parametro | Valore |
|---|---|
| Risoluzione | 240×240 |
| Dimensioni | 1.28 pollici |
| Interfaccia | SPI |
| Profondità colore | 65K colori (RGB565) |
| Libreria driver | Arduino_GFX_Library |
L’abbiamo scelto perché costa poco, un display circolare è naturalmente bello per un tachimetro e l’interfaccia SPI è sufficientemente veloce da non lasciare scie durante la rotazione dell’ago.
Sensore per la misura della distanza laser VL53L0X-V2
Il VL53L0X è un sensore per la misura della distanza laser basato sul principio del tempo di volo (ToF); in parole povere: emette un raggio laser infrarosso invisibile, cronometra il tempo che il laser impiega a colpire un oggetto e tornare indietro riflesso, e da questo risale alla distanza — è la stessa idea dell’ecolocalizzazione dei pipistrelli, solo che usa la luce invece del suono.
| Parametro | Valore |
|---|---|
| Range di misura | 30mm~1200mm (in modalità long range fino a circa 2000mm) |
| Precisione | ±3% |
| Interfaccia di comunicazione | I2C (fino a 400kHz) |
| Lunghezza d’onda del laser | 940nm (invisibile a occhio nudo, laser Class 1, sicuro) |
L’abbiamo scelto perché non è influenzato dal colore o dal materiale del bersaglio (rispetto ai sensori a ultrasuoni, è quasi insensibile alla superficie), è così piccolo da entrare in qualsiasi scatola e l’interfaccia I2C richiede solo due fili segnale.
💡 Piccola nota: questo modulo di solito non ha il coperchio ottico (io quando l’ho comprato me ne sono dimenticato)
Nella fase di test a nudo va tutto benissimo, ma ci sono alcune insidie da conoscere in anticipo:
- Non toccare la superficie del chip con le dita: le due finestrelle di grandi quanto un seme di sesamo sul chip (una emette, l’altra riceve) temono polvere, unto e umidità. Quando sono sporche, la polvere riflette il laser indietro causando “crosstalk”: la misura inspiegabilmente si accorcia, i numeri ballano e nei casi gravi il sensore smette di funzionare.
- Se si sporca, non strofinare a caso: non pulirlo mai con l’orlo della maglia o con un fazzoletto di carta (si graffia subito). Per la polvere usa un pompetta (palloncino soffia-aria), per l’unto usa un bastoncino di cotone imbevuto di un goccio di alcol isopropilico (senza acqua) passato con estrema delicatezza, poi lascia asciugare.
- Sotto luce forte “diventa cieco”: la luce solare e le vecchie lampadine a incandescenza contengono infrarossi; a nudo, senza coperchio, la portata massima crolla sensibilmente. Sul tavolo di casa non si nota, ma se lo porti fuori sappilo.
Se in futuro vuoi chiuderlo in un box per uso prolungato: non incollare nastro adesivo trasparente o vetro normale davanti al chip — i materiali comuni riflettono l’infrarosso, il sensore interpreterà il coperchio come un ostacolo e si bloccherà a
0mmo a pochi centimetri. O gli fai un foro per farlo sporgere, o ti procuri un filtro passa-infrarossi 940nm e lo incolli il più vicino possibile (distanza inferiore a 1mm).
BOM (lista componenti)
| Componente | Quantità | Note |
|---|---|---|
| Scheda di sviluppo ESP32-S3 | 1 | qualsiasi modello con GPIO sufficienti |
| GC9A01 display circolare 1.28“ (SPI) | 1 | verifica che sia la versione SPI, non quella a bus parallelo |
| Modulo VL53L0X-V2 ToF | 1 | versione per breadboard |
| Cavetti jumper | alcuni |
Descrizione dei pin dei componenti
Pin del GC9A01
| Pin | Funzione |
|---|---|
| VCC | Polo positivo dell’alimentazione, collega a 3.3V |
| GND | Massa |
| SCL/CLK | Linea di clock SPI |
| SDA/MOSI | Linea dati SPI |
| CS | Chip select, il chip lavora con livello basso |
| DC | Pin di selezione dato/comando |
| RST | Pin di reset |
| BL | Pin di controllo retroilluminazione (su alcuni moduli non è esposto, puoi ignorarlo) |
Pin del VL53L0X-V2
| Pin | Funzione |
|---|---|
| VIN | Polo positivo dell’alimentazione |
| GND | Massa |
| SCL | Ingresso clock seriale I2C |
| SDA | Dati seriali I2C |
| GPIO1 | Pin di uscita interrupt, indica che i dati sono pronti (in questo progetto non serve, lascialo scollegato) |
| XSHUT | Pin di spegnimento, tenuto alto in condizioni normali, messo basso entra in modalità shutdown (in questo progetto non serve, lascialo scollegato) |
Modalità di cablaggio
Ti consiglio di collegare una riga alla volta secondo la tabella e spuntare ogni cavetto man mano: risparmi l’80% del tempo di debugging.
ESP32-S3 → schermo GC9A01
| Schermo GC9A01 | ESP32-S3 |
|---|---|
| VCC | 3.3V |
| GND | GND |
| SCL / CLK | GPIO12 |
| SDA / MOSI | GPIO11 |
| CS | GPIO9 |
| DC | GPIO10 |
| RST | GPIO18 |
| BL | GPIO7 (controllato dal codice) oppure diretto a 3.3V (alcune schede non hanno un controllo retroilluminazione separato) |
ESP32-S3 → sensore VL53L0X-V2
| VL53L0X-V2 | ESP32-S3 |
|---|---|
| VIN | 3.3V |
| GND | GND |
| SDA | GPIO13 |
| SCL | GPIO14 |
| GPIO1 | non collegato |
| XSHUT | non collegato (tenuto alto internamente di default) |
⚠️ Attenzione: i pin I2C predefiniti dell’ESP32-S3 sono in genere GPIO8 (SDA) / GPIO9 (SCL), ma in questo progetto GPIO9 è già occupato dal CS dello schermo, quindi l’I2C del sensore è stato spostato manualmente su GPIO13/GPIO14. Nel codice,
Wire.begin(I2C_SDA, I2C_SCL)specifica questi due pin: in fase di cablaggio non fare il furbo tornando ai pin predefiniti, altrimenti schermo e sensore si scontreranno e nessuno dei due funzionerà.
Librerie da installare
In Arduino IDE cerca e installa tramite il “Gestore librerie”:
Arduino_GFX_Library(autore moononournation) — versione testata v1.6.5Adafruit_VL53L0X(autore Adafruit) — versione testata v1.2.5; durante l’installazione ti chiederà di installare ancheAdafruit BusIO, installalo
Versione IDE: Arduino IDE 2.3.8, il pacchetto di supporto alla scheda ESP32 usato è il 3.3.10. Versioni troppo distanti potrebbero avere API incompatibili, ti consiglio di allinearti.
Codice completo
Programma principale del tachimetro
/*
* ═══════════════════════════════════════════════════════
* Tachimetro Cyber · Cyber Gauge Dashboard
* Display circolare GC9A01 (240×240) + VL53L0X-V2 misura distanza laser
* MCU: ESP32-S3
* Libreria driver: Arduino_GFX_Library v1.6.5
* ═══════════════════════════════════════════════════════
*/
#include <Arduino.h>
#include <Wire.h>
#include <Adafruit_VL53L0X.h>
#include <Arduino_GFX_Library.h>
// ───────── Definizione colori (in Arduino_GFX v1.6.5 vanno definiti a mano) ─────────
#define BLACK 0x0000
#define WHITE 0xFFFF
#define RED 0xF800
#define GREEN 0x07E0
#define BLUE 0x001F
#define CYAN 0x07FF
#define YELLOW 0xFFE0
#define ORANGE 0xFD20
#define DARKGREY 0x4208
#define LIGHTGREY 0xC618
// Colori tema cyber
#define CYBER_BG 0x0841 // Sfondo profondo
#define CYBER_PANEL 0x1082 // Colore pannello
#define CYBER_BLUE 0x06DF // Blu fluo
#define CYBER_CYAN 0x07F5 // Ciano fluo
#define CYBER_GREEN 0x47E0 // Verde fluo
#define CYBER_RED 0xF806 // Rosso di allarme
#define CYBER_ORANGE 0xFB40 // Arancione
#define CYBER_YELLOW 0xFF80 // Giallo
#define CYBER_DIM 0x4A49 // Colore smorzato
// ───────── Definizione pin ─────────
#define TFT_SCK 12
#define TFT_MOSI 11
#define TFT_CS 9
#define TFT_DC 10
#define TFT_RST 18
#define TFT_BL 7
// Il VL53L0X usa un I2C separato, per evitare il GPIO9 già usato dal TFT_CS
#define I2C_SDA 13
#define I2C_SCL 14
// ───────── Dimensioni schermo ─────────
#define SCREEN_W 240
#define SCREEN_H 240
#define CX 120 // Coordinata X del centro
#define CY 120 // Coordinata Y del centro
// ───────── Parametri del tachimetro ─────────
#define GAUGE_R 95 // Raggio dell'arco di scala
#define GAUGE_WIDTH 10 // Spessore dell'arco
#define NEEDLE_LEN 78 // Lunghezza dell'ago
#define START_ANGLE 135 // Angolo di partenza (gradi)
#define END_ANGLE 405 // Angolo di fine (gradi)
#define MAX_DIST 800 // Distanza massima visualizzata mm
#define MIN_DIST 20 // Distanza minima mm
#define TICK_COUNT 16 // Numero di tacche
// ───────── Oggetti globali ─────────
Arduino_DataBus *bus = new Arduino_ESP32SPI(
TFT_DC, TFT_CS, TFT_SCK, TFT_MOSI, -1 /* MISO */
);
Arduino_GFX *gfx = new Arduino_GC9A01(
bus, TFT_RST, 0 /* rotation */, true /* IPS */
);
Adafruit_VL53L0X lox = Adafruit_VL53L0X();
Arduino_Canvas *canvas; // Canvas offscreen, elimina lo sfarfallio
// ───────── Variabili di stato ─────────
float currentAngle = START_ANGLE;
float targetAngle = START_ANGLE;
int currentDist = 0;
int lastDist = -1;
// ═══════════════════════════════════════
// Funzioni di utilità
// ═══════════════════════════════════════
// Miscelazione di due colori RGB565
uint16_t blendColor(uint16_t c1, uint16_t c2, float t) {
uint8_t r1 = (c1 >> 11) & 0x1F, g1 = (c1 >> 5) & 0x3F, b1 = c1 & 0x1F;
uint8_t r2 = (c2 >> 11) & 0x1F, g2 = (c2 >> 5) & 0x3F, b2 = c2 & 0x1F;
uint8_t r = r1 + (r2 - r1) * t;
uint8_t g = g1 + (g2 - g1) * t;
uint8_t b = b1 + (b2 - b1) * t;
return (r << 11) | (g << 5) | b;
}
// Colore in base alla distanza (vicino=rosso, lontano=verde)
uint16_t getDistColor(int dist) {
float ratio = constrain((float)dist / MAX_DIST, 0.0, 1.0);
if (ratio < 0.15) return CYBER_RED;
if (ratio < 0.30) return blendColor(CYBER_RED, CYBER_ORANGE, (ratio - 0.15) / 0.15);
if (ratio < 0.50) return blendColor(CYBER_ORANGE, CYBER_YELLOW, (ratio - 0.30) / 0.20);
if (ratio < 0.70) return blendColor(CYBER_YELLOW, CYBER_CYAN, (ratio - 0.50) / 0.20);
return blendColor(CYBER_CYAN, CYBER_GREEN, (ratio - 0.70) / 0.30);
}
// Restituisce il testo di stato
const char* getStatusText(int dist) {
if (dist < 100) return "DANGER";
if (dist < 200) return "WARNING";
if (dist < 400) return "CAUTION";
if (dist < 600) return "SAFE";
return "CLEAR";
}
// ═══════════════════════════════════════
// Funzioni di disegno
// ═══════════════════════════════════════
// Disegna un arco spesso (simulato con segmenti corti)
void drawArc(Arduino_Canvas *c, int cx, int cy, int r,
float startDeg, float endDeg, int thickness,
uint16_t color) {
float step = 1.5; // Angolo per passo
for (float a = startDeg; a <= endDeg; a += step) {
float rad = a * DEG_TO_RAD;
int x = cx + cos(rad) * r;
int y = cy + sin(rad) * r;
c->fillCircle(x, y, thickness / 2, color);
}
}
// Disegna un arco sfumato
void drawGradientArc(Arduino_Canvas *c, int cx, int cy, int r,
float startDeg, float endDeg, int thickness) {
float totalAngle = endDeg - startDeg;
float step = 1.5;
for (float a = startDeg; a <= endDeg; a += step) {
float ratio = (a - startDeg) / totalAngle;
uint16_t color;
// Rosso -> arancione -> giallo -> ciano -> verde
if (ratio < 0.2) color = blendColor(CYBER_RED, CYBER_ORANGE, ratio / 0.2);
else if (ratio < 0.4) color = blendColor(CYBER_ORANGE, CYBER_YELLOW, (ratio - 0.2) / 0.2);
else if (ratio < 0.6) color = blendColor(CYBER_YELLOW, CYBER_CYAN, (ratio - 0.4) / 0.2);
else color = blendColor(CYBER_CYAN, CYBER_GREEN, (ratio - 0.6) / 0.4);
float rad = a * DEG_TO_RAD;
int x = cx + cos(rad) * r;
int y = cy + sin(rad) * r;
c->fillCircle(x, y, thickness / 2, color);
}
}
// Disegna le tacche di scala
void drawTicks(Arduino_Canvas *c) {
float totalAngle = END_ANGLE - START_ANGLE;
for (int i = 0; i <= TICK_COUNT; i++) {
float angle = START_ANGLE + (float)i / TICK_COUNT * totalAngle;
float rad = angle * DEG_TO_RAD;
float ratio = (float)i / TICK_COUNT;
// Colore della tacca
uint16_t color;
if (ratio < 0.2) color = CYBER_RED;
else if (ratio < 0.4) color = CYBER_ORANGE;
else if (ratio < 0.6) color = CYBER_YELLOW;
else if (ratio < 0.8) color = CYBER_CYAN;
else color = CYBER_GREEN;
// Tacca lunga/corta
bool isMajor = (i % 4 == 0);
int innerR = GAUGE_R + 4;
int outerR = innerR + (isMajor ? 12 : 6);
int thick = isMajor ? 2 : 1;
int x1 = CX + cos(rad) * innerR;
int y1 = CY + sin(rad) * innerR;
int x2 = CX + cos(rad) * outerR;
int y2 = CY + sin(rad) * outerR;
// Disegna la tacca
for (int t = 0; t < thick; t++) {
c->drawLine(x1 + t, y1, x2 + t, y2, color);
}
// Etichetta numerica sulle tacche principali
if (isMajor) {
int labelR = outerR + 12;
int lx = CX + cos(rad) * labelR;
int ly = CY + sin(rad) * labelR;
int val = (float)i / TICK_COUNT * MAX_DIST;
c->setTextColor(CYBER_DIM);
c->setTextSize(1);
c->setCursor(lx - 8, ly - 4);
c->print(val);
}
}
}
// Disegna l'ago
void drawNeedle(Arduino_Canvas *c, float angleDeg, uint16_t color) {
float rad = angleDeg * DEG_TO_RAD;
// Punta dell'ago
int tipX = CX + cos(rad) * NEEDLE_LEN;
int tipY = CY + sin(rad) * NEEDLE_LEN;
// Base dell'ago (due punti perpendicolari alla direzione dell'ago)
float perpRad = rad + PI / 2;
int baseW = 4;
int bx1 = CX + cos(perpRad) * baseW;
int by1 = CY + sin(perpRad) * baseW;
int bx2 = CX - cos(perpRad) * baseW;
int by2 = CY - sin(perpRad) * baseW;
// Disegna l'ago triangolare
c->fillTriangle(tipX, tipY, bx1, by1, bx2, by2, color);
// Ghiera centrale decorativa
c->fillCircle(CX, CY, 7, CYBER_PANEL);
c->drawCircle(CX, CY, 7, color);
c->fillCircle(CX, CY, 3, color);
}
// Disegna l'intero tachimetro
void drawDashboard(int dist) {
canvas->fillScreen(CYBER_BG);
// Ghiera esterna decorativa
canvas->drawCircle(CX, CY, 118, CYBER_PANEL);
// Arco di sfondo (binario scuro)
drawArc(canvas, CX, CY, GAUGE_R,
START_ANGLE, END_ANGLE, GAUGE_WIDTH, CYBER_PANEL);
// Arco sfumato (completo)
drawGradientArc(canvas, CX, CY, GAUGE_R,
START_ANGLE, END_ANGLE, GAUGE_WIDTH);
// Tacche
drawTicks(canvas);
// Calcola l'angolo dell'ago
float ratio = constrain((float)dist / MAX_DIST, 0.0, 1.0);
targetAngle = START_ANGLE + ratio * (END_ANGLE - START_ANGLE);
// Interpolazione smussata
currentAngle += (targetAngle - currentAngle) * 0.15;
// Recupera il colore
uint16_t needleColor = getDistColor(dist);
// Disegna l'ago
drawNeedle(canvas, currentAngle, WHITE);
// ── Area numerica centrale ──
// Valore della distanza
canvas->setTextColor(WHITE);
canvas->setTextSize(3);
String distStr = String(dist);
int textW = distStr.length() * 18;
canvas->setCursor(CX - textW / 2, CY + 16);
canvas->print(distStr);
// Unità
canvas->setTextColor(CYBER_DIM);
canvas->setTextSize(1);
canvas->setCursor(CX - 6, CY + 42);
canvas->print("mm");
// Titolo
canvas->setTextColor(CYBER_DIM);
canvas->setTextSize(1);
canvas->setCursor(CX - 30, CY - 28);
canvas->print("LASER RANGE");
// Indicatore di stato
canvas->setTextColor(needleColor);
canvas->setTextSize(1);
const char* status = getStatusText(dist);
int sLen = strlen(status);
canvas->setCursor(CX - sLen * 3, CY + 56);
canvas->print(status);
// Invia allo schermo
canvas->flush();
}
// ═══════════════════════════════════════
// setup() & loop()
// ═══════════════════════════════════════
void setup() {
Serial.begin(115200);
Serial.println("\n═══ Cyber Gauge Dashboard ═══");
// Primo passo: accendi la retroilluminazione
pinMode(TFT_BL, OUTPUT);
digitalWrite(TFT_BL, HIGH);
// Secondo passo: inizializza lo schermo
gfx->begin();
gfx->fillScreen(BLACK);
gfx->setRotation(0);
// Terzo passo: crea il canvas offscreen (doppio buffer anti-sfarfallio)
canvas = new Arduino_Canvas(SCREEN_W, SCREEN_H, gfx);
canvas->begin();
// Schermata di avvio
canvas->fillScreen(CYBER_BG);
canvas->setTextColor(CYBER_BLUE);
canvas->setTextSize(2);
canvas->setCursor(40, 100);
canvas->print("CYBER");
canvas->setCursor(40, 125);
canvas->print("GAUGE");
canvas->setTextColor(CYBER_DIM);
canvas->setTextSize(1);
canvas->setCursor(55, 160);
canvas->print("Booting...");
canvas->flush();
delay(1000);
// Quarto passo: inizializza I2C e sensore (usa pin personalizzati, non quelli predefiniti)
Wire.begin(I2C_SDA, I2C_SCL);
if (!lox.begin()) {
Serial.println("Inizializzazione VL53L0X fallita!");
canvas->fillScreen(CYBER_BG);
canvas->setTextColor(CYBER_RED);
canvas->setTextSize(1);
canvas->setCursor(50, 110);
canvas->print("SENSOR ERROR");
canvas->setCursor(40, 130);
canvas->print("Check wiring!");
canvas->flush();
while (1) delay(100);
}
Serial.println("VL53L0X pronto ✓");
// Quinto passo: avvia la modalità di misura continua
lox.startRangeContinuous();
Serial.println("Avvio tachimetro completato!");
}
void loop() {
// Leggi la distanza
if (lox.isRangeComplete()) {
int dist = lox.readRange();
// Filtra i valori non validi
if (dist > 0 && dist < 8190) {
// Filtro di smussatura semplice, per evitare numeri ballerini
currentDist = currentDist * 0.7 + dist * 0.3;
currentDist = constrain(currentDist, MIN_DIST, MAX_DIST);
// Ridisegna solo quando la distanza cambia oltre una soglia, per risparmiare prestazioni
if (abs(currentDist - lastDist) > 2) {
drawDashboard(currentDist);
lastDist = currentDist;
Serial.printf("Distanza: %d mm\n", currentDist);
}
}
}
delay(30); // ~33 FPS
}
Sketch di test del sensore (consigliato eseguirlo prima)
Prima di lanciare il programma principale, ti consiglio vivamente di caricare prima questo sketch minimale per confermare che il sensore funzioni: se qualcosa va storto, sarà più facile isolarlo senza dover pescare nel mucchio di codice di disegno.
/*
* Test del sensore VL53L0X
*/
#include <Wire.h>
#include <Adafruit_VL53L0X.h>
#define I2C_SDA 13
#define I2C_SCL 14
Adafruit_VL53L0X lox = Adafruit_VL53L0X();
void setup() {
Serial.begin(115200);
delay(1000);
Serial.println("Test del sensore VL53L0X");
Wire.begin(I2C_SDA, I2C_SCL);
if (!lox.begin()) {
Serial.println("❌ Sensore non trovato, controlla il cablaggio!");
while (1);
}
Serial.println("✓ Sensore pronto, inizio misurazione...");
lox.startRangeContinuous();
}
void loop() {
if (lox.isRangeComplete()) {
int dist = lox.readRange();
Serial.printf("Distanza: %d mm\n", dist);
}
delay(100);
}
Spiegazione del codice
Ecco alcuni punti chiave che rischiano di far venire le vertigini, li isoliamo:
blendColor(): mescola due colori RGB565 in proporzionet, serve per realizzare l’arco sfumato rosso→arancione→giallo→ciano→verde. Invece di saltare da un colore all’altro, appare fluido.Arduino_Canvas(canvas offscreen): tutto viene prima disegnato su un canvas in memoria e infine inviato allo schermo in un colpo solo conflush(), invece di disegnare tratto per tratto direttamente a schermo — senza questo accorgimento, durante la rotazione dell’ago vedresti sfarfallii e strappi evidenti.- Filtro di smussatura
currentDist * 0.7 + dist * 0.3: le letture grezze del sensore hanno piccole oscillazioni; qui applichiamo un semplice filtro passa-basso del primo ordine per rendere il movimento dell’ago più fluido e non farlo sobbalzare. I2C_SDA=13, I2C_SCL=14: l’insidia già ribadita più volte nella sezione cablaggio, la ribadiamo ancora — non sono i pin I2C predefiniti dell’ESP32-S3, sono stati cambiati a mano perché il GPIO9 predefinito è occupato dal CS dello schermo.
Risoluzione dei problemi comuni
Niente panico, l’80% dei problemi si risolve qui:
-
Dopo il flash lo schermo resta nero Controlla prima che
TFT_BL(retroilluminazione) sia collegato bene o che nel codice venga eseguitodigitalWrite(TFT_BL, HIGH); poi verifica che il pin RST non abbia un contatto lasco: un RST allentato è la causa più comune di schermo nero sui display circolari. -
La porta seriale stampa “Inizializzazione VL53L0X fallita!” Nel 99% dei casi è un problema di cablaggio: verifica che VIN/GND non siano invertiti, che SDA/SCL siano davvero su GPIO13/GPIO14 (e non sui GPIO8/9 predefiniti) e che i cavetti jumper non siano laschi. Puoi prima lanciare lo “sketch di test del sensore” da solo per escludere le interferenze dello schermo.
-
Lo schermo si accende, ma ci sono disturbi/strisce/colori sbagliati Probabilmente la linea di clock SPI o quella dati hanno un contatto lasco, oppure i cavetti jumper sono troppo lunghi e il segnale si degrada. Verifica che SCL/SDA corrispondano a GPIO12/GPIO11 e tieni i cavetti entro i 15 cm.
-
L’ago salta all’impazzata e i numeri cambiano di continuo Il coefficiente del filtro non basta oppure davanti al sensore ci sono oggetti riflettenti/trasparenti che creano disturbo. Puoi cambiare i pesi
currentDist * 0.7 + dist * 0.3in0.85/0.15: il filtro diventa più forte (al prezzo di una risposta più lenta). -
Errore di compilazione: non trova
Adafruit_VL53L0X.hoArduino_GFX_Library.hSignifica che la libreria non è installata correttamente: cerca il nome esatto nel Gestore librerie e reinstallala, attenzione a non installare una fork di terze parti con lo stesso nome. -
L’angolo dell’ago o i numeri di scala non corrispondono Verifica che
MAX_DISTnon sia stato ridotto senza aggiornare di conseguenza le etichette di scala: i due devono rimanere coerenti, altrimenti i numeri della scala e la posizione effettiva dell’ago risulteranno sfasati.
FAQ
D: Quali sono i pin I2C predefiniti dell’ESP32-S3? R: Di solito GPIO8 (SDA) e GPIO9 (SCL), ma in questo progetto GPIO9 è occupato dal CS dello schermo, quindi l’I2C del sensore è stato spostato su GPIO13/GPIO14.
D: Fino a che distanza riesce a misurare il VL53L0X e con che precisione? R: La portata effettiva dichiarata è circa 30mm~1200mm (in modalità long range fino a 2000mm), con una precisione di circa ±3%.
D: Il GC9A01 circolare supporta il touch? R: Il GC9A01 è solo un chip display driver, senza funzionalità touch; alcuni moduli sul mercato integrano un chip touch capacitivo aggiuntivo, verifica il modello specifico prima di acquistarlo se vuoi la versione touch.
D: Il laser del VL53L0X fa male agli occhi? R: No, è un prodotto laser Class 1, con lunghezza d’onda 940nm invisibile a occhio nudo e potenza estremamente bassa, conforme agli standard di sicurezza per l’occhio umano: nell’uso normale non c’è nulla da temere.
D: Lo schermo GC9A01 non si accende ma l’alimentazione è a posto, perché? R: La causa più comune è il contatto lasco del pin RST (reset) oppure il pin BL della retroilluminazione non tirato alto: controlla prima questi due punti.
D: Perché nel codice si usa il canvas offscreen Arduino_Canvas invece di disegnare direttamente sullo schermo?
R: Disegnare direttamente sullo schermo provoca sfarfallii e strappi evidenti durante la rotazione dell’ago e il ridisegno dell’arco; usando il canvas come doppio buffer e facendo un unico flush alla fine, l’immagine risulta pulita.
D: Ci sono differenze tra VL53L0X-V2 e il VL53L0X normale? R: Il principio di misura e la piedinatura sono identici; la V2 di solito è una revisione del produttore del modulo su layout PCB e circuito di stabilizzazione della tensione. Per i dettagli, fai riferimento alla documentazione del modulo specifico che hai acquistato.
D: L’alimentazione USB dell’ESP32-S3 basta per questo progetto? R: Sì, basta: il consumo complessivo di schermo e sensore è basso, una normale alimentazione USB 5V/500mA non ha problemi.
Idee per estendere il progetto
- Collega un buzzer e fai suonare un allarme quando la distanza entra nella zona DANGER: in un attimo diventa un rudimentale sensore di parcheggio
- Salva i dati storici di distanza e disegna un grafico in tempo reale per osservare la traiettoria di un oggetto in movimento
- Aggiungi due pulsanti per cambiare l’unità di visualizzazione (mm / cm / inch)
- Stampaci un case, attaccalo con una ventosa al parabrezza e usalo davvero come sensore di retromarcia