11. Display e ESPHome Designer

I display sono il punto in cui la maggior parte delle persone abbandona ESPHome, ed è un peccato perché è anche il progetto più soddisfacente: un pannellino appeso in corridoio che mostra temperatura, meteo e prossimo appuntamento è la cosa che gli ospiti notano.

Il motivo dell’abbandono è tecnico e preciso: ESPHome disegna sui display tramite lambda, cioè frammenti di C++ scritti dentro il YAML, in cui ogni elemento va posizionato con le sue coordinate in pixel. Scrivere it.printf(10, 42, id(font_grande), "%.1f°C", id(temp).state); per venti elementi, ricompilare cinque minuti, guardare il risultato, spostare tutto di tre pixel e ricompilare, è un ciclo che stanca in fretta. ESPHome Designer esiste per rompere quel ciclo. In questo capitolo vediamo i tipi di display, perché il lambda a mano è faticoso, come funziona il Designer e quale flusso di lavoro conviene adottare.

I tipi di display e cosa richiedono

Tipo	Interfaccia	Aggiornamento	Consumo	Buono per
OLED 128×64 (SSD1306)	I²C	Istantaneo	Basso	Dati essenziali, prototipi, piccoli pannelli
E-ink / e-paper	SPI	2-15 secondi	Quasi zero a riposo	Cartelli informativi, device a batteria
LCD TFT (ILI9341, ST7789)	SPI	Istantaneo	Medio-alto	Interfacce colorate, grafici
TFT touch + LVGL	SPI + touch	Istantaneo	Alto	Pannelli di controllo veri, con pulsanti

Le due scelte che contano sono agli estremi.

L’OLED da 128×64 costa 3 €, si collega all’I²C con due fili e funziona su qualsiasi chip. È perfetto per mostrare quattro numeri, e per iniziare è il display giusto.

L’e-ink è la scelta interessante per i cartelli informativi, perché consuma corrente solo mentre cambia l’immagine. Un pannello e-ink alimentato a batteria che si aggiorna quattro volte al giorno dura mesi, ed è l’unico tipo di display che ha senso mettere dove non arriva una presa. Il rovescio è la lentezza (secondi per un refresh completo) e il fatto che i refresh parziali continui degradano il pannello: si progetta per aggiornare di rado.

Per tutto ciò che è LVGL, cioè interfacce grafiche vere con pulsanti e animazioni, serve un ESP32-S3 con PSRAM, come detto in 2 Famiglie e scelta della board. Non è un consiglio, è un requisito: senza PSRAM il framebuffer non ci sta in memoria.

Il problema del lambda scritto a mano

Ecco come si disegna una schermata minima in ESPHome senza strumenti:

font:
  - file: "fonts/Roboto-Regular.ttf"
    id: font_piccolo
    size: 12
  - file: "fonts/Roboto-Bold.ttf"
    id: font_grande
    size: 32
 
display:
  - platform: ssd1306_i2c
    model: "SSD1306 128x64"
    address: 0x3C
    lambda: |-
      it.printf(0, 0, id(font_piccolo), "Cucina");
      it.printf(0, 18, id(font_grande), "%.1f", id(temperatura).state);
      it.printf(70, 30, id(font_piccolo), "°C");
      it.printf(0, 52, id(font_piccolo), "Umidità %.0f%%", id(umidita).state);

Funziona, ed è anche leggibile. Il problema non è la sintassi: è che ogni numero in quelle righe (0, 18, 70, 30, 52) è una coordinata che hai indovinato, e per sapere se è giusta devi compilare e guardare. Con quattro elementi si sopravvive. Con un pannello e-ink da 800×480 e venticinque elementi, il ciclo “modifica, compila cinque minuti, guarda, sposta” diventa insostenibile.

C’è anche il problema dei font: ogni dimensione va dichiarata separatamente, i file .ttf vanno messi nella cartella giusta, e ogni carattere non ASCII (gli accenti, il simbolo del grado, le icone Material Design) va incluso esplicitamente con glyphs: o non viene disegnato.

ESPHome Designer

ESPHome Designer è un editor visuale drag & drop per esattamente questo problema. Apri un canvas che rappresenta il tuo display, trascini gli elementi dove li vuoi, li colleghi alle entità di Home Assistant, e lui genera il codice.

Si installa in due modi. Il primo è come integrazione HACS: aggiungi il repository github.com/koosoli/ESPHomeDesigner fra quelli custom di HACS, installi, e il Designer compare dentro Home Assistant. Il secondo è come web app standalone su koosoli.github.io/ESPHomeDesigner, che non richiede nessuna installazione: apri il sito, gli dai le credenziali della tua istanza Home Assistant, e lavori da lì. Per provarlo, la seconda strada è la più veloce. Se HACS non ce l’hai ancora, il capitolo è 5 Integrazioni e HACS.

Le cose che sa fare, in ordine di utilità:

Il canvas con anteprima delle entità vere. Trascini un widget “temperatura”, lo colleghi a sensor.sensore_cucina_temperatura, e sul canvas vedi il valore attuale, non un segnaposto. Questo cambia tutto rispetto al ciclo compila-e-guarda: capisci subito se il numero ci sta nello spazio che gli hai dato, se il font è troppo grande, se l’etichetta va a capo.

Oltre cinquanta tipi di widget. Testo, valori di sensori, grafici, icone, codici QR, barre di progresso, aree touch. Sono i mattoni che nel lambda dovresti costruire a mano ogni volta.

Pagine multiple con pianificazione oraria. Un pannello che di giorno mostra il meteo e la sera il consumo elettrico, senza scrivere la logica di rotazione.

