“configuration.yaml”: capire il file di configurazione di Home Assistant5 minuti di lettura

Banner PROMO -25€ HOMEY – Newsletter inDomus  
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 modifica all'impianto elettrico dev'essere effettuata da personale qualificato
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (la presente guida ha puro scopo didattico)
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere la garanzia.
Revisione guida: 3.1

Abstract

Home Assistant basa per intero la propria configurazione – quindi tutte le entità in essa definite – su un file capofila chiamato “configuration.yaml” definito, per l’appunto, sul formato di serializzazione dati YAML. Tale file solitamente è posizionato nella directory root dell’installazione di Home Assistant; ad esempio, nell’installazione Raspbian solitamente esso si trova nel path:

/home/homeassistant/.homeassistant/

questo path, ovviamente, cambia da sistema a sistema a sistema.

In sostanza si tratta di un file di testo contenente una serie di “blocchi” (senza uno specifico ordine), ciascuno dei quali rappresenta uno specifico componente di Home Assistant, componenti che, quando configurati, definiscono una o più integrazioni.

Se per esempio volessimo integrare nella domotica basata su Home Assitant 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’intentazione 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 tutti i componenti, per essere implementati, prevedono delle piattaforme soggiacenti, ma possono essere usati e configurati autonomamente.

L’esempio a seguire mostra un 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 “threat:” senza alcun valore sulla stessa linea. Questo perché di fatto apre alle linee successive un annidamento utile a definire i suoi parametri:

input_select:
  threat:
    name: Threat level
# 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 (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’aumentare della configurazione aumenta anche la dimensione 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 di default

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

Con sistemi come Windows e macOS la cosa è banale: è sufficiente trovare i file sul filesystem 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.

🔻 Clicca QUI per commentare l'articolo. 🔻