Scopi della guida:
Concetti affrontati:
|
Componenti software utilizzate:
Prerequisiti:
Dispositivi fisici utilizzati:
|
GUIDA INDICATA A UTENTI CON ISTALLAZIONE: |
|
NOTE E DISCLAIMER
|
|
| Revisione guida: 1.0 | |
Abstract
Già di per sé, l’HUB per domotica personale Home Assistant integra un efficiente database nel quale vengono archiviate tutte le misure relative alle tante integrazioni domotiche da esso previste e implementate, progressivamente, dall’utente che lo adotta.
Talvolta, per i motivi più disparati, può essere utile esportare tali informazioni (di solito solo una frazione ben precisa di esse, oppure tutte) verso una base dati “secondaria” alla scopo di archiviare informazioni, incrociarle con altri dati provenienti da altre fonti e molto altro. Sebbene non sia una pratica diffusissima, alcuni utenti trovano beneficio in questa operazione per i motivi di cui sopra nonché altri a propria discrezione.
Questa guida illustra come veicolare determinati dati verso un’istanza InfluxDB, un apprezzatissimo database gratuito dalla tipologia particolarmente adatta alle serie di dati temporali (tipo, appunto quelle provenienti dalla propria domotica). L’integrazione, come vedremo, è possibile anche da InfluxDB a Home Assistant, creando uno o più sensori alimentati dal database esterno.
| NOTA. Attenzione: tale integrazione mono o bi-direzionale non si sostituisce al database di Home Assistant, ma semmai lo affianca. Se il proprio obiettivo è quello di utilizzare un altro database per l’esecuzione di Home Assistant, di certo non è questa la guida da seguire: allo scopo, si rimanda infatti alla documentazione ufficiale realtiva al tema. |
Si parte
Assunti
Si assume che Home Assistant ovviamente sia già operativo in una delle tante possibilità di implementazione previste e documentate.
Inoltre, si assume di avere a disposizione un’istanza di InfluxDB già operativa alla quale avere accesso. Anche InfluxDB prevede molte divese possibilità di implementazione; noi di inDomus abbiamo realizzato una guida per Mini PC/Intel NUC oppure per Raspberry Pi che montino sistema operativo Linux-like.
Se invece si dispone di un’installazione Home Assistant OS o Home Assistant Supervised, la guida corretta è questa.
Integrazione
Come abbiamo detto, è possibile effettuare un’integrazione che invii dati da Home Assistant a InfluxDB (solo il set di dati selezionati poco fa) e/o una che invii dati da InfluxDB a Home Assistant.
Da Home Assistant a Influx DB
Quella più comune è l’integrazione che fa sì che l’utente possa esportare dati dalla propria istanza di Home Assistant a quella InfluxDB. Vediamo come.
Scelta dei dati
In base agli scopi per cui si decide di integrare le misure della propria istanza Home Assistant verso InfluxDB, è necessario – a monte – effettuare una scelta puntuale dei domini e delle entità da includere in tale integrazione. Questo perché è abbastanza folle pensare di replicare qualsiasi dato presente su Home Assistant verso InfluxDB: solitamente, sono solo alcuni dati esser eventualmente storicizzati esternamente all’HUB (ma la scelta, comunque, è libera).
| NOTA. Di nuovo: tale integrazione mono o bi-direzionale non si sostituisce al database di Home Assistant, ma semmai lo affianca. Se il proprio obiettivo è quello di utilizzare un altro database per l’esecuzione di Home Assistant, di certo non è questa la guida da seguire: allo scopo, si rimanda infatti alla documentazione ufficiale realtiva al tema. |
I dati possono essere inclusi/esclusi utilizzando:
- domini (eg. “sensor“, “binary_sensor“, “switch” eccetera);
- entità specifiche (eg. “sensor.temperatura_camera“);
- entità selezionate tramite nomenclatura (eg. “sensor.*_camera“, ovvero tutti i sensor che finiscano con _camera);
Una volta effettuata la scelta è dunque possibile provvedere alla configurazione dell’integrazione.
configurazione
UTENTI HOME ASSISTANT OS/SUPERVISED (InfluxDB installato con add-on)
Provvediamo ora a integrare Home Assistant verso InfluxDB. Per effettuare tale azione è necessario reperire le seguenti informazioni lato InfluxDB:
| Dato | Spiegazione |
| host | L’indirizzo IP presso il quale è istanziato InfluxDB, il quale se istanziato tramite Docker non può mai essere 127.0.0.1 bensì l’indirizzo dell’host ospitatante Docker stesso |
| port | La porta TCP/IP presso il quale è accedibile il frontend InflxuDB (l’interfaccia web), solitamente la 8086 |
| database | Il nome del database, presso InfluxDB, sul quale archiviare i dati Home Assistant |
| username | Il nome utente (presso InfluxDB) utile per l’accesso al database di cui sopra; |
| password | La relativa password dell’utente di cui sopra. |
Per prima cosa, recarsi alla voce “InfluxDB Admin” e creare un database ex-novo, chiamandolo come meglio si crede (eg. “influxdb“).
Clicare in alto, presso la voce “Users“, per creare un nuovo utente (eg. “influxdb_user“) al quale attribuire i diritti di lettura e scrittura (READ / WRITE) al database poco prima creato).
Effettuata la raccolta dei primi dati di connessione, inserire nel file di configurazione di Home Assistant la seguente porzione di codice:
influxdb:
host: a0d7b954-influxdb
port: 8086
database: influxdb
username: influxdb_user
password: <PASSWORD_UTENTE>
max_retries: 3
default_measurement: state
avendo cura di personalizzare i cinque campi come spiegato in precedenza.
I restanti sono utili per accedere correttamente a InfluxDB (ve ne sono altri, svariati, molto personalizzabili).
Per completare la configurazione vanno poi indicate le entità (o meglio, i relativi stati) e/o i gli interi domini da inviare a InfluxDB.
Consigliamo di inviare una sola, iniziale entità tra quelle scelte in precedenza, per verificare che tutto funzioni correttamente. Ipotizziamo di aver scelto l’entità sensor.time, aggiungeremo:
include:
entities:
- sensor.time
dopodiché salvare e provvedere al riavvio di Home Assistant.
Se tutto avrà funzionato lo si capirà sia dai log di Home Assistant (che non dovranno dare alcun errore in merito all’integrazione InfluxDB) ma sopratutto dal fatto che, collegandosi all’interfaccia InfluxDB (alla voce “Data Explorer“), selezionando il corretto database e cercando nella colonna subito alla sua destra, sarà certamente possibile riscontrare la presenza del sensore indicato in configurazione.
Complimenti!
Da questo momento in poi Home Assistant provvederà all’injection di dati verso InfluxDB i quali, ovviamente, andranno ampliati aggiungendo domini ed entità alla configurazione di cui sopra.
Se per esempio si volessero inviare tutti i sensori verso InfluxDB, la configurazione aggiuntiva sarebbe:
include:
domains:
- sensor
E così via.
Un esempio di configurazione generica e completa è:
influxdb:
api_version: 2
ssl: false
host: INDIRIZZO_IP_INFLUXDB
port: PORTA_INFLUXDB
token: MIO_TOKEN
organization: NOME_UTENTE
bucket: BUCKET_NAME
tags:
source: HA
tags_attributes:
- friendly_name
default_measurement: units
exclude:
entities:
- zone.home
domains:
- persistent_notification
- person
include:
domains:
- sensor
- binary_sensor
- sun
entities:
- weather.home
Tutti i dettagli relativi alle variabili di configurazione sono disponibili qui.
Altre info sulla configurazione dell’integrazione sono disponibili presso la documentazione ufficiale dell’add-on.
ALTRI UTENTI (InfluxDB installato via Docker o in altri modi)
Provvediamo ora a integrare Home Assistant verso InfluxDB. Per effettuare tale azione è necessario reperire le seguenti informazioni lato InfluxDB:
| Dato | Spiegazione |
| host | L’indirizzo IP presso il quale è istanziato InfluxDB, il quale se istanziato tramite Docker non può mai essere 127.0.0.1 bensì l’indirizzo dell’host ospitatante Docker stesso |
| port | La porta TCP/IP presso il quale è accedibile il frontend InflxuDB (l’interfaccia web), solitamente la 8086 |
| organization | In pratica, il nome utente che si vuole usare presso InfluxDB. |
| bucket | In pratica, il database sul quale salvare i dati (leggi di più sui bucket) |
| token | Il token di accesso al proprio bucket |
Dei dati di cui sopra, quello più “complicato” (ma non lo è, in realtà) da ottenere è il token di accesso, dato che gli altri sono pressoché tutti già noti all’utente, se InfluxDB è istanziato correttamente ed è funzionante.
Per creare un token d’accesso, collegarsi via browser all’interfaccia web di InfluxDB, accedere alla voce “Load Data” > “API Tokens” e cliccare su “GENERATE API TOKEN“.
In questa fase sarà possibile generare un generico token di accesso totale (“All Access API token“) oppure uno limitato (“Custom API Token“), il quale consenta solo l’accesso a determinate risorse di InfluxDB: la scelta è personale.
Viene chiesto come chiamare il token:
dopodiché esso viene generato (stringa viola):
ricordarsi di salvare da parte la stringa, perché successivamente non sarà più possibile leggerla.
Effettuata la raccolta dei primi dati di connessione, inserire nel file di configurazione di Home Assistant la seguente porzione di codice:
influxdb:
host: INDIRIZZO_IP_INFLUXDB
port: PORTA_INFLUXDB
token: MIO_TOKEN
organization: NOME_UTENTE
bucket: NOME_BUCKET
api_version: 2
ssl: false
max_retries: 3
avendo cura di personalizzare i cinque campi come spiegato in precedenza.
I restanti sono utili per accedere correttamente a InfluxDB (ve ne sono altri, svariati, molto personalizzabili).
Per completare la configurazione vanno poi indicate le entità (o meglio, i relativi stati) e/o i gli interi domini da inviare a InfluxDB.
Consigliamo di inviare una sola, iniziale entità tra quelle scelte in precedenza, per verificare che tutto funzioni correttamente. Ipotizziamo di aver scelto l’entità sensor.time, aggiungeremo:
include:
entities:
- sensor.time
dopodiché salvare e provvedere al riavvio di Home Assistant.
Se tutto avrà funzionato lo si capirà sia dai log di Home Assistant (che non dovranno dare alcun errore in merito all’integrazione InfluxDB) ma sopratutto dal fatto che, collegandosi all’interfaccia InfluxDB (alla voce “Data Explorer“), in basso a sinistra selezionando il corretto buket e cercando nella colonna subito alla sua destra, sarà certamente possibile riscontrare la presenza del sensore indicato in configurazione (nell’esempio sensor.time):
Complimenti!
Da questo momento in poi Home Assistant provvederà all’injection di dati verso InfluxDB i quali, ovviamente, andranno ampliati aggiungendo domini ed entità alla configurazione di cui sopra.
Se per esempio si volessero inviare tutti i sensori verso InfluxDB, la configurazione aggiuntiva sarebbe:
include:
domains:
- sensor
E così via.
Un esempio di configurazione generica e completa è:
influxdb:
api_version: 2
ssl: false
host: INDIRIZZO_IP_INFLUXDB
port: PORTA_INFLUXDB
token: MIO_TOKEN
organization: NOME_UTENTE
bucket: BUCKET_NAME
tags:
source: HA
tags_attributes:
- friendly_name
default_measurement: units
exclude:
entities:
- zone.home
domains:
- persistent_notification
- person
include:
domains:
- sensor
- binary_sensor
- sun
entities:
- weather.home
Tutti i dettagli relativi alle variabili di configurazione sono disponibili qui.
Da InfluxDB a Home Assistant
Come detto, non solo è possibile inviare dati da salvare da Home Assistant a InfluxDB, ma anche viceversa inviare dati – magari calcolati e/o provenienti da altre fonti – da InfluxDB a Home Assistant, eseguendo delle vere e proprie query lato InfluxDB.
| N.b. Scrivere query InfluxDB non è difficile – se si domina l’argomento. Se però non si ha alcuna esperienza in ambito database, prima di avventurarsi nelle configurazioni che seguono conviene studiare un po’. |
Questo è possibile farlo solo generando dei sensori lato HUB; la configurazione si effettua per esempio così:
sensor:
- platform: influxdb
api_version: 2
token: MIO_TOKEN
organization: NOME_UTENTE
queries_flux:
- group_function: mean
imports:
- strings
name: "Umidità media di ieri"
query: >
filter(fn: (r) => r._field == "value" and r.domain == "sensor" and strings.containsStr(v: r.entity_id, substr: "humidity"))
|> keep(columns: ["_value"])
range_start: "-1d"
L’esempio di cui sopra genera un sensore sensor.umidita_media_di_ieri tramite una query che, a partire da altri dati provenienti da altri sensori precedentemente intregrati da Home Assistant verso InfluxDB, effettua il calcolo.
Naturalmente è un esempio che non consigliamo, nello specifico, di effettuare: certi calcoli è serenamente possibile effettuarli tramite dei sensore template lato Home Assistant. Si tratta appunto solo di un esempio: se proprio si vuole effettuare delle query lato InfluxDB, la cosa deve avere un senso (per esempio effettuare calcoli non effettuabili tramite Home Assistant perché la fonte dati, magari, non è integrabile all’HUB).
Uso dei dati
Beh, l’uso che di farà dei dati integrati su InfluxDB è a totale appannaggio dell’utente. Uno degli esempi classici è effettuare storicizzazione di lungo corso di dati di dettaglio di alcune entità, cosa che non si vuol magari fare lato Home Assistant, lasciando (giustamente) a quest’ultimo una configurazione “recorder” più snella.
Altra possibilità mutualmente inclusiva è quella di utilizzare Grafana, collegato a InfluxDB, per generare grafici molto più accattivanti e parlanti rispetto, magari, a quelli realizzabili con le dashboard di Home Assistant.
Come sempre, il limite è la fantasia.
|
⚠️ 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. |