Visibilità condizionale. Un widget che compare solo se una certa entità è in un certo stato: l’icona della lavatrice solo mentre il ciclo è in corso, l’allerta finestra aperta solo quando lo è davvero. Nel lambda sarebbero if annidati.

Generazione assistita da AI. Descrivi a parole il layout che vuoi e ottieni una bozza da sistemare. Utile per partire, non per finire.

Round-trip. Puoi reimportare una configurazione esistente nell’editor e continuare a lavorarci. È la funzione che rende il Designer utilizzabile a lungo invece che solo per il primo disegno: senza, ogni modifica successiva ti riporterebbe a mano nel lambda.

Cosa esporta

Il Designer non è legato solo a ESPHome, ed è una cosa che vale la pena sapere:

• Lambda C++ per i display ESPHome tradizionali (OLED, e-ink, TFT).
• LVGL YAML per i pannelli touch su ESP32-S3.
• JSON per OpenEpaperLink, il sistema delle etichette elettroniche da supermercato riutilizzate in domotica.
• Azioni HTTP JSON per OpenDisplay.

Le prime due sono quelle che ti servono in questo corso. Le altre due significano che se un domani passi a un’altra piattaforma di display, il layout che hai disegnato non è buttato.

L’hardware supportato

Il Designer conosce le geometrie e le particolarità di parecchi dispositivi pronti: i pannelli e-ink reTerminal E1001/E1002 di Seeed, TRMNL, i Waveshare PhotoPainter, l’M5Paper, gli HMI Elecrow da 9 pollici, oltre agli OLED e ai TFT generici. Se il tuo display è uno di questi, parti con le dimensioni giuste; se è generico, imposti risoluzione e profondità di colore a mano.

Il flusso di lavoro completo

Mettendo insieme i pezzi, ecco come si costruisce un pannello dall’inizio.

1. Fai funzionare il device senza display. Configura il chip, il Wi-Fi, l’OTA, ed eventuali sensori locali. Verifica che sia online in Home Assistant. Aggiungere il display a un device che già funziona isola i problemi.
2. Aggiungi il display “nudo”. Solo la dichiarazione della piattaforma e un lambda con una scritta di prova. Serve a verificare cablaggio, indirizzo I²C o pin SPI, e orientamento. Se qui vedi “Ciao” sullo schermo, l’hardware è a posto e tutto il resto è software.
3. Disegna il layout nel Designer. Scegli il device, trascina i widget, collega le entità, sistema le dimensioni guardando i valori veri.
4. Esporta e incolla. Copi lo snippet generato e lo metti nella configurazione del device, al posto del lambda di prova.
5. Compila e installa via OTA dal Device Builder, come sempre.
6. Itera. Le modifiche successive si fanno nel Designer e si reimportano, non a mano nel YAML.

Il passaggio 2 è quello che la gente salta ed è quello che fa perdere più tempo: se disegni un layout bellissimo e poi scopri che il display è cablato male, non sai se il problema è nel disegno o nei fili.

IL DISPLAY RESTA BIANCO (O NERO) E NON SUCCEDE NIENTE

Nell’ordine: controlla l’alimentazione del display, che spesso vuole 5 V mentre il chip lavora a 3,3; verifica l’indirizzo I²C con scan: true (gli SSD1306 usano 0x3C o 0x3D); controlla che il modello dichiarato nel YAML corrisponda esattamente al pannello, perché controller diversi con la stessa diagonale non sono intercambiabili; sugli e-ink, ricorda che il primo refresh completo può richiedere una decina di secondi durante i quali sembra rotto. Se nei log leggi che il componente si inizializza senza errori ma non vedi nulla, il sospetto numero uno è il modello sbagliato.

Quanto aggiornare, e perché conta

L’update_interval di un display non è come quello di un sensore. Ridisegnare uno schermo costa CPU e, sugli e-ink, consuma il pannello: le tecnologie e-paper hanno un numero finito di refresh e i refresh parziali continui lasciano fantasmi.

Le regole pratiche: su OLED e TFT, un aggiornamento ogni 5-10 secondi è più che sufficiente per dei numeri (l’occhio non nota di più, e disegnare a 60 Hz scalda il chip per niente). Sugli e-ink, si progetta per aggiornare ogni 10-30 minuti, e si accetta che il dato mostrato sia vecchio di qualche minuto: è la natura del mezzo, non un difetto.

Se il display deve reagire istantaneamente a qualcosa (un pulsante premuto, un allarme), non alzare la frequenza globale: usa un component.update puntuale scatenato dall’evento.

Ricapitolando

• OLED 128×64 per iniziare (3 €, due fili I²C); e-ink per i cartelli e per la batteria; S3 con PSRAM obbligatorio per LVGL.
• Il lambda a mano funziona ma il ciclo “sposta di tre pixel, ricompila cinque minuti” è il motivo per cui la gente molla.
• ESPHome Designer (HACS koosoli/ESPHomeDesigner, o web app standalone) è un canvas drag & drop con anteprima delle entità vere.
• Ha 50+ widget, pagine multiple con pianificazione oraria, visibilità condizionale e generazione assistita da AI.
• Il round-trip è la funzione che lo rende usabile a lungo: reimporti la config e continui a lavorarci.
• Esporta lambda C++, LVGL YAML, e anche formati per OpenEpaperLink e OpenDisplay.
• Flusso giusto: device funzionante → display nudo con una scritta di prova → disegno → export → OTA → itera.
• Non alzare la frequenza di refresh: 5-10 s su OLED e TFT, 10-30 minuti sugli e-ink, che si consumano.