ESP32-S3 con schermo circolare GC9A01 + MQ135: guida completa per dashboard qualità dell'aria (LVGL v9 + interfaccia SPI + Arduino C++)
ESP32-S3 + sensore di gas MQ135 + schermo circolare GC9A01 da 1,28 pollici con LVGL v9 per creare una dashboard qualità dell'aria con arco animato, grafico a trend in tempo reale e effetto glow pulsante, inclusi cablaggio completo, codice e risoluzione problemi.

Difficoltà: ⭐⭐☆☆☆ (basta qualche cavo dupont per iniziare) Tempo stimato: 45 minuti Ambiente di test: Arduino IDE 2.3.8 · ESP32 Arduino Core 3.3.10 · lvgl v9.5.0 · Arduino_GFX_Library v1.6.5
TL;DR (vuoi solo farlo funzionare? leggi qui)
Gestione delle aspettative: questo progetto è solo a scopo educativo, da tavolo e puro piacere visivo. Non usarlo mai per rilevare davvero fughe di gas pericolose! La sua precisione è più o meno “alchemica”.
- Cablaggio: MQ135 A0 → GPIO 13; GC9A01 collegato come da tabella a GPIO 7 / 9 / 10 / 11 / 12 / 18
- Librerie: cerca
lvgl(scegli v9.x) +Arduino_GFX_Librarynel gestore librerie Arduino- Configura lv_conf.h: attiva
LV_FONT_MONTSERRAT_14eLV_FONT_MONTSERRAT_28(cambia 0 → 1)- Flash → lo schermo si accende, l’indicatore inizia a girare
Introduzione
Tra i miei sensori che raccoglievano polvere ne ho trovato uno specializzato nel monitoraggio della qualità dell’aria: il modulo MQ135. Volevo verificare la qualità dell’aria nel mio laboratorio, quindi l’ho collegato per fare qualche prova. Il manuale diceva che questo modulo richiede 24 ore di preriscaldamento, quindi mi sembrava più un giocattolo. Tuttavia, questo modulo è sensibile a diversi gas; anche se non necessariamente preciso, quando il valore aumenta significa che qualche gas è presente, potrebbe essere anidride carbonica, ammoniaca, benzene, alcol, fumo. Per giudicare se una stanza necessita ventilazione basandosi su valori relativi, dovrebbe andare bene.
Così è nato questo progetto: ESP32-S3 + sensore di gas MQ135 + schermo circolare GC9A01 da 1,28 pollici, con la famosa libreria grafica LVGL v9, per creare un indicatore di qualità dell’aria con arco, grafico a trend in tempo reale e che “respira” cambiando colore.
Obiettivo di questo articolo: dallo zero al funzionamento completo, riprodurre interamente questo effetto.
Risultato sperimentale
Lo schermo circolare mostra in tempo reale il valore ADC della qualità dell’aria attuale, lo stato di qualità (ECCellenTE / BUONO / ACCETtabile / MODERATO / SCARSO / PERICOLO) e il grafico storico del trend; il colore dell’indicatore passa dal verde al rosco in base alla qualità dell’aria, con un effetto glow “respirante” sul bordo esterno. Nell’angolo in basso a sinistra dello schermo vengono registrati anche i valori minimi e massimi dall’accensione.
---
Descrizione dei componenti
La scheda di sviluppo (ESP32-S3) non viene presentata in questo articolo, di seguito sono descritti solo i due moduli che i principianti potrebbero non aver mai utilizzato.
Sensore di gas MQ135
Il MQ135 è un sensore gas che rileva le variazioni di concentrazione di gas nocivi come CO₂, ammoniaca, benzene nell’aria. In questo progetto serve per emettere un valore ADC analogico 0-4095 che riflette il livello di qualità dell’ambiente attuale.
In parole povere: è un “naso” chimico, più l’aria è inquinata, più alta è la tensione in uscita e maggiore è il valore ADC.
| Parametro | Valore |
|---|---|
| Tensione di lavoro standard | 5V (filo riscaldante) / uscita analogica compatibile 3,3V |
| Interfaccia di uscita | Analogica (A0) + Digitale (D0) |
| Tempo di preriscaldamento | 24-48 ore (precisione completa) / circa 3 minuti (riferimento trend) |
| Gas rilevabili | CO₂, NH₃, NOₓ, benzene, alcol, fumo |
Informazioni sull’alimentazione 3,3V: La tensione standard del MQ135 è 5V; con alimentazione 3,3V la potenza del filo riscaldante è circa il 44% dello standard, la sensibilità diminuisce e le letture sono più basse, ma è sufficiente per mostrare il trend e rilevare variazioni relative. Per la massima precisione, si consiglia di alimentare VCC con 5V separatamente; l’uscita analogica A0 non supera 3,3V, quindi può essere collegata direttamente all’ESP32-S3 senza partitore di tensione.
Motivo della scelta: economico (meno di 5 yuan), modulare, pronto all’uso con pochi cablaggi, sufficiente per questo progetto “estetico”.
Utilizzo corretto del MQ135 per giudizi indoor
✅ Adatto per:
- Monitoraggio trend della qualità dell'aria (valori relativi)
- Determinazione soglie per attivare ventilazione/allarme
- Indicatore di "inquinamento complessivo" da più gas nocivi
❌ Non adatto per:
- Misurazione precisa di concentrazione di singolo gas
- Verifica di sicurezza di livello medico/industriale
- Valori precisi di CO₂ (errore fino a ±300ppm o più)
Schermo TFT circolare GC9A01 da 1,28 pollici
Il GC9A01 è uno schermo TFT LCD circolare da 1,28 pollici che riceve dati immagine tramite interfaccia SPI e li renderizza. In questo progetto serve per mostrare l’interfaccia UI dell’indicatore con effetti animati.
Analogia: è quel tipo di quadrante circolare sugli smartwatch su cui puoi disegnare contenuti liberamente.
| Parametro | Valore |
|---|---|
| Dimensione schermo | 1,28 pollici |
| Risoluzione | 240 × 240 pixel |
| Interfaccia | SPI (fino a 80 MHz) |
| Chip driver | GC9A01 |
| Tensione di lavoro | 3,3V |
| Controllo retroilluminazione | Supportato (pin BL, dimmerazione PWM possibile) |
Motivo della scelta: aspetto circolare unico, dimensioni compatte, uso diretto a 3,3V, supporto nativo da Arduino_GFX_Library, con LVGL fa un figurone per l’effetto visivo dell’indicatore.
BOM (Bill of Materials)
| Componente | Modello / Specifiche | Quantità |
|---|---|---|
| Scheda principale | ESP32-S3 (con USB-C) | 1 |
| Schermo TFT circolare | GC9A01 1,28“ 240×240 | 1 |
| Sensore gas | Modulo MQ135 | 1 |
| Cavi di connessione | Cavi dupont | Alcuni |
Descrizione pin dei componenti
Pin del modulo MQ135
| Pin | Descrizione |
|---|---|
| VCC | Alimentazione (in questo progetto a 3,3V, standard è 5V) |
| GND | Terra |
| A0 | Uscita segnale analogico, collegare a pin ADC dell’ESP32-S3 |
| D0 | Uscita digitale (non usata in questo progetto) restituisce livello alto/basso (HIGH / LOW) |
Pin del modulo GC9A01
| Etichetta pin | Descrizione |
|---|---|
| VCC | Alimentazione 3,3V |
| GND | Terra |
| SCL / CLK | Clock SPI |
| SDA / MOSI | Dati SPI |
| CS | Chip Select (attivo basso) |
| DC | Selezione dati/comando |
| RST | Reset (reset attivo basso) |
| BL | Controllo retroilluminazione (HIGH = acceso) (opzionale, non tutti i moduli lo hanno) |
Schema di collegamento
MQ135 → ESP32-S3
| MQ135 | ESP32-S3 |
|---|---|
| VCC | 5V |
| GND | GND |
| A0 | GPIO 13 |
GC9A01 → ESP32-S3
| Pin GC9A01 | GPIO ESP32-S3 |
|---|---|
| VCC | 3,3V |
| GND | GND |
| SCL / CLK | GPIO 12 |
| SDA / MOSI | GPIO 11 |
| CS | GPIO 9 |
| DC | GPIO 10 |
| RST | GPIO 18 |
| BL (retroilluminazione) | GPIO 7 (se presente, altrimenti non collegare) |
Promemoria pratico: Dopo il cablaggio, confronta riga per riga con le due tabelle sopra, puoi risparmiare l’80% del tempo di debug. L’errore più frequente è invertire DC e CS - una volta scambiati, lo schermo diventa tutto bianco o tutto nero, sembra “rotto”, ma in realtà i cavi sono solo sbagliati.
Librerie da installare
Apri Arduino IDE → Strumenti → Gestione librerie, cerca e installa queste due:
| Libreria | Autore | Versione testata in questo articolo |
|---|---|---|
lvgl |
LVGL | v9.5.0 |
Arduino_GFX_Library |
Moon On Our Nation | v1.6.5 |
Dopo aver installato lvgl, c’è un passaggio obbligatorio:
- Trova la directory della libreria lvgl (solitamente in
Documenti/Arduino/libraries/lvgl/) - Copia
lv_conf_template.hche c’è dentro, rinominala inlv_conf.h, mettila nella stessa directory dilvgl/ - Apri
lv_conf.h, trova queste due righe, cambia0in1:#define LV_FONT_MONTSERRAT_14 1 #define LV_FONT_MONTSERRAT_28 1 - Apri
lv_conf.h, trova all’inizio#if 0e cambialo in#if 1
Se dimentichi questo passaggio e fai direttamente il flash, la compilazione darà errore
lv_font_montserrat_28 undeclared. Non chiedermi come lo so.
Codice completo
/*
* ESP32-S3 + GC9A01 dashboard qualità dell'aria su schermo circolare v3.1
* "Stile tech minimale" - arco di progresso + grafico trend real-time + glow pulsante
*
* Ambiente di test: Arduino IDE 2.3.8 / ESP32 Core 3.3.10
* Librerie dipendenti: lvgl v9.5.0 + Arduino_GFX_Library v1.6.5
*/
#include <Arduino.h>
#include <lvgl.h>
#include <Arduino_GFX_Library.h>
#include <math.h>
// ===================== Definizione pin =====================
#define TFT_SCK 12 // Clock SPI
#define TFT_MOSI 11 // Dati SPI
#define TFT_CS 9 // Chip Select
#define TFT_DC 10 // Selezione dati/comando (se invertito lo schermo diventa tutto bianco)
#define TFT_RST 18 // Reset
#define TFT_BL 7 // Retroilluminazione - deve essere HIGH per accendersi, se dimentichi questo pin è inutile
#define MQ135_PIN 13 // Ingresso analogico MQ135 (canale ADC2, funziona normalmente senza Wi-Fi)
#define SCREEN_WIDTH 240
#define SCREEN_HEIGHT 240
// ===================== Inizializzazione driver display =====================
Arduino_ESP32SPI bus = Arduino_ESP32SPI(TFT_DC, TFT_CS, TFT_SCK, TFT_MOSI, -1);
Arduino_GC9A01 gfx = Arduino_GC9A01(&bus, TFT_RST, 0, true);
// ===================== Buffer disegno LVGL =====================
// 40 righe di buffer occupano circa 19KB su ESP32-S3, buon equilibrio velocità/memoria
#define DRAW_BUF_LINES 40
alignas(4) static uint16_t draw_buf[SCREEN_WIDTH * DRAW_BUF_LINES];
// ===================== Dati storici trend =====================
#define TREND_POINTS 40 // Mantiene gli ultimi 40 punti di campionamento (× 300ms ≈ 12 secondi di storia su schermo)
static int trendData[TREND_POINTS] = {0};
static int trendIdx = 0;
static bool trendFull = false;
static lv_point_precise_t trendLinePoints[TREND_POINTS];
// ===================== Handle oggetti UI LVGL =====================
static lv_obj_t *arc_bg; // Sfondo arco traccia (colore scuro)
static lv_obj_t *arc_main; // Arco principale + piccolo pallino knob all'estremità
static lv_obj_t *glow_circle; // Cerchio bordo glow esterno (respira)
static lv_obj_t *center_circle; // Piastra base disco centrale
static lv_obj_t *label_value; // Numero grande centrale (valore ADC)
static lv_obj_t *label_unit; // Etichetta unità "ADC"
static lv_obj_t *label_status; // Testo stato (ECCellenTE / BUONO...)
static lv_obj_t *dot_status; // Pallino stato
static lv_obj_t *label_title; // Titolo superiore "AIR QUALITY"
static lv_obj_t *label_score; // Punteggio pulizia inferiore
static lv_obj_t *label_minmax; // Valori min/max
static lv_obj_t *trend_line; // Linea trend
static lv_obj_t *trend_container; // Container ritaglio linea
// ===================== Stato sensore =====================
static float smoothedValue = 0.0f; // Valore mediato per ponderazione esponenziale
static bool firstSample = true; // Flag primo frame, evita animazione che parte da 0
static int minValue = 4095; // Valore ADC minimo dall'accensione
static int maxValue = 0; // Valore ADC massimo dall'accensione
static float displayValue = 0.0f; // Per interpolazione animazione UI
// ===================== Callback timer LVGL =====================
static uint32_t my_tick_cb(void) { return millis(); }
// ===================== Callback flush: LVGL finisce di renderizzare un'area e la invia allo schermo =====================
void my_disp_flush(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map) {
uint32_t w = area->x2 - area->x1 + 1;
uint32_t h = area->y2 - area->y1 + 1;
gfx.draw16bitRGBBitmap(area->x1, area->y1, (uint16_t *)px_map, w, h);
lv_display_flush_ready(disp); // Dice a LVGL: quest'area è finita, puoi continuare con la prossima
}
// ===================== Sistema colori: valore ADC → colore stato =====================
// Valore più alto = aria peggiore = colore più rosso, sei livelli corrispondono a sei stati
uint32_t getColorHex(int v) {
if (v < 600) return 0x00E5A0; // ECCellenTE: verde fresco
if (v < 1200) return 0x22C55E; // BUONO: verde chiaro
if (v < 2000) return 0xA3E635; // ACCETTabile: verde-giallo
if (v < 2800) return 0xEAB308; // MODERATO: giallo
if (v < 3500) return 0xF97316; // SCARSO: arancione
return 0xFF3355; // PERICOLO: rosso (apri subito le finestre)
}
lv_color_t getColor(int v) {
return lv_color_hex(getColorHex(v));
}
// Colore di base arco traccia (versione scura del colore stato, con sfondo scuro)
uint32_t getDimColorHex(int v) {
if (v < 600) return 0x0A2A20;
if (v < 1200) return 0x0A2A15;
if (v < 2000) return 0x1A2A10;
if (v < 2800) return 0x2A2208;
if (v < 3500) return 0x2A1808;
return 0x2A0A10;
}
const char* getStatusText(int v) {
if (v < 600) return "ECCellenTE";
if (v < 1200) return "BUONO";
if (v < 2000) return "ACCETTabile";
if (v < 2800) return "MODERATO";
if (v < 3500) return "SCARSO";
return "PERICOLO";
}
// Conversione valore ADC in percentuale pulizia (ADC più basso = più pulito = punteggio più alto)
int adcToScore(int adc) {
adc = constrain(adc, 0, 4095);
return constrain(100 - (adc * 100 / 4095), 0, 100);
}
// ===================== Creazione interfaccia UI =====================
void create_ui() {
lv_obj_t *scr = lv_screen_active();
// Primo passaggio: sfondo scuro
lv_obj_set_style_bg_opa(scr, LV_OPA_COVER, 0);
lv_obj_set_style_bg_color(scr, lv_color_hex(0x050810), 0);
// Secondo passaggio: bordo glow esterno più esterno (colore segue stato, animazione respirante)
glow_circle = lv_obj_create(scr);
lv_obj_remove_style_all(glow_circle);
lv_obj_set_size(glow_circle, 234, 234);
lv_obj_center(glow_circle);
lv_obj_set_style_radius(glow_circle, LV_RADIUS_CIRCLE, 0);
lv_obj_set_style_bg_opa(glow_circle, LV_OPA_TRANSP, 0);
lv_obj_set_style_border_width(glow_circle, 2, 0);
lv_obj_set_style_border_opa(glow_circle, LV_OPA_20, 0);
lv_obj_set_style_border_color(glow_circle, lv_color_hex(0x00E5A0), 0);
lv_obj_set_style_shadow_width(glow_circle, 30, 0);
lv_obj_set_style_shadow_spread(glow_circle, 2, 0);
lv_obj_set_style_shadow_opa(glow_circle, LV_OPA_30, 0);
lv_obj_set_style_shadow_color(glow_circle, lv_color_hex(0x00E5A0), 0);
lv_obj_clear_flag(glow_circle, LV_OBJ_FLAG_SCROLLABLE);
// Terzo passaggio: colore base arco traccia (mostra area scura "non ancora raggiunta")
arc_bg = lv_arc_create(scr);
lv_obj_remove_style_all(arc_bg);
lv_obj_set_size(arc_bg, 210, 210);
lv_obj_center(arc_bg);
lv_arc_set_range(arc_bg, 0, 100);
lv_arc_set_bg_angles(arc_bg, 135, 45);
lv_arc_set_value(arc_bg, 0);
lv_obj_set_style_arc_width(arc_bg, 18, LV_PART_MAIN);
lv_obj_set_style_arc_color(arc_bg, lv_color_hex(0x0A2A20), LV_PART_MAIN);
lv_obj_set_style_arc_rounded(arc_bg, true, LV_PART_MAIN);
lv_obj_set_style_arc_width(arc_bg, 0, LV_PART_INDICATOR);
lv_obj_set_style_arc_opa(arc_bg, LV_OPA_TRANSP, LV_PART_INDICATOR);
lv_obj_set_style_bg_opa(arc_bg, LV_OPA_TRANSP, LV_PART_KNOB);
lv_obj_clear_flag(arc_bg, LV_OBJ_FLAG_CLICKABLE);
// Quarto passaggio: arco principale (valore real-time + piccolo pallino knob all'estremità)
arc_main = lv_arc_create(scr);
lv_obj_remove_style_all(arc_main);
lv_obj_set_size(arc_main, 210, 210);
lv_obj_center(arc_main);
lv_arc_set_range(arc_main, 0, 4095);
lv_arc_set_bg_angles(arc_main, 135, 45);
lv_arc_set_value(arc_main, 0);
lv_obj_set_style_arc_width(arc_main, 18, LV_PART_MAIN);
lv_obj_set_style_arc_opa(arc_main, LV_OPA_TRANSP, LV_PART_MAIN);
lv_obj_set_style_arc_width(arc_main, 18, LV_PART_INDICATOR);
lv_obj_set_style_arc_color(arc_main, lv_color_hex(0x00E5A0), LV_PART_INDICATOR);
lv_obj_set_style_arc_rounded(arc_main, true, LV_PART_INDICATOR);
// knob = piccolo punto luminoso all'estremità, bordo bianco + interno riempito colore stato + ombra glow
lv_obj_set_style_bg_color(arc_main, lv_color_hex(0x00E5A0), LV_PART_KNOB);
lv_obj_set_style_bg_opa(arc_main, LV_OPA_COVER, LV_PART_KNOB);
lv_obj_set_style_pad_all(arc_main, 5, LV_PART_KNOB);
lv_obj_set_style_radius(arc_main, LV_RADIUS_CIRCLE, LV_PART_KNOB);
lv_obj_set_style_border_width(arc_main, 3, LV_PART_KNOB);
lv_obj_set_style_border_color(arc_main, lv_color_hex(0xFFFFFF), LV_PART_KNOB);
lv_obj_set_style_border_opa(arc_main, LV_OPA_COVER, LV_PART_KNOB);
lv_obj_set_style_shadow_width(arc_main, 18, LV_PART_KNOB);
lv_obj_set_style_shadow_color(arc_main, lv_color_hex(0x00E5A0), LV_PART_KNOB);
lv_obj_set_style_shadow_opa(arc_main, LV_OPA_70, LV_PART_KNOB);
lv_obj_set_style_shadow_spread(arc_main, 2, LV_PART_KNOB);
lv_obj_clear_flag(arc_main, LV_OBJ_FLAG_CLICKABLE);
// Quinto passaggio: disco centrale (contiene valore, linea trend, testo stato)
center_circle = lv_obj_create(scr);
lv_obj_remove_style_all(center_circle);
lv_obj_set_size(center_circle, 140, 140);
lv_obj_center(center_circle);
lv_obj_set_style_radius(center_circle, LV_RADIUS_CIRCLE, 0);
lv_obj_set_style_bg_opa(center_circle, LV_OPA_COVER, 0);
lv_obj_set_style_bg_color(center_circle, lv_color_hex(0x080E1A), 0);
lv_obj_set_style_bg_grad_color(center_circle, lv_color_hex(0x0C1628), 0);
lv_obj_set_style_bg_grad_dir(center_circle, LV_GRAD_DIR_VER, 0);
lv_obj_set_style_border_width(center_circle, 1, 0);
lv_obj_set_style_border_color(center_circle, lv_color_hex(0x1A3050), 0);
lv_obj_set_style_border_opa(center_circle, LV_OPA_60, 0);
lv_obj_set_style_pad_all(center_circle, 0, 0);
lv_obj_clear_flag(center_circle, LV_OBJ_FLAG_SCROLLABLE);
// Numero grande centrale
label_value = lv_label_create(center_circle);
lv_label_set_text(label_value, "0");
lv_obj_set_style_text_font(label_value, &lv_font_montserrat_28, 0);
lv_obj_set_style_text_color(label_value, lv_color_hex(0x00E5A0), 0);
lv_obj_align(label_value, LV_ALIGN_CENTER, 0, -26);
// Etichetta unità
label_unit = lv_label_create(center_circle);
lv_label_set_text(label_unit, "ADC");
lv_obj_set_style_text_font(label_unit, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_unit, lv_color_hex(0x506878), 0);
lv_obj_align(label_unit, LV_ALIGN_CENTER, 0, -6);
// Container linea trend (responsabile ritaglio, evita che la linea esca dai bordi)
trend_container = lv_obj_create(center_circle);
lv_obj_remove_style_all(trend_container);
lv_obj_set_size(trend_container, 110, 30);
lv_obj_align(trend_container, LV_ALIGN_CENTER, 0, 16);
lv_obj_set_style_bg_opa(trend_container, LV_OPA_TRANSP, 0);
lv_obj_set_style_pad_all(trend_container, 0, 0);
lv_obj_set_style_clip_corner(trend_container, true, 0);
lv_obj_set_style_radius(trend_container, 4, 0);
lv_obj_clear_flag(trend_container, LV_OBJ_FLAG_SCROLLABLE);
// Linea base riferimento sotto la linea trend
static lv_point_precise_t refPts[2] = {{0, 28}, {110, 28}};
lv_obj_t *refLine = lv_line_create(trend_container);
lv_line_set_points(refLine, refPts, 2);
lv_obj_set_style_line_color(refLine, lv_color_hex(0x1A2535), 0);
lv_obj_set_style_line_width(refLine, 1, 0);
// Linea trend (inizializza tutti i punti in basso)
for (int i = 0; i < TREND_POINTS; i++) {
trendLinePoints[i].x = (int32_t)(i * 110 / (TREND_POINTS - 1));
trendLinePoints[i].y = 28;
}
trend_line = lv_line_create(trend_container);
lv_line_set_points(trend_line, trendLinePoints, TREND_POINTS);
lv_obj_set_style_line_color(trend_line, lv_color_hex(0x00E5A0), 0);
lv_obj_set_style_line_width(trend_line, 2, 0);
lv_obj_set_style_line_rounded(trend_line, true, 0);
lv_obj_set_style_line_opa(trend_line, LV_OPA_70, 0);
// Pallino stato
dot_status = lv_obj_create(center_circle);
lv_obj_remove_style_all(dot_status);
lv_obj_set_size(dot_status, 8, 8);
lv_obj_set_style_radius(dot_status, LV_RADIUS_CIRCLE, 0);
lv_obj_set_style_bg_opa(dot_status, LV_OPA_COVER, 0);
lv_obj_set_style_bg_color(dot_status, lv_color_hex(0x00E5A0), 0);
lv_obj_set_style_shadow_width(dot_status, 8, 0);
lv_obj_set_style_shadow_color(dot_status, lv_color_hex(0x00E5A0), 0);
lv_obj_set_style_shadow_opa(dot_status, LV_OPA_50, 0);
lv_obj_align(dot_status, LV_ALIGN_CENTER, -42, 42);
// Testo stato
label_status = lv_label_create(center_circle);
lv_label_set_text(label_status, "ECCellenTE");
lv_obj_set_style_text_font(label_status, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_status, lv_color_hex(0x00E5A0), 0);
lv_obj_align(label_status, LV_ALIGN_CENTER, 3, 42);
// Titolo superiore
label_title = lv_label_create(scr);
lv_label_set_text(label_title, "AIR QUALITY");
lv_obj_set_style_text_font(label_title, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_title, lv_color_hex(0x4A6070), 0);
lv_obj_set_style_text_letter_space(label_title, 3, 0);
lv_obj_align(label_title, LV_ALIGN_TOP_MID, 0, 60);
// Punteggio inferiore
label_score = lv_label_create(scr);
lv_label_set_text(label_score, "100% PULITO");
lv_obj_set_style_text_font(label_score, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_score, lv_color_hex(0x00E5A0), 0);
lv_obj_align(label_score, LV_ALIGN_BOTTOM_MID, 0, -8);
// Record MIN/MAX (sopra il punteggio inferiore)
label_minmax = lv_label_create(scr);
lv_label_set_text(label_minmax, "L:-- H:--");
lv_obj_set_style_text_font(label_minmax, &lv_font_montserrat_14, 0);
lv_obj_set_style_text_color(label_minmax, lv_color_hex(0x3A4A5A), 0);
lv_obj_align(label_minmax, LV_ALIGN_BOTTOM_MID, 0, -24);
}
// ===================== Aggiorna dati linea trend =====================
void updateTrend(int value) {
trendData[trendIdx] = value;
trendIdx = (trendIdx + 1) % TREND_POINTS;
if (trendIdx == 0) trendFull = true;
int count = trendFull ? TREND_POINTS : trendIdx;
if (count < 2) return;
// Trova range dati, per normalizzare ad altezza linea
int vMin = 4095, vMax = 0;
for (int i = 0; i < count; i++) {
if (trendData[i] < vMin) vMin = trendData[i];
if (trendData[i] > vMax) vMax = trendData[i];
}
// Garantisce oscillazione minima - altrimenti quando aria troppo stabile linea diventa piatta morta
if (vMax - vMin < 50) vMax = vMin + 50;
int chartW = 110;
int chartH = 26;
for (int i = 0; i < TREND_POINTS; i++) {
int x = i * chartW / (TREND_POINTS - 1);
int y;
if (i < count) {
int dataIdx = trendFull ? (trendIdx + i) % TREND_POINTS : i;
int normalized = (trendData[dataIdx] - vMin) * chartH / (vMax - vMin);
y = chartH - normalized + 1; // asse Y invertito: valore più alto = punto più in alto
} else {
y = chartH + 1; // posizioni senza dati prima messe in basso
}
trendLinePoints[i].x = x;
trendLinePoints[i].y = y;
}
lv_line_set_points(trend_line, trendLinePoints, TREND_POINTS);
}
// ===================== Aggiorna display UI =====================
void update_ui(int value, int raw) {
value = constrain(value, 0, 4095);
raw = constrain(raw, 0, 4095);
// Animazione fluida: ogni frame avvicina al valore obiettivo del 18%, cambio numeri fluido non brusco
float diff = (float)value - displayValue;
displayValue += diff * 0.18f;
int dispVal = (int)(displayValue + 0.5f);
lv_color_t c = getColor(dispVal);
uint32_t dimC = getDimColorHex(dispVal);
int score = adcToScore(dispVal);
// Aggiorna record min/max
if (raw < minValue) minValue = raw;
if (raw > maxValue) maxValue = raw;
// Arco principale + knob colore segue stato
lv_arc_set_value(arc_main, dispVal);
lv_obj_set_style_arc_color(arc_main, c, LV_PART_INDICATOR);
lv_obj_set_style_bg_color(arc_main, c, LV_PART_KNOB);
lv_obj_set_style_shadow_color(arc_main, c, LV_PART_KNOB);
// Colore base traccia
lv_obj_set_style_arc_color(arc_bg, lv_color_hex(dimC), LV_PART_MAIN);
// Cerchio glow esterno: colore segue stato + funzione sin simula trasparenza respirante
lv_obj_set_style_border_color(glow_circle, c, 0);
lv_obj_set_style_shadow_color(glow_circle, c, 0);
static uint32_t breathCount = 0;
breathCount++;
float sinVal = sinf((breathCount * 6) % 360 * 3.14159f / 180.0f);
lv_opa_t breathOpa = (lv_opa_t)(LV_OPA_20 + (int)(sinVal * 25.0f));
lv_obj_set_style_shadow_opa(glow_circle, breathOpa, 0);
lv_opa_t borderOpa = (lv_opa_t)(LV_OPA_10 + (int)(sinVal * 15.0f));
lv_obj_set_style_border_opa(glow_circle, borderOpa, 0);
// Valore centrale
lv_label_set_text_fmt(label_value, "%d", dispVal);
lv_obj_set_style_text_color(label_value, c, 0);
// Testo stato + pallino (ombra pallino respira pure)
lv_label_set_text(label_status, getStatusText(dispVal));
lv_obj_set_style_text_color(label_status, c, 0);
lv_obj_set_style_bg_color(dot_status, c, 0);
lv_obj_set_style_shadow_color(dot_status, c, 0);
lv_opa_t dotOpa = (lv_opa_t)(LV_OPA_30 + (int)(sinVal * 40.0f));
lv_obj_set_style_shadow_opa(dot_status, dotOpa, 0);
// Colore linea trend
lv_obj_set_style_line_color(trend_line, c, 0);
// MIN/MAX
lv_label_set_text_fmt(label_minmax, "L:%d H:%d", minValue, maxValue);
// Punteggio pulizia inferiore
const char *statusWord;
if (score >= 80) statusWord = "PULITO";
else if (score >= 60) statusWord = "ACCETTabile";
else if (score >= 40) statusWord = "NVISTO";
else if (score >= 20) statusWord = "SPORCO";
else statusWord = "TOSSICO";
lv_label_set_text_fmt(label_score, "%d%% %s", score, statusWord);
lv_obj_set_style_text_color(label_score, c, 0);
}
// ===================== setup =====================
void setup() {
Serial.begin(115200);
delay(200);
// Primo passaggio: porta retroilluminazione alta, senza questo lo schermo rimane sempre nero
pinMode(TFT_BL, OUTPUT);
digitalWrite(TFT_BL, HIGH);
// Secondo passaggio: configura ADC (precisione 12 bit, range 0-3,3V)
// Nota: ADC_11db in ESP32 Core 3.x equivale a ADC_ATTEN_DB_12, compatibile con vecchia sintassi
pinMode(MQ135_PIN, INPUT);
analogReadResolution(12);
analogSetAttenuation(ADC_11db);
// Terzo passaggio: avvia schermo, frequenza SPI 40MHz
gfx.begin(40000000);
// Quarto passaggio: inizializza LVGL
lv_init();
lv_tick_set_cb(my_tick_cb);
lv_display_t *disp = lv_display_create(SCREEN_WIDTH, SCREEN_HEIGHT);
lv_display_set_color_format(disp, LV_COLOR_FORMAT_RGB565);
lv_display_set_buffers(disp, draw_buf, NULL, sizeof(draw_buf), LV_DISPLAY_RENDER_MODE_PARTIAL);
lv_display_set_flush_cb(disp, my_disp_flush);
// Quinto passaggio: costruisci interfaccia, inizializza a valore 0
create_ui();
displayValue = 0;
update_ui(0, 0);
Serial.println("[SYS] Indicatore v3.1 Pronto!");
}
// ===================== loop =====================
void loop() {
static uint32_t lastSensorMs = 0;
static uint32_t lastTrendMs = 0;
static uint32_t lastLogMs = 0;
uint32_t now = millis();
// Ogni 50ms: leggi sensore + aggiorna UI (circa 20fps, fluido senza lag)
if (now - lastSensorMs >= 50) {
int raw = analogRead(MQ135_PIN);
raw = constrain(raw, 0, 4095);
if (firstSample) {
// Primo frame assegna direttamente, salta transizione animazione da 0
smoothedValue = raw;
displayValue = raw;
firstSample = false;
} else {
// Media ponderata esponenziale: nuovo valore 12%, vecchio valore 88%, fluida ma non lenta
smoothedValue = smoothedValue * 0.88f + raw * 0.12f;
}
update_ui((int)smoothedValue, raw);
lastSensorMs = now;
}
// Ogni 300ms: pusha un punto dati alla linea trend (40 punti × 300ms ≈ 12 secondi coprono una schermata di storia)
if (now - lastTrendMs >= 300) {
updateTrend((int)smoothedValue);
lastTrendMs = now;
}
// Ogni 1s: output seriale log debug (apri monitor seriale per vedere quando hai problemi)
if (now - lastLogMs >= 1000) {
Serial.printf("SCORE=%d%% ADC=%d SMOOTH=%d L=%d H=%d [%s]\n",
adcToScore((int)smoothedValue),
analogRead(MQ135_PIN),
(int)smoothedValue,
minValue, maxValue,
getStatusText((int)smoothedValue));
lastLogMs = now;
}
lv_timer_handler(); // Scheduler interno LVGL, deve essere chiamato periodicamente, non dimenticare
delay(5);
}
Spiegazione del codice
Qualche scelta di design chiave, altrimenti il codice potrebbe confondere:
① Perché usare media ponderata esponenziale invece di mostrare direttamente l’ADC grezzo?
L’uscita analogica del MQ135 ha un certo rumore, mostrare direttamente il numero farebbe saltare continuamente i valori. La formula della media ponderata esponenziale (EMA):
nuovo valore medio = vecchio valore medio × 0,88 + valore grezzo × 0,12
Il peso 0,12 significa che i nuovi dati hanno influenza minore, il cambiamento dei valori è graduale ma segue il trend. Se vuoi una risposta più sensibile, aumenta 0,12f (max 1,0 = nessuna smoothing); se vuoi più stabilità, aumenta 0,88f.
② Come si realizza l’effetto respirante?
In update_ui() si usa sinf() per generare un valore che cicla da −1 a +1, mappato al range di trasparenza (LV_OPA_20 ~ LV_OPA_45), il contatore incrementa a ogni chiamata. La trasparenza del bordo esterno e dell’ombra così sfuma ciclicamente, come se “respirasse”.
③ Perché la linea trend a volte è piatta?
Quando l’ambiente è molto stabile e la differenza tra massimo e minimo storico è piccola, la linea viene forzata ad almeno 50 ADC di range:
if (vMax - vMin < 50) vMax = vMin + 50;
Così anche se l’aria non cambia, la linea non diventa una linea piatta morta, ma si possono notare piccole oscillazioni.
Risoluzione problemi comuni
Non preoccuparti, l’80% dei problemi viene da questi punti:
Schermo tutto nero, nessuna reazione
Prima cosa: controlla se il pin BL è collegato a GPIO 7 e se nel codice viene eseguito digitalWrite(TFT_BL, HIGH). Se la retroilluminazione non è accesa, lo schermo sarà sicuramente nero - non è che lo schermo è rotto, è che la retroilluminazione non è stata alzata.
Schermo tutto bianco o tutto rosso (c’è colore ma nessun contenuto) Nel 90% dei casi i pin DC e CS sono invertiti. Controlla questi due cavi confrontando con la tabella di collegamento, o scambiali direttamente per provare.
Errore di compilazione: lv_font_montserrat_28 undeclared
lv_conf.h non è configurato correttamente, o è nella posizione sbagliata. Torna alla sezione “Librerie da installare”, segui i passaggi per cambiare le opzioni font da 0 a 1.
Lettura ADC sempre 0 o 4095 senza cambiamenti Usa un multimetro per misurare la tensione di uscita del pin A0 del MQ135, normalmente dovrebbe oscillare tra 0,5V-2,5V. Se è 0V controlla il cablaggio VCC; se è a scala massima (3,3V), il sensore potrebbe non essere preriscaldato a sufficienza - nuovi sensori appena accesi hanno letture instabili, aspetta 3 minuti e riprova.
Valore visualizzato trema molto
Nel codice aumenta il coefficiente smoothing 0.88f (ad esempio 0,95f), aumenta la stabilità ma il prezzo è una risposta più lenta.
LVGL durante compilazione dice memoria insufficiente o si blocca in runtime
Riduci DRAW_BUF_LINES da 40 a meno (ad esempio 20), riduce l’occupazione del buffer. La RAM standard dell’ESP32-S3 è sufficiente, solo con schede con RAM minore si incontrerà questo problema.
FAQ
D: GPIO 13 è fisso? Posso usare un altro pin ADC? R: Sì puoi cambiare. Sull’ESP32-S3 i GPIO 1-10 appartengono ad ADC1, i GPIO 11-20 appartengono ad ADC2. Questo progetto non usa Wi-Fi, quindi i pin ADC2 (incluso GPIO 13) non hanno conflitti e funzionano normalmente. Se in futuro vuoi aggiungere Wi-Fi, si consiglia di spostare il sensore su un pin ADC1 (GPIO 1-10), evitando errori di lettura quando il Wi-Fi occupa ADC2.
D: MQ135 alimentato a 3,3V, le letture sono precise o no? R: Non molto precise, ma sufficienti per mostrare il trend. La tensione nominale del MQ135 è 5V; con alimentazione 3,3V la potenza del filo riscaldante è circa il 44% dello standard, la sensibilità diminuisce e i valori assoluti sono più bassi. Se vuoi convertire in concentrazione ppm, si consiglia di alimentare VCC con 5V separatamente; l’uscita analogica A0 non supera 3,3V, quindi non serve un circuito partitore aggiuntivo.
D: LVGL deve essere obbligatoriamente v9? v8 può funzionare?
R: v8 non può eseguire direttamente questo codice. v9 ha introdotto lv_display_t, lv_display_create e altre nuove API che non esistono in v8; compilare direttamente darà molti errori. Si consiglia vivamente di installare la versione v9.2.x o successive, non downgrade.
D: I quattro angoli dello schermo circolare hanno “buchi” neri, è saldato male? R: Fenomeno normale, non un problema. GC9A01 ha area di visualizzazione circolare, il buffer sottostante è quadrato 240×240, i quattro angoli sono strutture fisiche di schermatura dello schermo, non hanno pixel reali, non mostrare contenuto è corretto.
D: Quando il sensore viene appena acceso il valore salta molto, quanto tempo aspettare perché si stabilizzi?
R: Il MQ135 necessita preriscaldamento. Per nuovi sensori si consiglia continuità elettrica 24-48 ore prima che le letture si stabilizzino; sensori già usati si stabilizzano dopo circa 3 minuti di alimentazione. Puoi aggiungere delay(180000) (3 minuti) alla fine di setup(), oppure aggiungere uno stato “Preriscaldamento” nell’UI, iniziare采集 ufficialmente dopo il tempo.
D: Lo refresh dello schermo è un po’ lento, come velocizzare?
R: Due direzioni: ① Aumenta la frequenza SPI in gfx.begin(40000000) a 80MHz (GC9A01 supporta fino a 80MHz, ma alcune schede con qualità cablaggio scarsa possono essere instabili, testare prima); ② Aumenta DRAW_BUF_LINES (ad esempio a 60), riduci il numero di refresh parziali LVGL, il prezzo è occupare circa 9KB RAM in più.
Sviluppi successivi
Una volta funzionante, puoi continuare a espandere in queste direzioni:
- Collega BME280, aggiungi temperatura e umidità, dashboard mostra una riga di dati in più
- Invia dati ADC tramite Wi-Fi a Home Assistant, crea grafico storico a lungo termine
- Aggiungi pulsante per cambiare modalità display (indicatore / modalità numeri grandi / solo linea trend)
- Sostituisci con sensore MQ-7, specializzato nel monitoraggio concentrazione monossido di carbonio
- Aggiungi buzzer, quando qualità aria entra in zona PERICOLO attiva allarme