Comment Organiser Votre Configuration YAML Home Assistant

Home assistant a énormément travaillé l’interface pour éviter d’utiliser le YAML. Mais celui-ci reste très puissant lorsque l’on sait l’utiliser. Dans cet article nous allons voir les bases ainsi que quelques astuces d’organisation pour votre configuration Home Assistant.

Pourquoi utiliser le YAML avec Home Assistant

Étant présent depuis le début, la configuration YAML n’a aucune limite. Toutes les intégrations ne peuvent pas encore être configurées via l’interface utilisateur d’Home Assistant même si à termes elles le devraient.

Partager vos configurations avec le YAML est plus facile. Si vous rencontrez une erreur, il vous suffit de copier les quelques lignes YAML pour trouver assistance.

Utiliser les l’interfaces et le YAML ensemble est possible, nous allons voir comment à la fin de l’article.

Les bases YAML

Le YAML se représente de la forme `clé: valeur`. Les valeurs peuvent représenter différent type de donnés, je vous les listes ici. Je me suis basé sur le Gist partagé par Franck Nijhof qui fait maintenant parti de l’équipe cœur d’Home Assistant.

Commentaires

Les commentaires sont précédés de `#`

# Commentaire
hello: "world" # commentaire

Les nombres

Nous utiliserons particulièrement les entiers ou décimales.

entier: 1
decimal: 0.1234

Attention ceci n’est pas un entier mais un octal car il est précédé d’un 0:

pas_entier: 014 # Ceci est égal à 12

Une chaîne de caractères

Utilisé ` »` pour indiquer un string. Ceci est optionnel.

string: Hello World
string2: "Hello world"
string3: "2"

La valeur Null

Souvent utilisé pour activer une intégration sans configuration:

hassio: ~
discovery:

Les booléens

