Comprendere la logica componente(domini)-piattaforma-entità di Home Assistant

Quello di entità è, per chiunque voglia approcciare l’uso di Home Assistant, uno dei concetti da padroneggiare e comprendere interamente. Il motivo è semplice: l’entità è il mattoncino primario nella definizione della propria domotica basata su questo HUB personale sia in termini di interfaccia che di automazione.

Ciò che però è altrettanto importante conoscere è la catena di elementi che generano tali entità e che, in definitiva, ne definiscono la natura, la quale è riconoscibile dalla prima parte del nome di ognuna di esse (eg. “device_tracker.edoardo” è un’entità di tipo “Device Tracker“).

Su Home Assistant esistono due tipologie di elementi utili alla definizione delle entità: i “componenti” e le “piattaforme d’integrazione“. Purtroppo tali elementi vengono genericamente confusi e raccolti sotto la voce “Componenti”, quando in realtà si tratta di elementi – sebbene strettamente legati – distinti e molto diversi tra loro.

Componenti

I componenti (o “domini”) sono macro-famiglie. Tra i primissimi elementi inclusi su Home Assistant, sono quelli dalla quale deriva la natura delle entità ad essi collegate. Esempi classici di componenti basilari di Home Assistant sono “Light” (per la definizione delle entità di tipo luci), “Switch” (per gli interruttori), “Climate” (per i termostati e unità termiche) e così via. Ogni componente prevede servizi e proprietà: i primi, utili al controllo delle entità (nelle automazioni, negli script ecc.), le seconde, utili a raccogliere dati da esse provenienti.
Per il componete “Light”, per esempio, un tipico servizio è “light.turn_on“, utile per accedere l’entità, mentre una proprietà tipica invece è lo stato, il quale serve a sapere – solitamente – se la luce sia accesa o spenta.

Piattaforme d’integrazione

I componenti hanno delle figlie: le “piattaforme d’integrazione“. Questi elementi – sviluppati dalla community Open Source – implementano le specifiche dei componenti di Home Assistant allo scopo di ottenere l’integrazione dei più disparati dispositivi e servizi.

Portiamo l’esempio della piattaforma “Nanoleaf“: tale elemento è utile all’integrazione dei sistemi d’illuminazione della Nanoleaf ed è stato sviluppato in modo da generare solo entità di tipo “Light”, unico componente al quale tale piattaforma fa capo. Esistono invece altre piattaforme molto più strutturate, le quali generano entità di diversa natura, facendo quindi capo alle specifiche di più componenti diversi. È il caso – sempre per portare un esempio – della piattaforma per l’integrazione dei componenti Tado: essa genera svariate entità di diversa natura, per esempio di tipo “Climate”, “Device Tracker” ed altre.

Le piattaforme di integrazione possono essere di primo o di secondo livello. Quelle di primo livello hanno una dignità propria, per così dire, ovvero in configurazione vengono indicate con una voce a sé; la sopracitata “Tado” è di primo livello, infatti si implementa così:

tado:
  username: mio_username
  password: mia_password

La sopracitata piattaforma “Nanoleaf Light Panel” è invece di secondo livello, infatti in configurazione si implementa facendone riferimento sotto il blocco del componente “Light”:

light:
  platform: nanoleaf
  host: ip_del_device
  token: mio_token

I “componenti” e le “piattaforme di integrazione” di primo livello si confondono perché, appunto, hanno una voce propria in configurazione, ma ciò nonostante restano elementi molto diversi tra loro.

È molto importante leggere sempre con attenzione le “Breaking Changes” degli aggiornamenti di Home Assistant: capita infatti a volte che alcune piattaforme vengano promosse (o retrocesse) da secondo a primo grado (o viceversa), rendendo necessario un adeguamento in configurazione. Se per esempio “Nanoleaf Light Panel” venisse promossa a piattaforma di primo livello, probabilmente la sua configurazione varierebbe da così

light:
  platform: nanoleaf
  host: ip_del_device
  token: mio_token

a (presumibilmente) così:

nanoleaf:
  host: ip_del_device
  token: mio_token

È il caso di PiHole, la quale, in occasione dell’aggiornamento 0.99, è stata promossa a piattaforme di integrazione di primo livello.

L’elenco completo dei componenti e delle piattaforme di integrazione Home Assistant è disponibile qui.