Configurare, compilare e installare il firmware ESPHome tramite l’ambiente HASSIO

8 minuti di lettura
SCOPI DELLA GUIDA:
  • Utilizzare l’ambiente HASSIO al fine di configurare, compilare e installare su un dispositivo compatibile (ESP8266 o ESP32) il firmware ESPHome
  • Livello di difficoltà: medio
CONCETTI AFFRONTATI:
  • Installazione add-on
  • Configurazione firmware
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
  • Un dispositivo target basato su SOC ESP8266 o ESP32
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno puro scopo didattico);
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere garanzia, omologazioni e certificazioni di qualità.
Revisione guida: 1.0

Abstract

ESPHome - LogoESPHome è un firmware alternativo di nuova concezione per dispositivi basati su SOC ESP8266 e ESP32. La particolarità di questo firmware è la modalità con la quale l’utente lo configura, lo compila e ne stabilisce i comportamenti: differentemente da altri famosi firmware (come l’arcinoto Tasmota), i quali per design ad ogni compilazione includono tutte le funzionalità previste (anche quelle non utilizzabili dal dispositivo target), ESPHome consente di scegliere quali “moduli” includere nella compilazione, consentendo all’utente un maggior spazio di manovra.

Dato che la memoria dei dispositivi di cui sopra è limitata, infatti, i firmware di vecchia concezione devono giocoforza limitare le funzionalità incluse in essi; ESPHome invece mette a disposizione un “catalogo” di funzionalità (in continuo ampliamento) dal quale l’utente attinge selettivamente per modellare la propria implementazione di firmware. Una sorta di firmware su misura.

Altra differenza sta nelle modalità di definizione di questo insieme di funzionalità e caratteristiche: ESPHome mette infatti a disposizione dei tool a interfaccia grafica semplificati per rendere semplice anche all’utente meno esperto questo processo.

N.b. Tutti i dettagli su ESPHome sono disponibili sulla sua scheda inDomus.

Home Assistant Official Logo

Gli utenti Home Assistant che abbiano optato per l’installazione HASSIO dispongono di un add-on tale da dotarsi di questi tool, il quali consentono appunto tramite interfaccia web la configurazione, la compilazione e per sino l’installazione (via Wi-Fi) del firmware ESPHome sul dispositivo target.

Questa guida illustra proprio questi aspetti, dall’installazione dell’add-on al suo utilizzo, con riferimenti successivi alla configurazione del firmware fino al processo di installazione dello stesso sul dispositivo target.

N.b. Questa guida non è da confondersi con una dedicata all’integrazione di componenti ESP8266/ESP32 dotati di firmware ESPHome con l’HUB personale Home Assistant. Questa guida spiega piuttosto come installare, configurare e utilizzare l’add-on ESPHome al fine di riprogrammare un componente tramite firmware ESPHome.
N.b. Quelle descritte da questa guida non sono le uniche modalità di configurazione/compilazione/installazione di ESPHome. Esistono, volendo, altre possibilità.

Si parte

Installazione add-on

Home Assistant HASSIO è un HUB personale per domotica che può essere installato sia come sistema stand-alone su Raspberry Pi sia come sistema stand-alone virtualizzato su Docker, sempre su Raspberry Pi o su altri sistemi operativi sui quali sia presente Docker. Dopo averlo installato e dopo aver provveduto ai primi passi di configurazione, esiste una lista, breve ma importante, di strumenti da implementare da subito presso il suo frontend web.

Si tratta di semplici ma essenziali strumenti modulari (add-on) per la gestione, la configurazione, il collegamento sicuro del nostro HUB; senza è difficile riuscire in queste attività, salvo l’adozione di complicati workaround che però vanificano la semplicità intrinseca a questa distribuzione di Home Assistant. HASSIO infatti è una versione semplificata di Home Assistant – non nelle funzioni quanto nella modalità di installazione e di gestione ordinaria – che permette a chiunque di dotarsi di questo potente HUB personale. Un approfondimento sulle varie alternative di installazione è presente qui.