Utilisez de préférence `true et `false`

oui: true
non: false
oui2: yes
non2: no

Les listes (tableaux)

Une liste (array) se représente de la façon suivante:

ma_liste:
- 1
- 2
- 3
# ou
ma_liste_2: [1,2,3]
# l'indentation n'a pas d'importance

Dictionnaires

Les dictionnaires sont gérés grâce à l’indentation de la façon suivante:

dictionaire:
  propriete: valeur
  propriete2: valeur

Longues chaîne de caractères

Il peut être difficile de lire une longue chaîne de caractères. Il existe des opérateurs pour pouvoir l’étaler sur plusieurs lignes sans forcément garder les sauts de lignes. Les exemples suivant seront très utiles pour écrire vos templates (ex: messages Telegram). Plus d’information sur les Templates dans un prochain article.

`|` permets de garder les sauts de ligne mais supprime les doubles sauts.

text: |
  Voici un exemple de paragraphe de deux lignes, ceci étant la première.
  Et celle la la deuxième.

`-` après `|` permet de supprimer le dernier saut de ligne.

text: |-
  Voici un exemple de paragraphe de deux lignes, ceci étant la première.
  Et la deuxième ligne sans espaces après celle-ci.
text2: "Autre texte"

Contrairement au `+` qui assurera la présence des sauts de ligne de fin.

text: |+
  Voici un exemple de paragraphe de deux lignes, ceci étant la première.
  Puis la deuxième avec trois sauts de ligne qui suivent.
text2: "Autre texte"

Organiser ma configuration Home Assistant

J’ai suivi la méthode partagé par Franck dans une vidéo du DrZzs. Les règles principales sont simples:

• Pratiquement rien dans mon fichier configuration.yaml
• Chaque fichier représente une seule chose (une seule automatisation, une seule entité,…)

Voici par exemple mon fichier configuration.yaml

# This is the starting point of the configuration
homeassistant:
  whitelist_external_dirs:
    - /tmp
  # All Integrations:
  packages: !include_dir_named integrations
  customize: !include customize.yaml
# Configure a default setup of Home Assistant (frontend, api, etc)
default_config:
scene: !include scenes.yaml
climate: !include climate.yaml
sensor: !include_dir_merge_list sensors

Je dois encore migrer certaines entrées.

Celui de Franck encore plus minimum (Toute la configuration de Franck Nijhof):

---
# Welcome to my Home Assistant configuration!
#
# Don't be scared by the size of my configuration file...
# It is probably the smallest you've ever seen.
#
# My system is very modular and very differently structured
# compared to other configurations you'll find online.
#
# Basically, each file in the repository does 1 (one, uno, eins)
# thing only! Click through it, you'll get it pretty fast.
#
# The configuration.yaml is only used to bootstrap the system.
#
homeassistant:
  # Load packages
  packages: !include_dir_named integrations

Comment utiliser ‘include’

Nous avons vu précédemment les dictionnaires et les listes. Chaque listes et dictionnaires peuvent être déplacés dans un autre fichier.

La directive `include` se construit de la manière suivante:

• `!include`: Inclure un fichier
• `!include_dir_list`: Inclure un dossier (dir) où les fichiers représentent une entrée de liste (list).
• `!include_dir_merge_list`: Inclure un dossier (dir) où les fichiers seront assemblés (merge) pour former une seule liste (list).
• `!include_dir_named`: Inclure un dossier (dir) où les fichiers représentent une entrée du dictionnaire (named). Le nom du fichier sera utilisé commet clé.
• `!include_dir_merge_named`: Inclure un dossier (dir) où les fichiers seront assemblés (merge) pour former un seul dictionnaire (named).

Comment choisir la bonne directive. On commence par détecter si l’on veut intégrer une liste ou un dictionnaire. Ensuite on décide si l’on veut plusieurs entrées par fichier.

Exemple de liste

sensor:
  - platform: time_date
    display_options:
      - "time"
      - "date"
      - "date_time"
      - "time_date"
  - platform: history_stats
    name: battery_bike_charged_today
    entity_id: binary_sensor.bike_battery
    state: 'on'
    type: count
    start: '{{ now().replace(hour=10, minute=0, second=0) }}'
    end: '{{ now() }}'

peut se décomposer de la sorte: Lien vers ma configuration sensor

ou si plusieurs entrées par fichier: Lien vers ma configuration switch

Exemple de dictionnaire

input_boolean:
  sleeping_mode:
    name: Dodo
    icon: mdi:hotel
  vacation_mode:
    name: En vacance
    icon: mdi:beach
  washing_machine_full:
    name: Machine Pleine
    icon: mdi:washing-machine-alert

peut se décomposer de la sorte: Lien vers ma configuration input_boolean

ou si plusieurs entrées par fichier: Lien vers ma configuration yeelight

Astuces

Le YAML permet un mode avancé mais pour des changements rapides l’interface graphique (UI) reste très pratique. Voici quelques astuces pour concilier les deux:

Automatisations

Une astuce est d’ajouter une clé `id` à vos automatisations (Exemple d’automatisation). De cette manière vos automatisations seront modifiables sur l’interface utilisateur.

Le code suivant vous permettra d’avoir les automatisations créés sur l’interface graphique ainsi que celles créés en YAML:

automation: !include ../automations.yaml
automation split: !include_dir_list ../automations

Cette astuce est aussi valable pour les scènes.

Lovelace

Voici comment utiliser vos Dashboard créés sur l’interface graphique ainsi que ceux créés en YAML:

  lovelace:
    # Le mode de défault sera storage
    mode: storage
  
    # Mais nous ajouterons des Dashboards YAML
    dashboards: !include ../lovelace/dashboards.yaml

Voir ma configuration Lovelace

Voila vous savez tout de YAML et des bonnes pratiques pour organiser votre configuration Home Assistant. À vous de jouer, et si vous rencontrez des problèmes n’hésitez pas de partager dans la section commentaires ou sur La Meilleur Communauté Française Pour Home Assistant