community italiana di domotica personale
 
Configurare, compilare e installare il firmware ESPHome con Raspberry Pi con Docker

Configurare, compilare e installare il firmware ESPHome con Raspberry Pi con Docker

11 minuti di lettura
SCOPI DELLA GUIDA:
  • Utilizzare Raspberry Pi (con Docker su sistema operativo Raspbian) al fine di configurare, compilare e installare su un dispositivo compatibile 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 Raspberry Pi OS 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

Installare Docker

Installare Docker su Raspberry Pi dotato di sistema operativo Raspbian è piuttosto rapido e semplice: esiste infatti sia una procedura completamente automatica oppure una manuale. Entrambe le procedure sono illustrate in dettaglio in questa breve guida.

Se si dispone già di Docker, va da sé che questo passaggio possa essere saltato.

Gestione progetti

Una volta installato Docker, i i tool necessari per gestire ESPHome sono utilizzabili sia come tool da riga di comando sia da interfaccia web grazie a un container il quale, evocato, provveda a cancellarsi contestualmente dopo l’utilizzo. ESPHome va infatti considerato per quel che è, ovvero un insieme di tool concepiti allo scopo di creare configurazioni, compilare il firmware e installarlo sui dispositivi target.

A questo punto sarà quindi 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:

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.

Prima di tutto, ogni volta che provvede a usare ESPHome, si consiglia di utilizzare il comando:

docker pull esphome/esphome

per aggiornare l’immagine della suite di tool, qualora fosse stata aggiornata dallo sviluppatore.

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:

docker run --rm --net=host -v "${PWD}":/config -it esphome/esphome nome_progetto.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 nome_progetto.yaml sotto il percorso ~/ 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:

docker run --rm -v "${PWD}":/config --net=host --device=/dev/ttyUSB0 -it esphome/esphome nome_progetto.yaml run

avendo cura di personalizzare le seguenti variabili:

–device Se, dopo la compilazione, si vorrà provvedere alla contestuale installazione sul dispositivo utilizzando un adattatore USB/TTL (o un cavo USB/USB, laddove il dispositivo sia dotato di porta USB, come per esempio nel caso di NodeMCU) è necessario indicare tramite il parametro –device quale sia la porta logica assegnata dal sistema operativo al dispositivo connesso (il quale va connesso prima dell’esecuzione del comando). Esempio: /dev/ttyUSB0.

N.b. Omettendo il campo –device, dopo la compilazione EPSHome tenterà comunque l’aggiornamento OTA cercando sulla rete locale l’host nome_progetto.local, ovvero il dispositivo target evidentemente già programmato in precedenza con tale firmware.

nome_progetto.yaml Il nome del file yaml rappresentante il proprio progetto da compilare e installare

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:

  1. 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;
  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) – ATTENZIONE: procedura NON valida per dispositivi ESP32;
  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) – 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:

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 per avviare la dashboard web (tramite istanziamento temporaneo di un container Docker ad hoc) è

docker run -d --rm --name esphome -v "${PWD}":/config --device=/dev/ttyUSB0 --net=host --restart unless-stopped -it esphome/esphome

avendo cura di personalizzare la seguente variabile:

–device Se, dopo la compilazione, si vorrà provvedere alla contestuale installazione sul dispositivo utilizzando un adattatore USB/TTL (o un cavo USB/USB, laddove il dispositivo sia dotato di porta USB, come per esempio nel caso di NodeMCU) è necessario indicare tramite il parametro –device quale sia la porta logica assegnata dal sistema operativo al dispositivo connesso (il quale va connesso prima dell’esecuzione del comando). Esempio: /dev/ttyUSB0.

N.b. Omettendo il campo –device, dopo la compilazione EPSHome tenterà comunque l’aggiornamento OTA cercando sulla rete locale l’host nome_progetto.local, ovvero il dispositivo target evidentemente già programmato in precedenza con tale firmware.

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, ESP32 e similari per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.

   
Telegram News ChannelESP32