INSTALLAZIONE

Come anticipato sopra, la suite di tool ESPHome può essere installata come add-on presso HASSIO al fine di fornire una pratica interfaccia grafica utile a configurare e compilare il firmware, il quale poi verrà installato sul dispositivo target.

Per installare l’add-on, cliccare, presso il menu, la voce “Supervisor”  > “ADD-ON STORE“: si tratta di accedere ad una vera e propria “vetrina” di componenti aggiuntivi (gratuiti) che, proprio come mattoncini da costruzioni, andranno ad arricchire le funzionalità del nostro HUB.

Per installarlo è necessario aggiungere il seguente indirizzo ai repository ufficiali (“Add new repository by URL“):

https://github.com/esphome/hassio

Dopodiché cercare “ESPHome” e cliccare su “INSTALL” e attendere svariati minuti. Non chiudere la finestra nel mentre.

HASSIO - ESPHome add-on

Infine, avendo cura prima di selezionare “Show on sidebar” nel box in testa alla pagina, cliccare su “Start” per avviare il servizio. Non consigliamo di attivare “Start on boot“: si tratta di un servizio che verrà usato di tanto in tanto, quindi ha più senso attivarlo manualmente alla bisogna piuttosto che forzarne l’avvio occupando memoria e risorse del sistema.

Dashboard

Una volta installato e avviato l’add-on, sulla barra laterale di Home Assistant apparirà l’icona di ESPHome. Cliccandovi apparirà la dashboard principale; tale ambiente consente la definizione di “progetti”, ovvero quelle che saranno le varie personalizzazioni che andremo a definire per i vari dispositivi target destinatari ultimi del firmware.

Poniamo per esempio di avere un Sonoff Basic e un Sonoff POW: ovviamente si tratta di due interruttori simili ma non identici: il primo è un semplice interruttore singolo canale, il secondo è analogo ma è in grado anche di rileva l’entità in Watt del carico elettrico applicatogli. Va da sé che per questi due dispositivi – laddove gli si voglia installare ESPHome – prevedano due configurazioni diverse: in questo ESPHome ci aiuta consentendoci di creare due progetti diversi con caratteristiche peculiari.

Nuovo progetto

Rimanendo nel solco dell’esempio del Sonoff Basic R3 di cui sopra, vediamo di creare un progetto ad hoc per tale dispositivo.

Clicchiamo, in dashboard, sul “+” in alto a destra. Indichiamo un nome progetto (no maiuscole né spazi), per esempio “sonoff_basic“.

HASSIO - ESPHome add-on - Nuovo progetto - 1

Scegliamo poi la tipologia di system-on-a-chip (SOC) presente sul dispositivo target, in questo caso “Generic ESP8266“.

HASSIO - ESPHome add-on - Nuovo progetto - 2

Inseriamo in seguito le coordinate d’accesso alla propria Wi-Fi domestica (SSID e password) nonché una password di accesso OTA (over-the-air) a scelta:

HASSIO - ESPHome add-on - Nuovo progetto - 3

Terminato questo processo, cliccare sul tasto “SUBMIT“. Così facendo avremo creato il nostro primo progetto.
HASSIO - ESPHome add-on - Nuovo progetto - 5

Così facendo avremo creato un progetto base contenente alcune informazioni minimali.

Gestione progetto

I progetti vengono visualizzati in dashboard sotto forma di elenco.

HASSIO - ESPHome add-on - Dashboard e dettagli progetto
il progetto appena creato.

