community italiana di domotica personale
 
Integrare i dati della domotica personale Home Assistant verso InfluxDB (e viceversa)

Integrare i dati della domotica personale Home Assistant verso InfluxDB (e viceversa)

Scopi della guida:
  • Far in modo di salvare dati provenienti dall’HUB per la domotica personale Home Assistant sul database InfluxDB (per storicizzazione, incroci con altri dati e molto altro), e/o inviare dei dati raccolti/calcolati da InfluxDB verso Home Assistant
  • Livello di difficoltà: medio/bassa
  • Categoria d’integrazione: Local Push
Concetti affrontati:
  • Configurazione software
Componenti software utilizzate:
Prerequisiti:
Dispositivi fisici utilizzati:
GUIDA INDICATA A UTENTI CON ISTALLAZIONE:
Ambienti Home Assistant HassOS-Supervised-Core
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: 1.0

InfluxDB - Home Assistant

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“.

InfluxDB - Generate API Token
generare un nuovo API token lato InfluxDB.

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:

InfluxDB - Generate API Token - 2

dopodiché esso viene generato (stringa viola):

InfluxDB - Generate API Token - 3

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):

InfluxDB - Data Explorer
un esempio.

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.

Vetrina

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.