Après plusieurs mois à empiler capteurs, automations et intégrations, ma config Home Assistant est devenue un seul gros fichier illisible. La solution n’a pas été d’ajouter de l’UI, mais de redécouper le YAML par domaine fonctionnel. Précision utile avant de commencer : cet article ne s’adresse pas à tout le monde. Depuis la mise à jour 2026.7, une bonne partie des automatisations du quotidien se construit très bien sans toucher au YAML (voir plus bas). Ce qui suit concerne surtout les setups qui ont grossi au point de devenir difficiles à suivre, pas une étape obligatoire pour démarrer avec Home Assistant.
Le problème : un configuration.yaml qui devient un dépotoir
Home Assistant permet de tout gérer depuis l’interface : automations, scripts, helpers. Pratique pour démarrer, mais ça ne tient pas à l’échelle. Dès qu’on dépasse une vingtaine d’automations et autant de capteurs calculés, l’UI devient un mur de recherche sans structure, impossible à versionner, et illisible pour qui veut comprendre pourquoi telle règle existe.
Mon setup gère aujourd’hui du chauffage multi-pièces, des volets automatiques, une piscine connectée, du suivi énergie détaillé, de la détection de cycle électroménager et des notifications Telegram croisées entre tous ces domaines. Sans organisation claire, la moindre modification devenait un jeu de « où est-ce que j’ai mis ça déjà ».
Le contexte : développeur, donc réflexe de code organisé
Je code au quotidien, donc l’absence de structure me gênait plus qu’elle ne gênerait quelqu’un venu de l’UI pure. Mon objectif : appliquer à ma config domotique les mêmes principes qu’à un projet logiciel : séparation des responsabilités, un fichier = un périmètre clair, pas de logique dupliquée entre deux endroits.
Contrainte de départ : tout faire en YAML plutôt qu’en UI, pour pouvoir versionner, diffé, et éventuellement automatiser des vérifications dessus. Contrainte de fond : le système tourne en continu (chauffage, sécurité), donc toute réorganisation doit se faire sans downtime ni régression silencieuse.
L’implémentation : un fichier par domaine, pas par type d’objet
Le choix structurant a été de découper par domaine fonctionnel (chauffage, volets, énergie, piscine…) plutôt que par type d’objet (tous les sensors ensemble, tous les scripts ensemble). Chaque package est autonome : il contient ses helpers, ses capteurs calculés et parfois ses automations internes.
/config/
├── configuration.yaml # Config principale, includes
├── scripts.yaml # Tous les scripts, centralisés
├── packages/ # Un fichier par domaine fonctionnel
│ ├── volets.yaml # Volets, groupes, mode bébé
│ ├── energy.yaml # Suivi conso, 26 appareils
│ ├── piscine.yaml # Helpers piscine
│ └── ...
└── automations/ # Automations, groupées par domaine
├── chauffage_planning.yaml
├── piscine.yaml
└── ...
Ça repose sur deux directives d’inclusion dans configuration.yaml :
homeassistant:
packages: !include_dir_named packages/
automation: !include_dir_merge_list automations/
!include_dir_named charge chaque fichier du dossier packages/ comme un package nommé (le nom du fichier devient la clé). !include_dir_merge_list fusionne tous les fichiers d’automations en une seule liste. Résultat : ajouter un domaine, c’est ajouter un fichier, jamais toucher aux fichiers existants.
Deux conventions de nommage m’ont fait gagner du temps par la suite :
# Pattern répété partout : {domaine}_{piece_ou_appareil}
binary_sensor.machine_a_laver_en_fonctionnement
sensor.duree_fonctionnement_machine_a_laver_24h
sensor.consommation_machine_a_laver
# Pattern volets
cover.salon_baie_droite_low_speed
Noms d’appareils en français (plus naturel pour moi au quotidien), scripts et automations en anglais quand ça aide à la lisibilité pour un assistant IA qui m’aide à maintenir cette config. Les scripts, eux, restent tous centralisés dans un seul scripts.yaml à la racine plutôt que dispersés : ce fichier a grossi, mais je préfère un seul point de recherche à dix fichiers à parcourir.
Choisis ta convention de nommage des entités avant d’avoir vingt fichiers à corriger, pas après. Un pattern cohérent dès le départ (domaine_piece, domaine_appareil) fait gagner un temps fou dès que tu commences à écrire des automations qui croisent plusieurs domaines.
Le piège rencontré : la dérive des dossiers fantômes
Le vrai problème n’est pas venu de la structure elle-même, mais de sa dérive dans le temps. J’avais initialement deux dossiers séparés, configuration/ et helpers/, censés accueillir respectivement de la config générale et les helpers (input_boolean, input_number, etc.). Sur la durée, les deux ont fini vidés de leur substance : tout ce qu’ils contenaient a fini par migrer directement dans configuration.yaml, sans que je supprime les dossiers pour autant. Résultat : deux dossiers vides qui traînaient, référencés nulle part, sources de confusion à chaque audit de la config (« est-ce que j’utilise encore ça ? »).
La leçon : une structure de dossiers n’est un atout que si elle est revue périodiquement. Un dossier qui ne sert plus à rien doit être supprimé, pas laissé « au cas où ». J’ai fini par faire un audit complet, fichier par fichier, pour resynchroniser la doc avec la réalité du filesystem, et supprimer ce qui ne correspondait plus à rien.
Deuxième piège, plus insidieux : à chaque changement un peu lourd, je me retrouvais avec des fichiers .bak qui s’accumulaient à côté des originaux, faute de vrai suivi de version. Ça fonctionne comme filet de sécurité manuel, mais ça pollue le dossier et ne remplace pas un historique propre. Si c’était à refaire, je mettrais /config sous Git dès le premier jour plutôt que d’improviser des sauvegardes ponctuelles.
Depuis la 2026.7 : quand se passer du YAML
La mise à jour 2026.7 de Home Assistant a fait graduer les triggers et conditions « orientés intention » (sortis de la section Labs), qui deviennent le comportement par défaut de l’éditeur d’automatisation. Concrètement, tu choisis « la température passe sous un seuil » ou « mouvement détecté dans le salon » plutôt que de partir d’un entity_id et d’un état technique. Les automatisations peuvent aussi cibler une zone entière (une pièce) plutôt qu’un capteur précis, ce qui règle une bonne partie du travail de maintenance que je décris plus haut, sans écrire une ligne de YAML.
Pour une automatisation simple (une lumière, un volet, une alerte), l’éditeur UI suffit largement aujourd’hui et c’est clairement le point de départ à privilégier. Là où le YAML garde son intérêt, c’est pour les logiques qui croisent plusieurs conditions, plusieurs domaines et un vrai besoin de versionner (comme la structure en packages de cet article, ou les automatisations en cascade détaillées dans l’article chauffage de cette série). Les deux approches coexistent très bien : rien n’empêche de garder l’UI pour l’essentiel et de ne descendre en YAML que pour les cas qui le justifient vraiment.
Bilan : ce que je changerais
Le découpage en packages a clairement payé : ajouter un nouveau domaine (la piscine, récemment) tient dans un seul fichier neuf, sans toucher au reste. C’est le principal bénéfice recherché, et il tient dans la durée.
Ce que je changerais avec le recul : mettre en place Git dès le début plutôt que des .bak manuels, et documenter les conventions de nommage avant d’avoir vingt fichiers à corriger a posteriori plutôt qu’après. La structure par domaine fonctionnel plutôt que par type d’objet reste, avec le recul, le choix le plus important de tout ce setup : c’est lui qui rend la config lisible sans avoir à tout garder en tête.
Les articles suivants de cette série creusent chacun un de ces domaines en détail : chauffage, volets, piscine, sécurité, dashboards.
FAQ
Faut-il tout migrer en YAML pour utiliser des packages Home Assistant ?
Non, les packages coexistent avec des helpers ou automations créés en UI. Mais pour un gros setup, le YAML facilite le versionnement et la relecture.
Combien de fichiers packages faut-il avant que ça devienne utile ?
Dès qu’on dépasse une dizaine d’automations et de capteurs calculés, la recherche dans l’UI devient plus lente qu’un fichier bien nommé.
Quelle est la différence entre !include_dir_named et !include_dir_merge_list ?
Le premier charge chaque fichier comme une clé nommée (packages), le second fusionne tous les fichiers d’un dossier en une seule liste (automations).
Faut-il mettre sa config Home Assistant sous Git ?
Fortement recommandé dès le début : ça remplace les fichiers .bak improvisés et donne un vrai historique des changements.
Stack utilisée
- Home Assistant OS (VM virtualisée)
- YAML natif (
packages/,automations/,!include_dir_named,!include_dir_merge_list) - Zigbee2MQTT (Docker)
- Intégrations HACS diverses (custom_components)
