Integrare componenti ESPHome a Home Assistant (via API)

SCOPI DELLA GUIDA: Integrare a Home Assistant qualunque componente (e relative funzionalità) dotato di firmware ESPHome Livello di difficoltà: basso Categoria d’integrazione: Local Push CONCETTI AFFRONTATI: Configurazione software	COMPONENTI SOFTWARE UTILIZZATE: Home Assistant Piattaforma Home Assistant “ESPHome” (via API ESPHome) Firmware ESPHome Prerequisiti: Home Assistant configurato e funzionante Firmware ESPHome già installato sul componente/i da integrare DISPOSITIVI FISICI UTILIZZATI: Il computer sul quale è in esecuzione Home Assistant Uno o più componenti dotati di firmware ESPHome
GUIDA INDICATA A UTENTI CON ISTALLAZIONE:
NOTE E DISCLAIMER qualsiasi eventuale modifica agli impianti domestici dev'essere progettata e realizzata SOLO da personale qualificato; qualsiasi modifica non prevista attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno infatti puro scopo didattico) e fa decadere garanzia, omologazioni e certificazioni di qualità; dei dispositivi interessati; tutte le tecniche descritte si intendono applicate a software e firmware aggiornati alle ultime versioni disponibili; questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In caso di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat; gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione; se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 2.0

Abstract

Dopo aver visto nel dettaglio cosa sia nello specifico il sempre più noto firmware ESPHome e come si configuri, compili e installi sui componenti supportati (tipicamente quelli basati su SOC ESP8266 e ESP32, come i Sonoff, gli Shelly e molti altri) è giunto il momento di vedere come si integri al più noto e adottato degli HUB per domotica personale, Home Assistant.

L’integrazione di componenti dotati di ESPHome verso Home Assistant è piuttosto semplice: a differenza di altri ottimi firmware (vedi Tasmota), ESPHome risulta un po’ complicato da capire all’inizio, nonché da configurare, ma risulta estremamente elementare in fase di integrazione.

Dato che le caratteristiche funzionali del componente da integrare su l’Home Assistant (interruttori, sensori, comportamenti specifici ed altro) vengono decise a monte (in fase di configurazione del firmware, prima ancora di installarlo sul componente stesso), Home Assistant si limita a “prendere atto di ciò che trova”: se per caso configuro un Sonoff 4CH in modo che esponga solo due canali su quattro, in fase di integrazione Home Assistant censirà il componente come un singolo device dotato di due entità di tipo interruttore (“Switch”) e niente di più.

L’integrazione – come spiegato anche sulla pagina della piattaforma sul sito di Home Assistant – utilizza le API proprie del firmware, il che permette un’ottima, efficacissima integrazione di tipo Local Push.

API

Affinché l’integrazione vada a buon fine è strettamente necessario che, in fase di configurazione del proprio firmware, venga inclusa la componente API, ovvero la presenza – nel file di configurazione del firmware – di un blocco similare al seguente:

# Esempio di configurazione API di ESPHome
api:
  encryption:
    key: "metterequidentrounachiavepersonalequalunque" #la chiave per integrare il NodeMCU su Home Assistant 

Attenzione però: non stiamo parlando del file di configurazione di Home Assistant (che ha tutt’altro scopo), ma del file di configurazione (anch’esso scritto in notazione YAML, il che potrebbe generare confusione nella testa di chi legge) con il quale si definiscono le caratteristiche del firmware ESPHome destinato al componente target. Di questo aspetto specifico parliamo diffusamente qui.

La chiave indicata sarà quella che andrà fornita a Home Assistant in fase di configurazione dell’integrazione.

Assunti

Si assume quindi che:

• il componente (o i componenti) da integrare siano già dotati di firmware ESPHome appropriatamente configurato in base al tipo di componente (in merito a questo far riferimento alla scheda ESPHome alle sue varie ramificazioni);
• il firmware ESPHome sia stato dotato di componente API (come qui sopra spiegato);
• il componente sia acceso e abbia avuto accesso alla rete Wi-Fi domestica, rete domestica sulla quale sarà attestato anche Home Assistant.

Integrazione

L’integrazione può avvenire in due modi: manualmente o tramite autodiscovery. Tipicamente si utilizza quest’ultima opzione, ma qualora nelle notifiche non appaia la dicitura che comunica l’avvenuto auto-riconoscimento di un nuovo device compatibile ESPHome è sufficiente entrare nella sezione “Integrazioni” dell’HUB, cliccare su “+” e cercare e selezionare “ESPHome”:

Una volta scelto “ESPHome” verrà richiesto l’indirizzo IP del componente:

Arrivati a questo punto ci si ricongiunge al percorso che si effettua in caso di autodiscovery, ovvero la richiesta della chiave API per consentire a Home Assistant di accedere al componente.

A questo punto l’integrazione verrà completata:

Nello screenshot d’esempio è riportato il caso di un già precedentemente citato Sonoff 4CH PRO, il quale viene riconosciuto come tale in base alla configurazione precedentemente determinata in fase di configurazione, compilazione e installazione del firmware ESPHome.

Uso ordinario

Completata l’integrazione, nell’elenco delle integrazioni attive apparirà una nuova voce; nel caso del nostro Sonoff 4CH d’esempio apparirà come segue:

Come si nota il Sonoff 4CH usato a mo’ d’esempio viene riconosciuto come 1 singolo dispositivo (device) e 10 entità di vario tipo, nel dettaglio sono:

Alcune entità sono di tipo “Switch“, altre di tipo “Binary Sensor” (le quali “mappano” i quattro pulsanti del Sonoff 4CH, che potranno quindi essere usati per i più disparati usi), una di tipo “Light” (per accendere/spegnere il LED blu presente sull’unità) e infine un altro “Binary Sensor” che fornisce lo stato operativo dell’unità.

Tutto questo è il prodotto della porzione di configurazione ESPHome dedicata alla personalizzazione del componente; in questo caso, quella in uso è stata la seguente:

  binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      mode: INPUT_PULLUP
      inverted: True
    name: "Sonoff 4CH Button 1"
  - platform: gpio
    pin:
      number: GPIO9
      mode: INPUT_PULLUP
      inverted: True
    name: "Sonoff 4CH Button 2"
  - platform: gpio
    pin:
      number: GPIO10
      mode: INPUT_PULLUP
      inverted: True
    name: "Sonoff 4CH Button 3"
  - platform: gpio
    pin:
      number: GPIO14
      mode: INPUT_PULLUP
      inverted: True
    name: "Sonoff 4CH Button 4"
  - platform: status
    name: "Sonoff 4CH Status"

switch:
  - platform: gpio
    name: "Sonoff 4CH Relay 1"
    pin: GPIO12
  - platform: gpio
    name: "Sonoff 4CH Relay 2"
    pin: GPIO5
  - platform: gpio
    name: "Sonoff 4CH Relay 3"
    pin: GPIO4
  - platform: gpio
    name: "Sonoff 4CH Relay 4"
    pin: GPIO15

output:
  # Register the blue LED as a dimmable output ....
  - platform: esp8266_pwm
    id: blue_led
    pin: GPIO13
    inverted: True

light:
  # ... and then make a light out of it.
  - platform: monochromatic
    name: "Sonoff 4CH Blue LED"
    output: blue_led

Ovviamente ogni componente avrà la propria configurazione, la quale non solo genererà entità specifiche verso Home Assistant, ma determinerà anche gli specifici comportamenti dell’unità in sé.

Una lista di configurazione preconfezionate è disponibile qui.