Wer Home Assistant schon länger nutzt, dürfte einige male über die Formulierung „Ergänze folgenden Code in deiner configuration.yaml“ gestolpert sein. Und entsprechend groß dürfte die configuration.yaml dann zwischenzeitlich auch geworden sein. Aber das muss nicht sein! Ich zeige dir, wie du deine configuration.yaml super einfach wieder verkleinern kannst, indem du YAML-Code auslagerst.
Bei mir hatte die Datei vor wenigen Tagen noch über 240 Zeilen Codes, der zum absolut größten Teil individuell von mir erstellt war. Entsprechend unübersichtlich und klobig war die Datei. Durch simples Auslagern von YAML-Code in logischen Blöcken in andere Dateien, habe ich keine Funktionalität meines Smart Homes verloren und zeitgleich meine Konfigurations-Datei wieder deutlich übersichtlicher.
Inhaltsverzeichnis
Home Assistant hat grundsätzlich keine Probleme damit, wenn die Konfigurationsdatei riesig ist. Ich persönlich mag dies aber nicht, da man so deutlich schneller den Überblick und sich im Code verlieren kann. Durch das Aufteilen des YAML-Codes in mehrere, logisch getrennte Blöcke bzw. Dateien, wird das Verwalten und Pflegen des Codes deutlich einfacher.
Wer zu faul zum Lesen ist, kann sich das Ganze natürlich auch als Video auf YouTube anschauen 😉
Du magst Home Assistant? Dann abonniere kostenlos meine Beiträge mit Tipps, Tricks und Anleitungen rund um Home Assistant:
Garantiert kein Spam, keine Werbung und immer mit Abmelde-Link, solltest du es dir anders überlegen!
Beispiel für das Auslagern von YAML-Code
In jeder configuration.yaml von HA dürfte sich folgender Code wiederfinden:
automation: !include automations.yaml script: !include scripts.yaml scene: !include scenes.yaml
Dieser Code macht exakt, was ich in diesem Beitrag beschreibe: Es wird etwas definiert automation: beispielsweise und der eigentliche Code hierfür befindet sich in der Datei automations.yaml, der mit der Anweisung !include eingefügt wird. Gleiches gilt in diesem Beispiel für script und scene.
Durch die Anweisung !include kann man also andere YAML-Dateien in die configuration.yaml Datei inkludieren. Alternativ könnte man man den YAML-Code der Datei automations.yaml auch direkt in die configuration.yaml schreiben. Meine automations.yaml ist aktuell aber knapp über 3000 Zeilen lang, was verdeutlichen dürfte, wie unübersichtlich die configuration.yaml werden würde. Also macht es viel mehr Sinn, logisch zusammenhängende Code-Blöcke in eigene Dateien auszulagern und diese in die Konfigurationsdatei zu inkludieren!
Möglichkeiten YAML-Code auszulagern
Das Aufteilen der Konfiguration in mehrere Dateien wird unter anderem auch in der offiziellen Doku von Home Assistant beschrieben: Splitting up the configuration
Neben dem einfach !include-Befehl, mit welchem du zuvor in der configuration.yaml befindlichen Code 1:1 in eine zusätzliche Datei auslagern kannst, gibt es noch die folgenden erweiterten Möglichkeiten:
- !include_dir_list gibt den Inhalt eines Verzeichnisses als Liste zurück, wobei jeder Dateiinhalt ein Eintrag in der Liste ist. Die Reihenfolge der Listeneinträge basiert auf der alphanumerischen Reihenfolge der Dateinamen.
- !include_dir_named gibt den Inhalt eines Verzeichnisses in Form eines Wörterbuchs zurück, das den Dateinamen => Inhalt der Datei abbildet.
- !include_dir_merge_list gibt den Inhalt eines Verzeichnisses als Liste zurück, indem alle Dateien (die eine Liste enthalten sollten) zu einer großen Liste zusammengefasst werden.
- !include_dir_merge_named gibt den Inhalt eines Verzeichnisses als Wörterbuch zurück, indem es jede Datei lädt und in ein großes Wörterbuch zusammenführt.
Zugegeben: Obwohl ich HA mittlerweile seit über 6 Jahren sehr aktiv nutze, habe ich diese erweiterten Möglichkeiten nie so richtig genutzt, da diese voraussetzen würden, dass man deutlich komplexere Code-Aufteilungen und -Gruppierungen vornimmt, als ich dies für nötig halte.
Meine Code-Aufteilungen erfolgen eigentlich alle mittels !include. Lediglich eine !include_dir_named Anweisung existiert in meiner Konfiguration noch. Die habe ich aber vor Jahren mal von anderer Stelle übernommen, weil ich es für clever gehalten habe. Jedoch hat sich HA in der Zwischenzeit deutlich weiterentwickelt (und ich habe natürlich auch dazugelernt), so dass ich diesen Code nicht mehr für sinnvoll halte und bislang lediglich zu faul war ihn auszubauen (und gegen die deutlich simpleren !include-Anweisungen auszutauschen).
Besonderheiten beim Nutzen von !include
Das Nutzen von !include ist grundsätzlich sehr einfach umzusetzen. Aber natürlich gibt es Dinge, auf die du achten musst. Immerhin arbeitest du direkt an der Konfiguration deines Smart Homes und kannst hierbei natürlich Dinge kaputt machen.
Korrekte Code-Einrückungen beachten
Primär solltest du darauf achten, das der Code in der zusätzlichen YAML-Datei korrekt eingerückt ist, also die für YAML elementaren Einrückungen nicht durch Copy&Paste „zerschossen“ wurden. Bei YAML-Code werden über die Einrückungen logischen Abhängigkeiten definiert, so dass eine falsche Einrückung den Code unbrauchbar machen kann.
Ich empfehle für das Bearbeiten von YAML-Code das Nutzen des Add-ons Studio Code Server, da dieser Editor simple Prüfungen deines YAML-Codes „on-the-fly“ durchführt und dich damit auch mögliche Syntax-Probleme deines Codes hinweist. Hier ein Beispiel für eine vom Editor erkannte falsche Einrückung in Zeile 1:
In Zeile 4 wird „bad indentation of a mapping entry“ moniert und der Code-Beginn rot unterstrichen dargestellt. Das eigentliche Problem liegt zwar in den fehlenden Leerzeichen in Zeile 1 vor „garage_light_off“, jedoch hilft einem der Hinweis des Editors die fehlerhafte Stelle überhaupt erst zu entdecken.
Generell empfehle ich ausgelagerten Code in der zusätzlichen Datei „vorne bündig“ einzufügen, also ohne Leerzeichen am Anfang. Für den vorherigen Screenshot würde dies dann folgendes bedeuten:
Tipp: Um gesamte Code-Blöcke schnell einzurücken markiere den gesamten Code und drücke dann bei Windows folgende Tasten:
- Codeblock nach rechts rücken: TAB
- Codeblock nach links rücken: SHIFT + TAB
Code-Änderungen vor Neustart überprüfen
Wenn du deine configuration.yaml aufgeräumt hast, solltest du deine Code-Änderungen auf jeden Fall überprüfen, bevor du einen Neustart des Systems ausführst. Hierfür wechselst du zu den Entwicklerwerkzeugen und wählst dort KONFIGURATION PRÜFEN:
Sofern hier keine Warn- oder Fehlermeldungen angezeigt werden, kannst du deinen HA in der Regel bedenkenlos neu starten und somit deine Code-Änderungen „aktivieren“.
Hier ein Beispiel wie eine Fehler-/Warnmeldung bei dieser Überprüfung aussehen kann, wobei ich die falsche Einrückung aus dem Beispiel von weiter oben hierfür bewusst nicht korrigiert habe (also um die Meldung zu provozieren):
Wenn du eine solche Warnmeldung beim Überprüfen deines YAML-Code angezeigt bekommst, solltest du HA nicht neu starten, sondern zuerst den betreffenden Code beheben und erst nach einer erneuten, erfolgreichen Überprüfung den Neustart durchführen!
Bedeutung von Duplicate-Key Warnungen
Wenn du auch den Studio Code Server für das Bearbeiten der YAML-Dateien nutzt, kann es vorkommen, dass dir eine duplicate key Warnung angezeigt wird. Dies bedeutet in der Regel, dass du eine Angabe vor dem Doppelpunkt doppelt genutzt hast, hier ein Beispiel:
In diesem Beispiel habe ich (bewusst) command_line: definiert, weshalb es zu der Warnmeldung kommt. Technisch verhält sich dieser Code dann so, dass die erste Definition (also !include command_lines.yaml) von der zweiten bzw. letzten „überschrieben“ wird. Als Ergebnis würde als einzig der Code aus der timers.yaml effektiv genutzt werden.
In einem solchen Fall solltest du den „doppelten Schlüssel“ entfernen, also deinen YAML-Code so anpassen, dass es zu keiner solchen Dopplung kommt.
Produktempfehlungen
