🖥️ ESP32 + OLED: Notifiche visive intelligenti con ESPHome

🔎 Descrizione del progetto

Questo progetto trasforma un microcontrollore ESP32 in un pannello di notifica visiva, utilizzando un display OLED SSD1306 da 128×64 pixel. È pensato per integrarsi con Home Assistant e mostrare messaggi testuali dinamici, come avvisi di sicurezza, stato degli elettrodomestici, promemoria o notifiche personalizzate.

Il cuore del sistema è un’entità input_text in Home Assistant: ogni volta che viene aggiornata, il messaggio appare sul display OLED. Il messaggio rimane visibile finché non ne arriva uno nuovo. Non c’è più alcun timeout automatico: il display mostra sempre l’ultimo messaggio ricevuto.

È una soluzione elegante, modulare e facilmente estendibile per chi vuole aggiungere un feedback visivo alle automazioni domestiche.

🔌 Collegamenti hardware

Componente	Pin ESP32	Pin periferica
Display OLED SSD1306	GPIO 21	SDA
Display OLED SSD1306	GPIO 22	SCL
Alimentazione	3.3V / GND	VCC / GND

Il display comunica via I²C, usando i pin GPIO 21 (SDA) e GPIO 22 (SCL). L’indirizzo I²C del display è 0x3C (standard per SSD1306). Non sono richieste resistenze di pull-up esterne: ESPHome le gestisce automaticamente.

📄 Spiegazione riga per riga del file YAML

⚙️ Configurazione generale

esphome:
  name: esphome-web-33da74
  friendly_name: Esp32 LCD
  min_version: 2025.5.0
  name_add_mac_suffix: false

name: nome tecnico del dispositivo
friendly_name: nome leggibile in Home Assistant
min_version: versione minima di ESPHome richiesta
name_add_mac_suffix: se false, evita di aggiungere il MAC al nome

🧠 Specifiche hardware

esp32:
  board: esp32dev
  framework:
    type: arduino

board: modello della scheda ESP32
framework: usa il linguaggio Arduino per la compilazione

🛠️ Servizi di base

logger:
api:
ota:
  - platform: esphome

logger: abilita il log seriale per il debug
api: consente la comunicazione diretta con Home Assistant
ota: permette aggiornamenti firmware via Wi-Fi

📶 Connessione Wi-Fi

wifi:
  networks:
    - ssid: "TechLab_Guest"
      password: "connect1234"
    - ssid: "HomeSecure_5G"
      password: "safezone9876"

Il dispositivo proverà a connettersi alla prima rete disponibile tra quelle elencate.

🔌 Bus I²C per il display

i2c:
  sda: 21
  scl: 22
  scan: true

sda e scl: pin di comunicazione I²C
scan: true: rileva automaticamente i dispositivi collegati

🔤 Font per il display

font:
  - file: "gfonts://Roboto"
    id: my_font
    size: 12

file: scarica il font Roboto da Google Fonts
id: nome interno del font
size: altezza dei caratteri in pixel

🧾 Sensore testuale da Home Assistant

text_sensor:
  - platform: homeassistant
    name: "Messaggio OLED"
    entity_id: input_text.lcd_message
    id: lcd_text

Importa l’entità input_text.lcd_message da Home Assistant
Ogni volta che il valore cambia, il display si aggiorna
Non c’è più alcun timeout: il messaggio resta finché non ne arriva uno nuovo

🖥️ Display OLED SSD1306

display:
  - platform: ssd1306_i2c
    model: "SSD1306 128x64"
    address: 0x3C
    lambda: |-
      if (!id(lcd_text).state.empty()) {
        std::string msg = id(lcd_text).state;
        int line = 0;
        const int max_chars = 20;

        while (msg.length() > 0 && line < 4) {
          std::string segment = msg.substr(0, max_chars);
          msg = msg.length() > max_chars ? msg.substr(max_chars) : "";
          it.printf(0, line * 16, id(my_font), "%s", segment.c_str());
          line++;
        }
      }

platform: tipo di display usato
model: risoluzione del display
address: indirizzo I²C del display
lambda: codice inline in C++ che:
- Verifica se il messaggio è vuoto
- Divide il testo in righe da 20 caratteri
- Le stampa verticalmente con spaziatura di 16 pixel
- Mostra massimo 4 righe (limite del display)

✅ Conclusione

Questo progetto è una soluzione compatta e potente per creare un pannello di notifica visiva con ESP32 e OLED. È perfettamente integrato con Home Assistant, facile da modificare e ideale per chi vuole un feedback immediato e visivo delle proprie automazioni.

Il comportamento è ora più naturale: il messaggio resta visibile finché non viene aggiornato. Nessun timeout, nessuna cancellazione automatica. Il display è sempre sincronizzato con l’ultimo stato dell’automazione.

Aggiungo …

Ecco una spiegazione semplificata del codice fornito:

Funzionamento generale

Il codice gestisce la visualizzazione di un testo su uno schermo LCD (es. 20 caratteri x 4 righe) in ESPHome.

Passaggi principali

Controllo inputif (!id(lcd_text).state.empty())
- Verifica che il contenuto da visualizzare non sia vuoto (es. “Ciao mondo!” invece di “”).
Inizializzazione variabilistd::string msg = id(lcd_text).state; int line = 0; const int max_chars = 20;
- msg: memorizza il testo da visualizzare.
- line: indica la riga corrente (da 0 a 3).
- max_chars: numero massimo di caratteri per riga (es. 20).
Loop per suddivisione del testowhile (msg.length() > 0 && line < 4)
- Continua finché ci sono caratteri da visualizzare e non si superano le 4 righe.
Suddivisione in segmentistd::string segment = msg.substr(0, max_chars); msg = msg.length() > max_chars ? msg.substr(max_chars) : "";
- Estrae i primi max_chars caratteri (es. “Ciao mondo!” → “Ciao mondo” in prima riga).
- Rimuove il segmento già visualizzato dal testo originale.
Visualizzazione su schermoit.printf(0, line * 16, id(my_font), "%s", segment.c_str());
- it: riferimento all’oggetto LCD.
- printf(...): stampa il testo in posizione (0, line*16) (spaziatura tra righe).
- id(my_font): font utilizzato per la visualizzazione.
Avanzamento rigaline++;
- Passa alla riga successiva per il prossimo segmento.

Esempio concreto

Se msg = "Questo è un testo lungo", il codice:

Stampa “Questo è un t” (20 caratteri) sulla riga 0.
Stampa “esto lungo” (rimanenti) sulla riga 1.

Perché funziona?

Gestisce testi lunghi suddividendoli in segmenti compatibili con le dimensioni dell’LCD.
Evita errori di sovraccarico o troncamento non previsto del messaggio.