Ogni elemento dell’elenco presenta tutta una serie di informazioni e opzioni tra i quali:

  • lo stato del componente (il quale apparirà solo dopo avergli installato il firmware compilato);
  • il tasto “EDIT” per la modifica della configurazione dei firmware (ovvero cosa includere in compilazione, e come);
  • il tasto “VALIDATE“, per verificare che la configurazione sia scritta correttamente;
  • la voce “Clean Build‘, per pulire le eventuali, precedenti compilazioni;
  • l’importantissima voce “Compile“, per compilare l’attuale configurazione del firmware destinato al dispositivo target;
  • il tasto “UPLOAD” per installare di una nuova release del firmware (tramite procedura OTA – over the air – possibile però solo dopo aver installato una prima volta, manualmente, il firmware).

Se si cliccasse direttamente su “Compile“, ESPHome provvederebbe a compilare la versione minimale del firmware (quella visibile cliccando su “Edit), frutto della iniziale configurazione di massima indicata in fase di creazione progetto:

esphome:
  name: sonoff_basic
  platform: ESP8266
  board: esp01_1m

wifi:
  ssid: ""
  password: ""

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Sonoff Basic Fallback Hotspot"
    password: ""

captive_portal:

# Enable logging
logger:

# Enable Home Assistant API
api:
  password: ""

ota:
  password: ""

Una volta effettuate (eventuali) modifiche alla configurazione sarà sufficiente cliccare su “SAVE” e poi su “VALIDATE” per verificarne la correttezza, la quale verrà eventualmente confermata tramite questo messaggio:

HASSIO - ESPHome add-on - validazione configurazione

A questo punto cliccando su “Compile” verrà effettuata la compilazione del proprio firmware al termine della quale, se andata a buon fine, sarà possibile scaricare il binario precompilato per l’installazione fisica sul dispositivo target semplicemente cliccando su “DOWNLOAD BINARY“.

Installazione del firmware

È ora importante capire un concetto fondamentale legato a ESPHome: qualsiasi modifica attuata alla configurazione del progetto al fine di variare il comportamento del dispositivo target passa per una nuova compilazione del firmware e una sua nuova installazione.

L’installazione può essere fatta in due modalità:

  • fisica, tramite adattatore USB/TTL;
  • OTA (over-the-air), ovvero tramite Wi-Fi.

La modalità fisica è quella da attuarsi la prima volta che si programma con il firmware ESPHome un dispositivo; la modalità OTA è quella solitamente utilizzata dalla seconda volta in poi.

Tasmota Full LogoN.b. In caso il dispositivo target sia già dotato di firmware Tasmota, non è necessario utilizzare la modalità fisica via adattatore USB/TTL. È infatti sufficiente compilare normalmente il firmare ESPHome, scaricare il precompilato e, tramite interfaccia web di Tasmota, aggiornare il firmware usando quel precompilato ESPHome. Maggiori dettagli sono disponibili qui.
MODALITÀ FISICA

Per provvedere alla riprogrammazione fisica del dispositivo target è necessario prima compilare e scaricare il binario precompilato (come spiegato sopra) e poi seguire i semplici passi di questa guida.

Sostanzialmente si tratta di riprogrammare il firmware usando appunto il precompilato. Niente di più.

MODALITÀ OTA

Una volta installato ESPHome sul dispositivo potremo dimenticarci dell’adattatore USB/TTL. Il dispositivo target, una volta acceso con ESPHome in esecuzione (e collegato alla propria WI-Fi) viene “visto” direttamente dalla dashboard ESPHome di HASSIO. Per effettuare una modifica sarà quindi sufficiente eseguirla, salvarla, validarla, compilare il firmware e poi cliccare su “UPLOAD“: si aprirà una finestra che, tramite connessione tramite LAN, provvederà ad aggiornare il firmware a bordo del dispositivo.

Personalizzazioni

Sebbene lo scopo di questa guida sia esplicitamente quello di spiegare come funzioni la suite di tool ESPHome presso HASSIO (e quindi quali siano le funzioni di definizione progetto, la compilazione e l’aggiornamento OTA del dispositivo target), forniamo volentieri una panoramica (approfondita poi in altre guide) che illustri alcuni casi d’uso.

