"Configuration.yaml": understand the configuration file of Home Assistant

5 minutes of reading
Guide purposes:
  • Understand the basic concepts related to the configuration file of Home Assistant
  • Difficulty level: bass
Concepts dealt with:
  • software configuration
Software components used:
Prerequisites:
GUIDE more indicated for:

All environments

Notes and disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere progettata ed effettuata da personale qualificato;
  • any changes implemented in probefore is a propersonal responsibility as well as a profirst risk and danger (the contents of the present page are purely educational);
  • any changes implemented in proprior to a device it voids the guarantee, quality approvals and certifications.
Driving review: 3.2

Abstract

Home Assistant based entirely on profirst configuration - then all entity defined in it - on a file leader called "configuration.yaml"Defined, for theappon the data serialization format YAML. This file is usually located in the root directory of the installation of Home Assistant; for example, in the Raspbian installation it is usually found in the path:

/home/homeassistant/.homeassistant/

while on HASSIOit is usually found at the path:

/ Config /

this path obviously changes from installation to installation.

Basically it is of a text file containing a series of "blocks" (without a specific order), each of which rappresents a specific one Component / platform di Home Assistant, components that, when configured, define one or more integrations.

If for example we wanted to integrate into home automation based on Home Assistant a light, say, of the series Magic, we would use the platform dedicated to it "Flux Led / Magic Light", Which is the" daughter "of the component"Light"

The "block" related to this integration would correspond to:

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

where the voice "light:"Defines the beginning of the component block"Light"And the sub-block"platform:”Defines the true entity e proere, prolearned by specifying the platform, or "flux_led"

  • un components (component) provides the core logic for specific features (eg "and "light", too");
  • a platform (platform) creates the connection to a specific software and / or hardware (for example "flux_led“).

Pay attention to the fact that the intentazione has a role determinant in defining the relationships defined in YAML - most of the configuration errors arise, in fact, from an incorrect indentation. Indented elements are nested within elements of a "higher" level. In the example above, “platform: flux_led" it's a proownership (nested) of the component "notify"
Each degree of indentation is defined by two spaces, not three, not one: the two.

By convention, indentation is defined through two spaces for each nesting level.
The lines preceded by the "#"Are ignored by the system.

Before giving any configuration to food a Home Assistant, it is always a good idea to validate the profirst YAML file through the site YAMLint.


Not all components require underlying platforms to be implemented, but they can be used and configured independently.

The example to follow shows a component configuration "Input Select" that progives a list of choice items (as a form of user input at the GUI level). As noted, no platform is indicated.

More proproperty (for example "name") Are specified using mappature. Notice how the second line is only "Threat:"Without any value on the same line. This is because in fact it opens up successive nesting lines to define its parameters:

input_select:
  threat:
    name: Threat level
# Le opzioni di scelta vengono definite tramite la seguente mappatura
    options:
    - 0
    - 1
    - 2
    - 3
    initial: 0

The following example shows instead the nesting of a collection of mappature in a mappatura itself: in this case two are defined "Sensor"(Sensors) that use the platform"MQTT Sensor"Which have different" state topic "values ​​(one of the protypical properties of an MQTT sensor):

sensor:
  - platform: mqtt
    state_topic: sensor/topic
  - platform: mqtt
    state_topic: sensor2/topic
USE ENVIRONMENTAL VARIABLES

In the configuration file configuration.yaml (as in the other sidecar files connected to it) you can use environment variables. To use one it is sufficient to indicate "! env_var”Followed by the name of the variable itself.
For example:

http:
api_password: !env_var PASSWORD

If the variable is not defined, it is possible to indicate in the configuration the value to be used alternatively:

http:
api_password: !env_var PASSWORD password_di_default
INCLUDE SIDECAR FILE (SUBDIVISION)

Given that as the configuration increases also increases the file size, to improve its readability it is possible to indicate inside specific references to external files using the particle "!includes”Followed by the name of the file to include:

lights: !include lights.yaml

In essence it is possible to maintain "configuration.yaml"As" backbone "of the configuration and use multiple files (.yaml) as" ribs "in which to configure the entities deriving from the various components declared in the main file.

File subdivision "configuration.yaml"In several files sidecar is a technique that reduces complexity and increases manageability - therefore, on inDomus we have decided to dedicate to this theme an ad hoc page.

Configuration example

The following is, roughly (it may change from version to version), a "typical" configuration"Of 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

As can be seen, a series of components are already listed and therefore active on the platform; others, of course, will be customized by hand.

In line, a good rappresentment of the concept of subdivision into multiple files of the configuration file.

How to modify the configuration file (s)

As explained in the opening, the modification of these text files is dependent on the type of system and installation of Home Assistant in use.
In the case of Raspbian + Home Assistant, it is possible to access the system via SSH (via terminal or via SFTP, via a typical FTP client) Filezilla) and overwrite / modify files; using HASSIOinstead, the most practical thing is that to install and use theadd-on "Configurator".

With systems like Windows e macOS the thing is trivial: it is sufficient to find the files on the filesystem and modify them directly with a text editor present on the operating system. We recommend the evergreen ATOM.

"Configuration.yaml": how to split the configuration file of Home Assistant


Home Assistant Official LogoATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Home Assistant, for any doubt, question, information on the specific merit of these components.


Please comment below