Una premessa importante: chiunque sia intenzionato ad utilizzare Home Assistant quale proprio HUB personale ha la necessità di far propri i concetti espressi su questa pagina. Non è possibile utilizzare tale HUB senza capire nitidamente il concetto di entità: si tratta infatti di un concetto cardine.
Cos’è un’entità
Le entità sono degli oggetti astratti dotati di una propria natura, di un proprio stato e di uno o più attributi ad essi collegati. Quando un servizio o un componente domotico viene integrato a Home Assistant (le varie modalità sono spiegate qui), questa operazione genera automaticamente una o più entità.
Esse vanno immaginate, per usare una metafora, come dei mattoncini LEGO: cercheremo di spiegarci meglio utilizzando degli esempi.
Ipotizziamo di aver (senza entrare nel merito di come) aggiunto un interruttore alla configurazione di Home Assistant.
Questo interruttore sarà, esso stesso, un’entità.
Diciamo che il suo nome sia “Termoventilatore bagno”. Sul frontend di Home Assistant lo switch apparirà come segue:
Tornando alle caratteristiche descritte sopra:
- la natura di questa entità sarà, per l’appunto, di interruttore o, come da linguaggio proprio di Home Assistant, “Switch”;
- lo stato di questo tipo di entità prevede due condizioni, “on” e “off“, per l’appunto acceso e spento;
- gli attributi variano in base alla tecnologia tramite il quale tale interruttore è stato inserito in configurazione, il “come” tralasciato nell’incipit dell’esempio. Un attributo tipicamente presente in quasi tutte le entità è il “friendly_name“, oppure “icon“, o molti altri;
- i servizi variano anch’essi in base alla tecnologia usata: tipici servizi collegati a un’entità di tipo “Switch” sono “turn_on“, “turn_off“, “toggle“, rispettivamente accendi, spegni, e inverti stato.
Un altro esempio.
Poniamo il caso di avere integrato un sensore termico:
- la sua natura, è quella di “Sensor”;
- il suo stato contiene la lettura termica (tipicamente un numero decimale);
- gli attributi variano, come sempre, in base alla tecnologia e alla natura del componente: tipicamente in un sensore del genere ci si aspetta di trovare almeno “unit_of_measurement” (l’unità di misura, C o F) e l’onnipresente “friendly_name“;
- i servizi variano, in base alla tecnologia usata e alla natura del componente. Nel caso dei sensori (“Sensors”), non sono presenti servizi.
In sostanza, ogni accessorio/componente/dispositivo domotico integrato su Home Assistant è rappresentato da una o più entità. Una o più, certamente: mentre un singolo interruttore potrebbe essere integrato (in base alla tecnologica) tramite una singola entità, dispositivi più complessi potrebbero essere esposti su Home Assistant come un insieme di entità di diversa natura.
Un termostato domotico potrebbe essere rappresentato da un’entità di tipo “Climate” (per la gestione delle funzionalità di accensione/spegnimento dell’impianto termico) e da un’entità di tipo “Sensor” la quale contenga, nel suo stato, la temperatura dell’ambiente rilevata dal termostato stesso. BRIDGE/Gateway come quello della linea Xiaomi “Smart Home” (al quale si collegano direttamente innumerevoli sensori e attuatori diversi) viene visto come un’entità di tipo “Light” più tutta una serie di entità che rappresentano i componenti ad esso collegati.
E così via.
Raccontata in questo modo parrebbe evidente l’equivalenza componente domotico = entità, ma non è così.
Di fatto sono considerate entità (di natura specifica) anche i gruppi, le automazioni, gli script, le scene, le zone (e altri): qualunque componente Home Assistant ha un corrispettivo in entità definite all’interno della proprio ambiente operativo.
Anche queste entità hanno, ovviamente, uno stato, degli attributi, dei servizi collegati.
Per esempio un’automazione ha:
- la natura di “Automation”;
- lo stato “on” o “off” (ovvero se è operativa oppure no);
- attributi quali ad esempio “last_triggered” (data e ora dell’ultima volta in cui è stata eseguita), o “hidden” (per nasconderla al frontend ecc;
- servizi interni all’automazione chiamati “State Object”.
Maggiore dettagli sulle automazioni sono disponili qui.
I gruppi (“Group”) sono entità interessanti: raggruppano, per l’appunto, entità di natura diversa al fine di essere visualizzati in questo modo presso il frontend; laddove la natura delle entità contenute in un gruppo sia omogenea (eg. tutte “Light”), lo stato dell’entità gruppo assumerà lo stato “off” quando tutte le luci siano in stato “off“, e “on” quando anche una sola sia “on“.
Ipotizziamo un gruppo che raggruppi solo entità di tipo “Device Tracker” (per tracciare in modo geografico la posizione degli inquilini): lo stato di tale entità sarà “not_home” quando tutte le entità raggruppate avranno stato diverso da “home“, e avrà “home” quando almeno una abbia un proprio stato uguale a “home”.
N.b. Ai gruppi abbiamo anche dedicato una scheda ad hoc:
Integrazioni ed entità
Una volta capita la logica delle entità è facile intuire come, una volta “tradotto” un accessorio/componente/dispositivo domotico in uno o più di questi oggetti, ci si trovi ben oltre metà dell’opera. Una volta ottenuta una o più entità funzionanti sarà infatti possibile disinteressarsi degli aspetti “fisici” della propria domotica per interessarsi, concentrarsi su quelli “logici”.
Grande declinazione di questo concetto sta, per esempio, nel domotizzare qualcosa di non domotico. Ipotizziamo di rendere domotico un condizionatore tradizionale utilizzando un emettitore a infrarossi: una volta ben configurato Home Assistant otterremo un’entità di tipo HVAC (citata prima): a questo punto non ci interesserà più l’aspetto fisico della questione, ma ci limiteremo a comandare e interrogare l’entità attraverso il suo stato, i suoi attributi e i suoi servizi.
Quando, su inDomus, descrivendo un componente domotico ci soffermiamo sul tema “integrazione domotica”, ciò che facciamo è cercare di capire con quanta semplicità tale componente possa essere tradotto in una o più entità presso Home Assistant (o altri HUB).
Sull’importantissimo tema dell’integrazione consigliamo la lettura della seguente scheda:
Le varie modalità di integrazione di componenti e servizi con Home Assistant
Nomenclatura
Le entità sono definite da un nome composto da un prefisso – dato dalla tipologia di componente al quale la piattaforma d integrazione fa capo (eg. “Switch”, “Light”, “Climate” ecc.) – e da suffisso – dato dal nome stesso dell’entità, definito in configurazione.
Ipotizziamo di aver registrato una luce LED tramite la piattaforma Flux LED/Magic Light:
light:
- platform: flux_led
devices:
192.168.1.10:
name: LED 1
mode: "rgbw"
Il nome dell’entità risultante sarà: light.led_1 (si noti come gli eventuai spazi vengano sostituiti da un “_”)
Lista entità
Home Assistant metta a disposizione, sul proprio frontend, una pagina ad hoc presso la quale sono elencate tutte le entità presenti rilevate all’avvio. Tale pagina è disponibile cliccando alla voce “Strumenti per gli sviluppatori” > “Stati”.
Nella pagina che appare sono presenti, oltre alle varie entità, anche tutti i relativi stati e attributi (e relativi valori).
Per ottenere invece un elenco “grezzo” di entità e domini, si faccia riferimento a questo breve script ad hoc.
Uso
Oltre all’intuitivo utilizzo presso il frontend, le entità possono essere utilizzate (in maniera molto puntuale) anche nelle automazioni, negli script, nelle scene ecc.
La cosa interessante e di grande valore sta nel fatto che un’entità, una volta definita in configurazione, può essere utilizzata in concerto con altre entità astraendosi completamente da quale sia la fonte fisica delle entità stesse. In pratica entità collegate a dispositivi fisici diversi (di linee, tecnologie e produttori diversi) possono collaborare sullo stesso piano.
Un esempio lampante è dato dalla piattaforma “Generic Thermostat” (figlia del componente “Climate“) la quale permette di definire in configurazione un’entità di tipo termostato (virtuale) il quale prenda le decisioni tipiche di un termostato (accendere il riscaldamento sulla base di una soglia termica) partendo dalla lettura termica presente nello stato di un’altra entità (di tipo “Sensor”) e arrivando a impostare “on”/”off” lo stato di un’entità di tipo “Switch”, il quale aziona a valle l’impianto di riscaldamento (vedi progetto ad hoc).
IN AUTOMAZIONE
In ambito automazione le entità sono il pane quotidiano: possono essere utilizzate come trigger (ovvero utilizzarne uno stato e/o uno o più attributi per innescare l’automazione) e/o come condition (ovvero verificare uno stato/attributo per validare l’automazione innescata) e/o come action (ovvero variare lo stato di una o più entità a fronte dell’esecuzione dell’automazione stessa.
Un esempio:
automation: - alias: "Risveglio" trigger: - platform: time at: '07:00:00' condition: - condition: state entity_id: group.famiglia state: 'home' action: - service: light.turn_on entity_id: light.sala
Alle 7 del mattino viene verificato che l’entità “group.famiglia” abbia stato “home“, a questo punto (se la condizione è verificata) viene utilizzato il servizio “turn_on” per l’entità di tipo “Light” chiamata “light.sala“.
Ovviamente, l’entità di tipo “Automation” così creata si chiamerà “automation.risveglio“.
Comprendere la logica componente(domini)-piattaforma-entità di Home Assistant
|
⚠️ Se di Home Assistant ne sai poco ma sei interessato a capirne di più, ti suggeriamo di partire da qui. |
| 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. Se ti sei perso, a tua disposizione c'è la mappa. |