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

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: Home Assistant un editor di testo (opzionale) Prerequisiti: Home Assistant installato e funzionante
GUIDA INDICATA A UTENTI CON ISTALLAZIONE:
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; gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione; 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; se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 4.1

• Abstract
  • Utilizzare le variabili di ambiente
  • Includere file sidecar (suddivisione)
  • Package
• Esempio di configurazione
• Come modificare il/i file di configurazione

Abstract

Il popolare HUB personale software Home Assistant dispone una propria configurazione operativa nonché diverse configurazioni d’integrazione relative più disparati componenti domotici e servizi. Principalmente, per agire su tali configurazioni si agisce su un file capofila chiamato “configuration.yaml“, un semplice file di testo scritto in notazione YAML.

Tale file di configurazione solitamente è posizionato in una specifica cartella preposta alla scopo; ad esempio:

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, configurano una o più piattaforme di integrazione (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 (per esempio alle automazioni, script, scene), ogni modifica prevede il riavvio dell’HUB al fine di renderle operative; quando l’HUB viene avviato legge il file configuration.yaml, applica le impostazioni relative alla configurazione e, in relazione alle integrazioni specificate, crea (se non ci sono problemi) le entità corrispondenti.

Per portare un esempio, quando volessimo integrare nella domotica basata su Home Assistant un punto luce, diciamo, basato su un banale Shelly 1L, utilizzeremmo la piattaforma ad essa dedicata “MQTT Light“, la quale è “figlia” del componente “Light“.

Il “blocco” relativo a questa integrazione corrisponderebbe a:

# Esempio di entry su configuration.yaml
mqtt:
  light:
  - name: "Luce Sala"
    state_topic: "shellies/NOME_SHELLY/relay/0"
    command_topic: "shellies/NOME_SHELLY/relay/0/command"
    availability_topic: "shellies/NOME_SHELLY/online"
    qos: 1
    value_template: "{% if value == 'on' %} on {% else %} off {% endif %}" 
    payload_on: "on"
    payload_off: "off"
    payload_available: "true"
    payload_not_available: "false"
    optimistic: false
    retain: false

dove la voce “light:” definisce l’inizio del blocco relativo al componente “Light” e il sottoblocco “platform:” definisce la piattaforma d’integrazione usata, ovvero “mqtt“.

Tale configurazione genera un’entità chiamata light.luce_sala.

• 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 “mqtt“).

(Leggi di più: Comprendere la logica componente-piattaforma-entità di Home Assistant)

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: nanoleaf” è una proprietà (annidata) del componente “light“.
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 e vengono usate come commenti alla configurazione.

Non tutte le integrazioni, per essere implementate, prevedono delle piattaforme soggiacenti, ma possono essere usate e configurate in autonomia direttamente tramite il componente padre.

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

Tale configurazione genera un’entità chiamata input_select.alto.tapparelle.

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 entrambi la piattaforma “MQTT Sensor” i quali abbiano differenti valori di “state topic” (una delle proprietà tipiche di un sensore MQTT):

mqtt:
  sensor:
  - name: "sensor 1"
    state_topic: sensor/topic
  - name: "sensor 2"
    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

Nell’esempio si dislocano nel file lights.yaml tutte le voci del componente light: che, altrimenti, avrebbero dovute essere scritte a seguire.

In sostanza è possibile mantenere “configuration.yaml” quale “spina dorsale” della configurazione e utilizzare più file (YAML) quali “costole” presso le quali configurare specifici aspetti.

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

PACKAGE

Oltre alla suddivisione in più file “per componente”, Home Assistant prevede anche una modalità detta “a package”, ovvero dei file che raggruppano configurazioni dedicate a specifiche funzionalità composte da più tipologie di componenti e servizi.

Come per i file sidecar, la tecnica dei package è comoda sotto vari aspetti, pertanto su inDomus abbiamo deciso di dedicare a questo tema un’ulteriore 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:

# 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 Raspberry Pi OS o di Linux Debian, è possibile accedere al sistema via SSH (via terminale o via SFTP, tramite un cliente FTP tipo Filezilla) e sovrascrivere/modificare i file; utilizzando Home Assistant OS, 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 (file “sidecar”)