Configurare, compilare e installare il firmware ESPHome tramite Raspberry Pi (con Raspbian, o Linux)

9 minuti di lettura
SCOPI DELLA GUIDA:
  • Utilizzare Raspberry Pi (con sistema operativo Raspbian) 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:
GUIDA maggiormente indicatA per:

Raspbian - Linux

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.

Gli utenti che dispongano di Raspberry Pi dotato di sistema operativo Raspbian possono utilizzarlo, tramite l’installazione di un package di tool, la configurazione, la compilazione e per sino l’installazione (via Wi-Fi) 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

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 Raspbian 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 progetti

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.

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

Il software richiederà il completamento 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 sul dispositivo target.
Per farlo, eseguire il comando:

esphome ~/esphome/luce_salotto.yaml run

Al termine della compilazione la voce [SUCCESS] indicherà l’avvenuta compilazione.
La voce immediatamente precedente:

Creating BIN file ".pioenvs/salotto/firmware.bin" using ".pioenvs/salotto/firmware.elf"

indica dove sia stato salvato il file del firmware appena compilato (in questo caso.pioenvs/salotto“) dal nome “firmware.bin“.

INSTALLAZIONE SUL DISPOSITIVO TARGET

Al termine della compilazione, il wizard consente di installare direttamente il firmware sul dispositivo target.
Per farlo è in realtà possibile seguire sostanzialmente  una delle quatto strade che seguono:

  1. selezionare la voce 1, riprogrammando il dispositivo target usando un adattatore USB/TTL (leggere questo, prima);
  2. 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);
  3. interrompere il wizard (CTRL+Z), prelevare il firmware e seguire la solita, generica procedura manuale prevista per i precompilati (sempre con adattatore USB/TTL);
  4. 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).

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:

ESPHome - Log

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 /home/pi/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

Immaginando questa volta che il dispositivo target sia un Sonoff Basic R3: creeremo 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 le sue informazioni minimali, esattamente come nel caso del wizard da riga di comando.


I progetti vengono visualizzati in dashboard sotto forma di elenco (sia creati sulla Dashboard sia quelli creati via riga di comando – inclusi i pre-esistenti).

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).
COMPILAZIONE

Se si cliccasse direttamente su “Compile“, la dashboard 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. La stessa vista sopra, per capirci.

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 SUL DISPOSITIVO TARGET

L’interfaccia Dashboard consente di installare il firmware solo in modalità OTA, cliccando su “UPLOAD” (il dispositivo deve essere acceso, collegato alla Wi-Fi e deve già possedere il firmware ESPHome – infatti questa procedura si usa per aggiornare);

Altrimenti (in caso di installazione ex-novo), si faccia sempre riferimento alle considerazioni alle modalità di riprogrammazione fatte sopra.

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 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.


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