Ich werde immer wieder gefragt, wie ich meine YAML-Dateien in Home Assistant organisiere. Die kurze Antwort: mit Packages. Die etwas längere Antwort erkläre ich dir hier Schritt für Schritt, weil das Thema ein bisschen mehr verdient als einen kurzen Kommentar.
Warum die configuration.yaml schnell zum Problem wird
Wenn du Home Assistant frisch aufsetzt, landet erstmal alles in der configuration.yaml. Sensoren, Automationen, Templates, Integrationen. Das funktioniert eine Weile ganz gut, bis die Datei irgendwann so lang wird, dass du weißt: da steckt irgendwo ein Tippfehler drin, aber ich finde ihn nicht.
Das ist kein seltenes Problem. Ein einzelnes falsch gesetztes Zeichen in der configuration.yaml reicht aus, damit Home Assistant beim nächsten Neustart gar nicht mehr hochkommt. Und je länger die Datei, desto größer die Chance, dass genau das passiert. Deswegen macht es Sinn, die Konfiguration früh aufzuteilen, bevor das Chaos anfängt.
Der erste Schritt: Dateien auslagern
Die einfachste Möglichkeit ist, einzelne Bereiche in separate YAML-Dateien auszulagern. In meiner configuration.yaml sieht das zum Beispiel so aus:
automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yamlDie ausgelagerten Dateien liegen dann im selben Verzeichnis wie die configuration.yaml. Das ist schon eine deutliche Verbesserung, hat aber einen Haken: du organisierst immer noch nach Domain, also nach Typ. Alle Automationen in einer Datei, alle Skripte in einer Datei, alle Sensoren in einer Datei. Wenn du etwas an deiner Waschmaschinen-Automatisierung ändern willst, springst du trotzdem zwischen drei verschiedenen Dateien hin und her.
Packages: Alles zu einem Thema an einem Ort
Genau hier kommen Packages ins Spiel. Statt nach Domain zu organisieren, organisiere ich nach Thema. Alles, was mit meiner Garmin-Integration zu tun hat, liegt in einer einzigen Datei. Alles zur Heizung in einer anderen. Alles zum Whirlpool in einer dritten.
Dafür brauchst du in der configuration.yaml nur einen einzigen Eintrag:
homeassistant:
packages: !include_dir_named packagesDas weist Home Assistant an, alle YAML-Dateien aus dem Ordner packages automatisch in die Konfiguration einzubeziehen. Du legst den Ordner packages neben deine configuration.yaml, und dann kannst du darin beliebig viele Dateien anlegen.
Eine solche Package-Datei kann mehrere Domains gleichzeitig enthalten:
1sensor:
2 - platform: template
3 sensors:
4 waschmaschine_status:
5 friendly_name: "Waschmaschine Status"
6 value_template: "{{ states('input_select.waschmaschine_status') }}"
7
8automation:
9 - alias: "Waschmaschine fertig"
10 trigger:
11 - platform: state
12 entity_id: sensor.waschmaschine_status
13 to: "fertig"
14 action:
15 - service: notify.mobile_app
16 data:
17 message: "Die Waschmaschine ist fertig!"
18
19input_select:
20 waschmaschine_status:
21 name: Waschmaschine Status
22 options:
23 - idle
24 - laueft
25 - fertigAlles, was zur Waschmaschine gehört, steckt in packages/waschmaschine.yaml. Kein Springen zwischen Dateien mehr.
Neue Dateien hinzufügen ohne Nacharbeit
Das ist für mich der vielleicht größte Vorteil an dieser Methode. Wenn ich eine neue Datei im packages-Ordner anlege, etwa google.yaml für alle Google-bezogenen Konfigurationen, muss ich das nirgendwo eintragen. Home Assistant findet die Datei beim nächsten Neustart automatisch und bezieht sie ein.
Beim klassischen !include-Ansatz würdest du die neue Datei zuerst in der configuration.yaml referenzieren müssen. Vergisst du das, läuft die Datei einfach nicht mit. Und dann sitzt du da und fragst dich, warum deine neue Konfiguration keine Wirkung zeigt, obwohl du alles richtig gemacht hast. Das kann dir mit Packages nicht passieren.
Unterverzeichnisse wenn es mehr wird
Wenn der packages-Ordner irgendwann selbst unübersichtlich wird, kannst du auch mit Unterverzeichnissen arbeiten. Dann gruppierst du zum Beispiel alle Energie-bezogenen Dateien in packages/energie/ und alles zur Beleuchtung in packages/licht/. Für diesen Fall nutzt du in der configuration.yaml:
homeassistant:
packages: !include_dir_named packagesHome Assistant durchsucht dabei auch Unterordner, solange du !include_dir_named verwendest. Das Verzeichnis kann also beliebig tief werden, ohne dass du die Konfiguration anpassen musst.
YAML-Validator und Config Explorer
Neben der Struktur selbst gibt es auf alles-automatisch.de noch ein paar hilfreiche Tools. Den YAML-Validator kannst du nutzen, um deinen Code auf Fehler zu prüfen, bevor du ihn in Home Assistant einfügst. Du fügst deinen YAML-Code ein und siehst sofort, ob da ein Syntaxfehler drinsteckt.
Dazu gibt es jetzt auch den Config Explorer, der meine Home Assistant Struktur noch einmal interaktiv darstellt. Du kannst da durchklicken, siehst wie die configuration.yaml aufgebaut ist, wie die Packages eingebunden werden und welche Dateien in welchem Verzeichnis liegen. Das ist vor allem dann hilfreich, wenn du gerade erst anfängst und dir das Ganze noch etwas abstrakt vorkommt.
Wenn du Fragen zur Struktur hast oder dir noch nicht sicher bist, wie du das bei dir umsetzen solltest, schreib mir das gerne in die Kommentare. Ich bin wahnsinnig gespannt, wie ihr das bei euch gelöst habt.