FUNZIONI BASE (“CORE”)

Tornando all’esempio di cui sopra (Sonoff Basic R3), abbiamo visto proposta una configurazione minimale che prevede, per l’appunto, un insieme minimo di funzionalità dette “Core” ovvero:

  • esphome:  nome del progetto, processore e tipo scheda;
  • wifi: nome utente e password della Wi-Fi domestica;
  • logger: abilita il logger visibile nel plugin esphome;
  • api: funzionalità utile all’integrazione (con Home Assistant, ma anche con altri HUB e realtà operative);
  • ota: aggiornamenti OTA abilitati (necessario per l’aggiornamento del firmware dalla seconda volta in poi);
  • captive_portal: quando il dispositivo non trova la Wi-Fi prevista, espone un proprio AP con il 192.168.4.1 e relativo captive portal (pagina di benvenuto).

Queste funzioni vengono aggiunte automaticamente dal wizard di creazione nuovo progetto, ma possono ovviamente essere personalizzate in una seconda fase.

FUNZIONI AGGIUNTIVE

Esiste poi tutta una lista di componenti aggiuntive (in continua evoluzione) che possono essere aggiunte al nostro progetto, sopratutto in relazione al tipo di dispositivo target. Nel caso del Sonoff Basic R3, dato che si tratta di interruttore intelligente a singolo canale dotato, osservandolo, di:

  • un pulsante;
  • un LED;
  • un interruttore (relè).

Per includere in configurazione questi elementi serve un “binary_sensor” (attenzione, non stiamo parlando di Home Assistant, ma di un componente ESPHome che non casualmente si chiama uguale a un componente dell’HUB), uno “switch” (stesso discorso) e uno “status_led“.

Li implementeremo in modo molto piuttosto piatto, così da limitarci a far funzionare l’attuatore in modo elementare:

esphome:
  name: sonoff_basic
  platform: ESP8266
  board: esp01_1m

wifi:
  ssid: ""
  password: ""

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Sonoff Basic Fallback Hotspot"
    password: ""

captive_portal:

# Enable logging
logger:

# Enable Home Assistant API
api:
  password: ""

ota:
  password: ""

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      mode: INPUT_PULLUP
      inverted: True
    name: "Pulsante Sonoff Basic"
    on_press:
      - switch.toggle: relay

switch:
  - platform: gpio
    name: "Relè Sonoff Basic"
    pin: GPIO12
    id: relay

status_led:
  pin:
    number: GPIO13
    inverted: yes

Ciò che è veramente importante capire è che questi (come altri) componenti del firmware ESPHome nascondono molto più al loro interno di quanto non appaia all’occhio: per esempio, il componente “switch” può essere configurato in molto molto più evoluto, introducendo condizioni, automazioni ed altro. Questo è molto comodo perché consente all’utente di determinare una “personalità” specifica all’attuatore, evitando di demandare determinati automatismi base all’HUB personale in uso, ma lasciando piuttosto che sia direttamente il firmware che opera localmente sul dispositivo ad eseguire azioni specifiche.

Integrazioni

Le integrazioni dei dispositivi dotati di ESPHome verso gli HUB personali non sono oggetto di questa guida; ciò che è importante conoscere per il momento sono i componenti più tipicamente usati per provvedere ad esse:

  • Native API: è quello più comunemente utilizzato; per esempio, il componente d’integrazione ESPHome di Home Assistant utilizza proprio questo componente ESPHome;
  • MQTT: il “jolly” che consente virtualmente qualsiasi tipo di integrazione.

Su inDomus è presente una guida ad hoc che illustra come integrare un componente dotato di firmware ESPHome con Home Assistant via API.

Ringraziamenti

Si ringrazia Giovanni per la collaborazione nella stesura di questa guida.


NodeMCU ATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica ai dispositivi ESP8266 e similari per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.


Telegram News Channel