SCOPI DELLA GUIDA:
CONCETTI AFFRONTATI:
|
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
|
GUIDA DEDICATA A utenti: |
|
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 che dispongano di Raspberry Pi dotato di sistema operativo Raspberry Pi OS possono utilizzarlo, tramite l’installazione di un package di tool, la configurazione, la compilazione e persino l’installazione (via OTA) del firmware ESPHome sul dispositivo target. In realtà la guida è valida, più genericamente, per gli utenti di sistemi operativi Linux.
Questa guida illustra proprio questi aspetti, dall’installazione del pacchetto di tool all’utilizzo degli stessi, con riferimenti successivi alla configurazione del firmware fino al processo di installazione dello stesso sul dispositivo target.
| 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
Raspberry Pi OS (Raspbian) è un sistema operativo dedicato ai micro-computer Raspberry Pi, noti per la loro versatilità. Come anticipato sopra, la suite di tool ESPHome può essere installata su Raspberry Pi OS al fine di fornire una pratica interfaccia grafica web utile a configurare e compilare il firmware, il quale poi verrà installato sul dispositivo target.
Per installarlo, da terminale (collegati via VNC o SSH), eseguire il seguente comando:
pip3 install tornado esphome
Al termine dare un’occhiata al comando al file ~/.profile col comando:
cat ~/.profile
Se all’interno del contenuto del file non è presente il seguente blocco:
# set PATH so it includes user's private bin if it exists
if [ -d "$HOME/.local/bin" ] ; then
PATH="$HOME/.local/bin:$PATH"
fi
provvedere ad aggiungerlo, in fondo al file, tramite il comando:
sudo nano ~/.profile
dopodiché salvare e uscire (CTRL+X, Y, invio).
Infine eseguire:
. ~/.profile
Al termine dell’avvenuta installazione, creiamo una cartella nella quale salveremo tutti i nostri “progetti”:
mkdir -p ~/esphome
Ora è possibile proseguire oltre.
Gestione progetto
Una volta installati i tool necessari per gestire ESPHome è possibile cominciare a realizzare i propri “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.
A questo punto per creare/modificare/installare un progetto possiamo seguire due strade diverse, ovvero:
- da riga di comando;
- tramite la dashboard web (scelta consigliata).
Riga di comando
Ipotizziamo dunque di avere un componente basato su ESP8266 (diciamo un Sonoff Basic R3) e di volerlo aggiornare con firmware ESPHome debitamente configurato. Creeremo un progetto ad hoc per:
- modellare il firmware;
- compilare il firmware;
- installare il firmware sul dispositivo target.
CREAZIONE PROGETTO
Lanciamo – sempre da terminale – il wizard indicandogli di creare un file specifico (sotto la directory ESPHome precedentemente creata) dedicata a questo nuovo progetto:
esphome ~/esphome/luce_salotto.yaml wizard
Avviandosi, il tool risponderà dicendo:
Hi there! I'm the wizard of ESPHome :) And I'm here to help you get started with ESPHome. In 4 steps I'm going to guide you through creating a basic configuration file for your custom ESP8266/ESP32 firmware. Yay!
quindi richiederà l’inserimento di alcune informazioni:
| (name) | Il “nome” del device. Noi sceglieremo “salotto“ |
| (ESP32/ESP8266) | La tipologia di processore del dispositivo target |
| (board) | La tipologia di board del dispositivo target, sulla base di questo elenco (ulteriori potrebbero aggiungersi):
nodemcuv2, esp8285, wifinfo, esp01_1m, d1_mini, espduino, esp12e, inventone, heltec_wifi_kit_8, espinotee, espino, espectro, thingdev, xinabox_cw01, sparkfunBlynk, huzzah, phoenix_v1, phoenix_v2, d1, esp01, wio_node, esp07, thing, esp_wroom_02, modwifi, oak, wio_link, wifi_slot, gen4iod, nodemcu, wifiduino, esp210, d1_mini_lite, espresso_lite_v1, espresso_lite_v2, d1_mini_pro |
| (ssid) |
Il SSID (il nome) della propria rete Wi-Fi |
| (PSK) |
La password d’accesso alla propria Wi-Fi |
| (password) |
La password locale del dispositivo, la quale verrà usata successivamente per accedervi per l’eventuale processo di aggiornamento OTA del firmware |
Al termine della procedura sarà stato creato il file luce_salotto.yaml sotto il percorso ~/esphome/ con il seguente contenuto in notazione YAML:
esphome:
name: luce_salotto
platform: ESP8266
board: nodemcuv2
wifi:
ssid: ""
password: ""
# Enable fallback hotspot (captive portal) in case wifi connection fails
ap:
ssid: "Luce Salotto Fallback Hotspot"
password: ""
captive_portal:
# Enable logging
logger:
# Enable Home Assistant API
api:
ota:
Da notare la presenza del codice per l’attivazione di un hotspot di fallback, ovvero l’hotspot Wi-Fi che il componente attiverà nel caso in cui non riuscisse a collegarsi alla Wi-Fi domestica. Ovviamente si tratta di parametri che potranno essere modificati a piacimento.
| N.b. Ogni volta che si vorrà effettuare una modifica al firmware ESPHome del dispositivo sarà sufficiente riaprire questo file, modificarlo, dopodiché seguire i passi che seguono. |
COMPILAZIONE
A questo punto il progetto è pronto alla compilazione (e, volendo, alla seguente installazione sul dispositivo target).
Per farlo, eseguire il comando:
esphome ~/esphome/nome_progetto.yaml run
Una volta eseguito il comando, il tool riporterà gli avanzamenti della compilazione:
INFO Reading configuration nome_progetto.yaml... INFO Generating C++ source... INFO Core config or version changed, cleaning build files... INFO Compiling app... INFO Running: platformio run -d nome_progetto
Al termine della compilazione la voce [SUCCESS] indicherà l’avvenuta compilazione.
La voce immediatamente precedente:
Creating BIN file ".pioenvs/nome_progetto/firmware.bin" using ".pioenvs/nome_progetto/firmware.elf"
indica dove sia stato salvato il file del firmware appena compilato (in questo caso “.pioenvs/nome_progetto“) dal nome “firmware.bin“.
INSTALLAZIONE SUL DISPOSITIVO TARGET
Al termine della compilazione, il wizard offre la possibilità di installare direttamente il firmware sul dispositivo target.
INFO Successfully compiled program. Found multiple options, please choose one: [1] /dev/ttyUSB0 (CP2102 USB to UART Bridge Controller - CP2102 USB to UART Bridge Controller) [2] Over The Air (nome_progetto.local)
Per farlo è in realtà possibile seguire sostanzialmente una delle strade che seguono:
- selezionare la voce 1, riprogrammando il dispositivo target usando un adattatore USB/TTL (leggere questo, prima) oppure un cavo USB/USB in caso che il dispositivo target disponga di una porta USB;
- selezionare la voce 2, riprogrammando il dispositivo target via Wi-Fi con procedura OTA (il dispositivo deve essere acceso, collegato alla Wi-Fi e deve già possedere il firmware ESPHome – infatti questa procedura si usa per aggiornare);
- interrompere il wizard (CTRL+Z), prelevare il firmware e seguire la solita, generica procedura manuale prevista per i precompilati (sempre con adattatore USB/TTL) – ATTENZIONE: procedura NON valida per dispositivi ESP32;
- in caso di dispositivo target già dotato di firmware Tasmota, interrompere il wizard (CTRL+Z), prelevare il firmware e, tramite interfaccia Web di Tasmota, aggiornare tale firmware utilizzando il file precompilato di ESPHome, che lo sostituirà (maggiori info qui) – ATTENZIONE: procedura NON valida per dispositivi ESP32;
In caso si utilizzi l’opzione 1, dopo l’avvenuto upload del firmware, il dispositivo target si riavvierà. Dato che nel nostro file YAML abbiamo inserito l’opzione logger (“logger:“), vedremo scorrere a video il log del device dove troveremo, tra le varie cose, anche l’indirizzo IP assegnato dal router:
Dashboard
Tutto quanto descritto sopra per le procedure tramite riga di comando (creazione progetto, compilazione, installazione sul dispositivo target) possono essere effettuate tramite interfaccia grafica via browser web (dashboard).
Per farlo è sufficiente eseguire un comando che avvii temporaneamente il server web dedicato a ESPHome indicandogli quale sia la cartella contenente i nostri progetti passati e futuri.
Nel nostro caso, il comando da eseguire è:
esphome ~/esphome dashboard
Come risposta otterremo qualcosa tipo:
INFO Starting dashboard web server on port 6052 and configuration dir ~/esphome...
che indica l’avvio del server sulla porta indicata (in questo caso 6052).
A questo punto basterà aprire il browser e collegarsi all’host:
http://IP_DEL_RASPBERRY:PORTA
per esempio
http://192.168.1.100:6052
A questo punto si aprirà l’interfaccia dashboard.
CREAZIONE 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
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 (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 agli esempi di cui sopra (Sonoff Basic R3), abbiamo visto modellarsi 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:
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.
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. |