Integriamo in Home Assistant il display Oled SSD1306 da 0.96″, programmandolo con ESPHome

Il display OLED da 0.96 pollici con controller SSD1306 è una delle soluzioni più diffuse nel mondo dell’elettronica e del fai-da-te per realizzare interfacce grafiche semplici e leggibili. Si tratta di un piccolo schermo monocromatico, economico e versatile, ideale per progetti basati su microcontrollori come l’ESP32. La tecnologia OLED garantisce un’elevata qualità di visualizzazione grazie al contrasto molto marcato tra i pixel accesi e lo sfondo nero, oltre a consumi ridotti rispetto ai tradizionali display LCD retroilluminati. Nonostante le dimensioni compatte, questo display permette di mostrare testi, icone o semplici grafici in modo chiaro. In questo articolo vedremo le principali caratteristiche tecniche, come collegarlo all’ESP32 e alcune indicazioni per integrarlo nei tuoi progetti con ESPHome.

Acquista su Aliexpress:

ESP32 – https://s.click.aliexpress.com/e/_omglDEk
Display OLED 0.96″ SSD1306 – https://s.click.aliexpress.com/e/_onXb2uU

Acquista su Amazon:

ESP32 – https://amzn.to/3HU71B3
Display OLED 0.96″ SSD1306 – https://amzn.to/43T4UGh

Specifiche tecniche

Il display OLED 0.96″ con chip SSD1306 ha una risoluzione di 128×64 pixel e rappresenta una scelta ideale per visualizzare testi, icone, piccoli grafici o indicatori di stato in progetti embedded. Il cuore del modulo è proprio il controller SSD1306, un circuito integrato progettato per pilotare direttamente i pixel OLED grazie alla presenza di una memoria interna chiamata GDDRAM, che memorizza lo stato di ciascun pixel.

Questo controller è in grado di gestire la comunicazione con il microcontrollore tramite diverse interfacce, tra cui I2C e SPI, anche se nella maggior parte dei moduli destinati al fai-da-te si utilizza quasi sempre l’I2C per la sua semplicità. Il SSD1306 integra funzioni avanzate come lo scroll orizzontale e verticale hardware, la possibilità di invertire i colori, e un sistema di gestione della luminosità mediante controllo software.

Il display funziona sia a 3,3V sia a 5V, adattandosi facilmente a microcontrollori come ESP32 o Arduino. L’indirizzo I2C di fabbrica è generalmente 0x3C, ma in alcune versioni può essere impostato su 0x3D tramite ponticelli o saldature sul modulo. La tecnologia OLED non necessita di retroilluminazione, poiché ogni pixel emette luce propria, e questo contribuisce a ridurre notevolmente i consumi rispetto ai display LCD tradizionali.

Collegamenti

Il collegamento del display all’ESP32 è semplice e richiede solo quattro fili. L’alimentazione viene fornita dal pin a 3,3V della scheda e la massa va connessa al GND. Per quanto riguarda i segnali dati, nel nostro esempio utilizziamo il pin GPIO0 dell’ESP32 come SCL, ovvero il clock della comunicazione I2C, e il pin GPIO4 come SDA, cioè la linea dati. Una volta effettuati i collegamenti, sarà possibile verificare la corretta comunicazione tramite uno scanner I2C o direttamente durante la configurazione con ESPHome.

Codice

Andiamo a creare un nuovo device su ESPHome e chiamiamolo OLED. Saltiamo per il momento la connessione e selezioniamo la scheda che dobbiamo programmare (ESP32).

Una volta creato, clicchiamo su EDIT per modificare il codice.

Questo è il codice per configurare una ESP32 per scrivere un testo o inviare dati al display da Home Assistant tramite ESPHome. Il dispositivo sarà accessibile in rete tramite Wi-Fi e potrà essere aggiornato via OTA (Over-The-Air) senza bisogno di connessione fisica. Potete scaricarlo a questo LINK.

All’inizio, il codice definisce il nome del dispositivo, sia quello tecnico (“oled”) che quello più leggibile per Home Assistant (“OLED”).

esphome:
  name: oled
  friendly_name: OLED

Poi si specifica che il microcontrollore utilizzato è un ESP32 e che il firmware verrà compilato usando il framework Arduino, che è più semplice e supportato rispetto ad altre alternative come ESP-IDF.

esp32:
  board: esp32dev
  framework:
    type: arduino

Il codice attiva il logger, che serve a registrare gli eventi e inviare messaggi di debug. Inoltre, viene attivata l’API di ESPHome, che permette a Home Assistant di comunicare con il dispositivo in modo sicuro grazie a una chiave di crittografia.

logger:

api:
  encryption:
    key: "LIAEDvKEh24Qfr5E64FlAChRDwst4IBxdHYq4SHpM54="

Per evitare di dover collegare il dispositivo fisicamente ogni volta che si vuole aggiornare il firmware, viene attivata la modalità OTA (Over-The-Air), con una password di sicurezza. Inoltre, è presente la funzione captive portal, che permette di riconfigurare il Wi-Fi direttamente da un browser in caso di problemi di connessione.

ota:
  - platform: esphome
    password: "1045d625c49976f481a366774eef7151"

captive_portal:

Per collegarsi alla rete, il codice usa le credenziali Wi-Fi salvate nei secrets di ESPHome (file separato non visibile nel codice). Se la connessione fallisce, il dispositivo crea un hotspot Wi-Fi di emergenza (“Oled Fallback Hotspot”) con una password predefinita, in modo che sia possibile riconfigurarlo.

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  ap:
    ssid: "Oled Fallback Hotspot"
    password: "TtNA0qNJtzdh"

Il Display OLED sfrutta l’interfaccia I2C, pertanto dichiariamo che è il pin SDA collegato al pin GPIO4 dell’ESP32, il pin SCL collegato al pin GPIO0, impostando la funziona scan come true.

i2c:
  sda: 4
  scl: 0
  scan: true
  id: bus_a

Abbiamo bisogno adesso di un font. Il primo passo sarà scaricare un qualsiasi font, ad esempio Arial. Poi, all’interno di Home Assistant OS, apriamo l’add-on File Editor (se non presente, scaricatelo da Componenti Aggiuntivi) e cerchiamo la cartella esphome.

Una volta al suo interno, clicchiamo sull’icona di Upload file e carichiamo il nostro font.

Se tutto è stato eseguito correttamente, all’interno della cartella esphome troverete il file del font Arial.

Dichiariamo il font appena caricato e impostiamo a 20 la grandezza del carattere.

font:
  - file: "arial.ttf"
    id: arial_font
    size: 20

Andiamo a dichiarare il nostro attuatore, indicando la piattaforma ssd1306_i2c, il modello e l’indirizzo per la comunicazione (0x3C), nel lambda, la funzione it.printf posiziona il testo al centro del display calcolando metà larghezza e metà altezza, e usa TextAlign::CENTER per centrare sia in orizzontale sia in verticale.

display:
  - platform: ssd1306_i2c
    model: "SSD1306 128x64"
    address: 0x3C
    lambda: |-
      it.printf(it.get_width() / 2, it.get_height() / 2, id(arial_font), TextAlign::CENTER, "ciao");

Salvate e verificate con Validate se il codice è stato scritto correttamente.

Collegate la ESP32 al computer tramite cavo USB, e cliccate su Install.

Conclusa l’installazione, integriamo il device su Home Assistant. Dovrebbe essere arrivata una notifica sulla plancia. In ogni caso, per integrarlo andate su Impostazioni -> Dispositivi e servizi e apparirà il dispositivo OLED da integrare.