SCOPI DELLA GUIDA:
CONCETTI AFFRONTATI:
|
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
|
GUIDA INDICATA A UTENTI CON ISTALLAZIONE: |
|
NOTE E DISCLAIMER
|
|
| Revisione guida: 3.0 | |
Abstract
ESPHome è 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. |
Gli utenti Home Assistant che abbiano optato per le installazioni Home Assistant OS/Supervised dispongono di un add-on tale da dotarsi di questi tool, il quali consentono appunto tramite interfaccia web la configurazione, la compilazione e persino l’installazione (via OTA) 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
- Dashboard
- Nuovo progetto
- Gestione progetto
- Installazione del firmware
- Personalizzazioni
- Funzioni base (“Core”)
- Funzioni varie
- Integrazioni
- Ringraziamenti
Installazione add-on
Home Assistant è un HUB personale per domotica. 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. HassOS/Supervised 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 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:
- “Configurazione” > “Componenti aggiuntivi” e poi sul pulsante “Raccolta di componenti aggiuntivi“.
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 (“Repository” > “Aggiungi“):
https://github.com/esphome/hassio
Dopodiché cercare “ESPHome” e cliccare su “INSTALLA” e attendere svariati minuti. Non chiudere la finestra nel mentre.
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 “+ NEW DEVICE” in alto a destra. ESPHome chiederà di collegare il componente alla porta USB, ma per ora ignoriamo la cosa e clicchiamo su “CONTINUE“.
Indichiamo un nome progetto (no maiuscole né spazi), per esempio “sonoff_basic“, dopodiché indichiamo le credenziali di accesso alla propria Wi-Fi:
Scegliamo poi la tipologia di system-on-a-chip (SOC) presente sul dispositivo target, in questo caso “ESP8266“.
Terminato questo processo, cliccare sul tasto “SUBMIT“. Così facendo avremo creato il nostro primo progetto:
Così facendo avremo creato un progetto base contenente alcune informazioni minimali: potremmo provvedere immediatamente all’installazione cliccando “INSTALL“, ma per il momento soprassederemo cliccando su “SKIP“.
Gestione progetto
I progetti vengono visualizzati in dashboard sotto forma di elenco.
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 Files“, per pulire le eventuali, precedenti compilazioni;
- il tasto “UPDATE” 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);
- l’importantissima voce “Install“, per compilare l’attuale configurazione del firmware destinato al dispositivo target.
Una volta effettuate (eventuali) modifiche alla configurazione è sufficiente cliccare su “SAVE” e poi su “VALIDATE” per verificarne la correttezza, la quale verrà eventualmente confermata tramite un messaggio positivo.
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 cavo USB o 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.
 N.b. In caso il dispositivo target sia già dotato di firmware Tasmota, per riprogrammarlo con ESPHome non è necessario collegarlo fisicamente al prorpio computer di appoggio. È 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 collegarlo al proprio computer, o via USB (se il dispositivo è dotato di porta USB) oppure tramite un adattatore TTL/USB. In questo seecondo caso, è solitamente necessario impostare il dispositivo in modalità flash (o “BOOT mode”).
Una volta collegato al computer di appoggio, cliccare su “Install” > “Plug into this computer“; attendere qualche istante (“sotto il cofano” ESPHome sta compilando per noi il firmware) e poi cliccare su “Download project” per scaricare il file binario compilato.
Cliccare successivamente sul link “Open ESPHome Web” per recarsi presso il sito che consente, via browser, di riprogrammare i componenti collegati fisicamente al proprio computer. Cliccare su “CONNECT“, selezionare la porta seriale sulla quale è stato collegato il dispositivo, dopodichè cliccare su “INSTALL” per selezionare il file binaro poco prima scaricato e provvedere all’upload:
Cliccando “INSTALL” verrà avviata la riprogrammazione:
Al termine, il dispositivo sarà dotato di firmware ESPHome, configurato come da configurazione precedentemente definita.
MODALITÀ OTA
Una volta installato ESPHome sul dispositivo potremo dimenticarci della connessione fisica (via cavo o via 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 Home Assistant OS/Supervised. Per effettuare una modifica sarà quindi sufficiente eseguirla, salvarla, eventualmente validarla, per poi compilare e caricare il firmware clicando su “Install” > “Wirelessly“: si aprirà una finestra che, tramite connessione wireless, 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 Home Assistant OS/Supervised (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 SPECIFICHE
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:
encryption:
key: "metterequidentrounachiavepersonalequalunque"
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.
FUNZIONI ACCESSORIE E CONSIGLIATE
Si consiglia di implementare anche le funzioni spiegate in questa mini-scheda:
Utilità: elementi accessori consigliati per il firmware ESPHome
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.
| Questa pagina è redatta, manutenuta e aggiornata dallo staff di inDomus, un gruppo di persone molto diverse tra loro che trovi, per domande e supporto, sul forum e sulla chat del sito. Alcuni link sono taggati in qualità di affiliati Amazon e riceviamo un compenso dagli acquisti idonei, utile al sostenimento del sito, ma le nostre recensioni sono tutte indipendenti e non sponsorizzate. Se ti sei perso, a tua disposizione c'è la mappa. |