“configuration.yaml”: capire il file di configurazione di Home Assistant

5 minuti di lettura
● Resta sempre aggiornato grazie al nostro canale Telegram e alla nostra newsletter settimanale!
Scopi della guida:
  • Comprendere i concetti di base relativi al file di configurazione di Home Assistant
  • Livello di difficoltà: basso
Concetti affrontati:
  • configurazione software
Componenti software utilizzate:
Prerequisiti:
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno puro scopo didattico);
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere garanzia, omologazioni e certificazioni di qualità.
Revisione guida: 3.4

Abstract

Il popolare HUB personale software Home Assistant prevede svariate modalità per la sua configurazione e per l’integrazione dei più disparati componenti domotici e servizi di vario tipo. Principalmente, per agire sulla sua configurazione (intesa sia come quella relativa alle sue componenti core sia delle integrazioni di componenti domotiche e servizi) si agisce su un file capofila chiamato “configuration.yaml“, un semplice file di testo scritto in formato YAML.

Tale file solitamente è posizionato nella directory preposta alla configurazione dell’HUB; ad esempio, quando Home Assistant è installato come applicativo su sistema operativo Raspbian solitamente esso si trova presso il percorso:

/home/homeassistant/.homeassistant/

Per quanto riguarda l’installazione HASSIO, solitamente, si trova presso il percorso:

/config/

Oppure, sempre su HASSIO (ma installato su Docker@Raspbian):

/usr/share/hassio/homeassistant/


In buona sostanza si tratta di un file di testo contenente una serie di “blocchi” (senza uno specifico ordine), ciascuno dei quali rappresenta uno specifico componente/piattaforma di Home Assistant, componenti che, quando configurati, definiscono una o più integrazioni (eg. luci, switch, condizionatori e chi più ne ha più ne metta) oppure la configurazione di specifiche funzionalità proprie dell’HUB (eg. la definizione delle “zone geografiche“). A parte specifiche modifiche (ad automazioni, script, scene), ogni modifica prevede il riavvio dell’HUB al fine di renderle operative.

Per portare un esempio, quando volessimo integrare nella domotica basata su Home Assistant una luce, diciamo, della serie Magic, utilizzeremmo la piattaforma ad essa dedicata “Flux Led/Magic Light“, la quale è “figlia” del componente “Light“.

Il “blocco” relativo a questa integrazione corrisponderebbe a:

# Esempio di entry su configuration.yaml
light:
  - platform: flux_led
    automatic_add: True

dove la voce “light:” definisce l’inizio del blocco relativo al componente “Light” e il sottoblocco “platform:” definisce l’entità vera e propria, prodotta specificando la piattaforma, ovvero “flux_led“.

  • un componente (component) fornisce la logica core per specifiche funzionalità (ad esempio “light“);
  • una piattaforma (platform) crea la connessione ad un software e/o un hardware specifici (ad esempio “flux_led“).

Si presti attenzione al fatto che l’indentazione ha un ruolo determinante nella definizione delle relazioni definite in YAML – la maggior parte degli errori di configurazione nasce, infatti, da un’indentazione errata. Gli elementi indentati sono annidati all’interno di elementi di livello più “alto”. Nell’esempio sopra, “platform: flux_led” è una proprietà (annidata) del componente “notify“.
Ogni grado di indentazione è definito da due spazi, non tre, non uno: due.

Per convenzione, l’indentazione è definita tramite due spazi per ogni livello di annidamento.
Le righe precedute dal carattere “#” sono ignorate dal sistema.

Prima di dare in pasto qualsivoglia configurazione a Home Assistant, è sempre buona regola validare il proprio file YAML tramite il sito YAMLint.


Non tutte le integrazioni, per essere implementate, prevedono delle piattaforme soggiacenti, ma possono essere usate e configurate autonomamente.

L’esempio a seguire mostra una configurazione del componente “Input Select” che produce una lista di voci di scelta (come forma di input da parte dell’utente a livello di interfaccia grafica). Come si nota, non viene indicata alcuna piattaforma.

Altre proprietà (ad esempio “name“) sono specificate utilizzando mappature. Si noti come la seconda riga presenti solo “alzo_tapparelle:” senza alcun valore sulla stessa linea. Questo perché di fatto apre alle linee successive un annidamento utile a definire i suoi parametri:

input_select:
  alzo_tapparelle:
    name: Alzo delle tapparelle
# Le opzioni di scelta vengono definite tramite la seguente mappatura
    options:
    - 0
    - 1
    - 2
    - 3
    initial: 0

L’esempio successivo invece mostra l’annidamento di una collezione di mappature in una mappatura stessa: in questo caso vengono definiti due “Sensor” (sensori) che utilizzano la piattaforma “MQTT Sensor” i quali abbiano differenti valori di “state topic” (una delle proprietà tipiche di un sensore MQTT):

sensor:
  - platform: mqtt
    state_topic: sensor/topic
  - platform: mqtt
    state_topic: sensor2/topic
UTILIZZARE LE VARIABILI D’AMBIENTE

Nel file di configurazione configuration.yaml (così come negli altri file sidecar ad esso collegati) è possibile utilizzare variabili d’ambiente. Per utilizzarne una è sufficiente indicate “!env_var” seguito dal nome della variabile stessa.
Ad esempio:

http:
  api_password: !env_var PASSWORD

In caso la variabile non sia definita, è possibile indicare in configurazione il valore da utilizzare in alternativa:

http:
  api_password: !env_var PASSWORD password_di_default  
INCLUDERE FILE SIDECAR (SUDDIVISIONE)

Dato che all’ampliarsi della configurazione aumenta anche la lunghezza del file, per migliorarne la leggibilità è possibile indicare al suo interno rimandi specifici a file esterni utilizzando la particella “!include” seguita dal nome del file da includere:

lights: !include lights.yaml

In sostanza è possibile mantenere “configuration.yaml” quale “spina dorsale” della configurazione e utilizzare più file (.yaml) quali “costole” presso le quali configurare le entità derivanti dai vari componenti dichiarati nel file principale.

La suddivisione del file “configuration.yaml” in più file sidecar è una tecnica che riduce la complessità e aumenta la gestibilità – pertanto, su inDomus abbiamo deciso di dedicare a questo tema una pagina ad hoc.

Esempio di configurazione

Quella che segue è, grossomodo (può cambiare da versione a versione), una configurazione “tipo” di Home Assistant:

homeassistant:
  # Name of the location where Home Assistant is running
  name: Home
  # Location required to calculate the time the sun rises and sets
  latitude: 43.9092
  longitude: 12.9164
  # Impacts weather/sunrise data (altitude above sea level in meters)
  elevation: 0
  # metric for Metric, imperial for Imperial
  unit_system: metric
  # Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  time_zone: Europe/Rome
  # Customization file
  customize: !include customize.yaml

# Show links to resources in log and frontend
introduction:

# Enables the frontend
frontend:

# Enables configuration UI
config:

# Uncomment this if you are using SSL/TLS, running in Docker container, etc.
# http:
#   base_url: example.duckdns.org:8123

# Checks for available updates
# Note: This component will send some information about your system to
# the developers to assist with development of Home Assistant.
# For more information, please see:
# https://home-assistant.io/blog/2016/10/25/explaining-the-updater/

updater:
  # Optional, allows Home Assistant developers to focus on popular components.
  # include_used_components: true

# Discover some devices automatically
discovery:

# Allows you to issue voice commands from the frontend in enabled browsers
conversation:

# Enables support for tracking state changes over time
history:

# View all events in a logbook
logbook:

# Enables a map showing the location of tracked devices
map:

# Track the sun
sun:

# Allow diagnosing system problems
system_health:

# Sensors
sensor:
  # Weather prediction
  - platform: yr

# Text to speech
tts:
  - platform: google

# Cloud
cloud:

group: !include groups.yaml
automation: !include automations.yaml
script: !include scripts.yaml

Come si nota, una serie di componenti sono già elencati e pertanto attivi in piattaforma; altri, ovviamente, andranno personalizzati mano mano.

In coda, una buona rappresentazione del concetto di suddivisione in più file del file di configurazione.

Come modificare il/i file di configurazione

Come spiegato in apertura, la modifica di questi file di testo è dipendente dal tipo di sistema e di installazione di Home Assistant in uso.
Nel caso di Raspbian + Home Assistant, è possibile accedere al sistema via SSH (via terminale o via SFTP, tramite un cliente FTP tipo Filezilla) e sovrascrivere/modificare i file; utilizzando HASSIO, invece, la cosa più pratica è quella di installare ed utilizzare l’add-on “File Editor”.

Con sistemi come Windows e macOS la cosa è banale: è sufficiente trovare i file sull’hard-disk e modificarli direttamente con un editor di testo presente sul sistema operativo. Noi consigliamo il sempreverde ATOM.

“configuration.yaml”: come suddividere il file di configurazione di Home Assistant


Home Assistant Official LogoATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica a Home Assistant, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.