YAML-Beispiele lesen und auf das eigene Zuhause übertragen

Ein YAML-Beispiel wirkt oft erstaunlich übersichtlich. Ein paar Zeilen nennen einen Auslöser, eine Lampe und eine Aktion. Nach dem Einfügen meldet der Editor trotzdem einen Fehler, oder die Automation lässt sich speichern und tut anschließend etwas anderes als erwartet. Beide Situationen sind verständlich, wenn man zwischen dem Dateiformat und der Bedeutung der Konfiguration unterscheidet. YAML beschreibt zunächst eine Datenstruktur. Home Assistant erwartet an einer bestimmten Stelle eine bestimmte Struktur mit passenden Feldern und gültigen Kennungen.

Wer fremde Beispiele übernimmt, arbeitet daher auf mehreren Ebenen. Ist der Text syntaktisch gültig? Passt er an die Stelle, an der er eingefügt wird? Sind die genannten Geräte und Helfer vorhanden? Entspricht der Ablauf der eigenen Absicht? Erst die Kombination dieser Prüfungen macht aus einem Ausschnitt eine brauchbare Konfiguration. Dieser Artikel verwendet ausschließlich erfundene Kennungen und kleine Lernbeispiele, die keine private Installation voraussetzen.

Die äußere Form und die innere Bedeutung

In YAML werden Zuordnungen häufig als Schlüssel und Wert geschrieben. Listen kennzeichnen mehrere Einträge. Einrückungen zeigen, welche Teile zusammengehören. Die Home-Assistant-Einführung in YAML erläutert diese Grundformen im Kontext der Konfiguration. Beim Lesen hilft es, zunächst nur die Struktur zu betrachten und die konkreten Gerätenamen kurz auszublenden.

Ein Feld namens target kann beispielsweise eine untergeordnete Zuordnung enthalten. Darin steht die Kennung eines Ziels. Eine Liste von Aktionen enthält wiederum mehrere einzelne Zuordnungen. Wenn eine Zeile auf die falsche Ebene rutscht, kann sich die Bedeutung verändern oder die Struktur ungültig werden. Das Problem ist dann nicht die gewählte Lampe, sondern die Beziehung zwischen den Zeilen.

Davon getrennt ist die fachliche Prüfung. Ein syntaktisch korrektes Feld kann an der gewählten Stelle unbekannt sein. Ein korrekt aufgebautes Ziel kann auf eine nicht vorhandene Entität zeigen. Eine gültige Aktion kann für das gewählte Gerät ungeeignet sein. Deshalb ist eine erfolgreiche allgemeine YAML-Prüfung nur der erste Schritt. Sie beweist weder, dass Home Assistant die Konfiguration akzeptiert, noch dass das gewünschte Alltagsverhalten entsteht.

Zuerst klären, wohin ein Beispiel gehört

Nicht jeder Ausschnitt ist eine vollständige Automation. Ein Beispiel kann nur den Aktionsblock, einen einzelnen Listeneintrag oder eine Konfiguration für eine bestimmte Datei zeigen. Wer diesen Umfang nicht erkennt, fügt leicht eine zusätzliche äußere Ebene ein oder lässt eine erforderliche Ebene weg. Ein Text, der in einem Aktionseditor passt, muss deshalb nicht unverändert an anderer Stelle funktionieren.

Vor dem Kopieren wird die Beschreibung des Beispiels gelesen. Steht dort, dass nur eine Aktion gezeigt wird? Gehört der Inhalt in eine Liste? Wird eine ganze Datei oder ein Abschnitt ersetzt? Falls der Zusammenhang nicht klar ist, wird der Ausschnitt zunächst als Lernmaterial behandelt. Die passende Struktur kann dann im eigenen Editor erzeugt und mit dem Beispiel verglichen werden, statt die gesamte vorhandene Konfiguration zu überschreiben.

Ein nützlicher Vergleich beginnt mit einer selbst angelegten, sehr einfachen Automation. Ihre Darstellung zeigt, wie die aktuelle Installation diesen Typ von Konfiguration organisiert. Danach werden einzelne Felder ergänzt. So bleibt der äußere Rahmen bekannt. Unterschiede zu einem älteren Internetbeispiel lassen sich gezielt untersuchen, ohne jede abweichende Schreibweise sofort als Fehler oder als zwingend notwendige Modernisierung zu behandeln.

Einen Aktionsausschnitt wirklich lesen

Das folgende Beispiel beschreibt eine einzelne Aktion für eine erfundene Lampe. Es ist kein vollständiger Automationsentwurf. Es gibt weder einen Auslöser noch Bedingungen an. Als Lernaufgabe lässt sich daran jedoch gut erkennen, welche Information auf welcher Ebene steht.

action: light.turn_on
target:
  entity_id: light.beispiel_leselampe
data:
  brightness_pct: 45

Die Aktion benennt die gewünschte Funktion. Das Ziel beschreibt, welche Entität betroffen ist. Die zusätzlichen Daten geben eine Einstellung für diesen Aufruf an. Vor einer tatsächlichen Nutzung muss die konkrete Lampe die betreffende Funktion unterstützen. Ein schöner Name im Beispiel ersetzt diese Prüfung nicht. Wenn zunächst nur das Einschalten getestet wird, kann die zusätzliche Helligkeitsangabe vorübergehend entfallen.

Wird derselbe Aufruf Bestandteil einer Aktionsliste, kommt die entsprechende Listenstruktur hinzu. Diese kleine Änderung ist wichtig, weil sie zeigt, dass der Inhalt nicht unabhängig von seiner Umgebung gelesen werden kann. Die Form des einzelnen Aufrufs bleibt erkennbar, sein Platz innerhalb des größeren Dokuments verändert sich jedoch.

actions:
  - action: light.turn_on
    target:
      entity_id: light.beispiel_leselampe
    data:
      brightness_pct: 45

Der zweite Ausschnitt ist weiterhin nur ein Teil einer Automation. Er zeigt ausdrücklich die äußere Aktionsliste. Wer die beiden Beispiele vergleicht, sollte nicht nach einer vermeintlich allgemein richtigen Version suchen. Beide können im passenden Zusammenhang sinnvoll sein. Die entscheidende Information ist, welcher Rahmen an der konkreten Einfügestelle bereits existiert.

Kennungen als Verknüpfungen behandeln

Eine Entitätskennung ist keine frei gewählte Beschreibung, die beim Einfügen automatisch ein Gerät erzeugt. Sie verweist auf eine vorhandene Funktion. Deshalb wird für jede Kennung im Beispiel geprüft, ob sie in der eigenen Installation existiert und ob sie tatsächlich zum gewünschten Gerät gehört. Eine ähnlich aussehende Kennung kann eine Diagnosefunktion oder ein anderes Gerät bezeichnen.

Bei mehreren Ersetzungen hilft eine kleine Zuordnungsliste. Links stehen die Beispielkennungen, rechts die eigenen Ziele. Danach wird der gesamte Ausschnitt nach verbliebenen Beispielen durchsucht. Besonders leicht werden Kennungen in Bedingungen, Variablen oder Vorlagen übersehen. Eine Aktion kann bereits die richtige Lampe treffen, während der Auslöser noch auf den erfundenen Sensor aus der Vorlage wartet.

Diese Liste dient der lokalen Bearbeitung und gehört nicht ungeprüft in einen öffentlichen Beitrag. Für geteilte Beispiele werden die Kennungen wieder durch erkennbare Platzhalter ersetzt. Auch Namen können Aufschluss über Räume und Gewohnheiten geben. Die technische Erklärung verliert nichts, wenn sie mit einer ausdrücklich erfundenen Leselampe arbeitet und die tatsächliche Zuordnung in der privaten Installation bleibt.

Zeichenketten, Zahlen und auffällige Anführungszeichen

Ein Wert kann eine Zahl, ein Wahrheitswert oder eine Zeichenkette sein. Welche Form erforderlich ist, bestimmt das betreffende Feld. Bei Zuständen, die als Text verglichen werden, sind ausdrücklich gesetzte Anführungszeichen oft eine hilfreiche Lesestütze. Sie machen sichtbar, dass beispielsweise ein Wort als Zustand und nicht als freie Erklärung gemeint ist.

Beim Kopieren aus formatierten Webseiten oder Textprogrammen können typografische Zeichen in einen Codeblock gelangen. Geschwungene Anführungszeichen sehen im Fließtext angenehm aus, sind aber nicht automatisch die richtigen Begrenzungszeichen für einen Konfigurationswert. Auch unsichtbare Einrückungsprobleme können entstehen. Deshalb wird der Ausschnitt in einem geeigneten Editor betrachtet und nicht allein nach seiner optischen Ähnlichkeit mit dem Original beurteilt.

Die YAML-Spezifikation beschreibt das Format im Detail. Für die alltägliche Anpassung muss man sie nicht vollständig auswendig kennen. Es genügt zunächst, bei Unsicherheit die konkrete Struktur und den erwarteten Datentyp zu prüfen. Eine Zahl sollte nicht nur deshalb als Text behandelt werden, weil sie in einem anderen Beispiel zwischen Anführungszeichen stand; umgekehrt darf ein Textzustand nicht versehentlich als andere Wertart interpretiert werden.

Vorlagen sind eine zusätzliche Sprachebene

Manche Werte werden durch Vorlagen berechnet. Dann enthält das YAML nicht nur feste Daten, sondern zusätzlich einen Ausdruck, dessen Ergebnis zur Laufzeit verwendet wird. Diese zweite Ebene verdient eine getrennte Prüfung. Ein Dokument kann korrekt aufgebaut sein, während die Vorlage einen fehlenden Wert nicht behandelt oder eine Zahl unerwartet umwandelt.

Bei einem fremden Beispiel wird deshalb zuerst gefragt, welche Eingaben die Vorlage benötigt. Woher kommen diese Werte? Können sie unbekannt oder nicht verfügbar sein? In welchem Zusammenhang wird der Ausdruck ausgewertet? Variablen, die in einem bestimmten ausgelösten Ablauf vorhanden sind, müssen nicht bei einem manuell gestarteten Test in derselben Form existieren. Eine Probe ohne diesen Zusammenhang kann ein irreführendes Ergebnis liefern.

Zum Lernen ist es häufig sinnvoll, zunächst mit einem festen Wert zu arbeiten. Wenn die Aktion mit diesem Wert funktioniert, wird erst danach die Vorlage ergänzt. So lässt sich ein Problem der Berechnung von einem Problem der Geräteaktion unterscheiden. Der feste Wert ist dabei eine vorübergehende Testhilfe, keine versteckte Ersatzlösung für eine unbekannte Eingabe.

Änderungen klein halten und lesbar vergleichen

Eine lange Konfiguration wird nicht dadurch verständlicher, dass viele Anpassungen gleichzeitig vorgenommen werden. Für den ersten Versuch werden nur Kennungen und unbedingt erforderliche Felder ersetzt. Danach folgt eine Prüfung. Weitere Wünsche wie eine zusätzliche Bedingung oder eine andere Wartezeit kommen in getrennten Schritten hinzu. So bleibt nachvollziehbar, welche Änderung welches Verhalten beeinflusst hat.

Ein Textvergleich vor und nach einer Bearbeitung ist dabei sehr hilfreich. Er zeigt, ob versehentlich eine benachbarte Zeile entfernt oder eine ganze Gruppe anders eingerückt wurde. Besonders bei kopierten Listen sollte geprüft werden, ob ein neuer Eintrag wirklich ergänzt wurde oder einen vorhandenen Eintrag ersetzt hat. Kleine Unterschiede können eine größere Bedeutung haben als ein auffälliger neuer Gerätename.

Auch die Beschreibung der Automation wird angepasst. Ein alter Kommentar über eine andere Aufgabe kann die spätere Fehlersuche erheblich erschweren. Der Kommentar soll die Absicht erklären, nicht jede sichtbare Zeile wiederholen. Eine kurze Notiz zum gewünschten Verhalten und zu bewusst ausgelassenen Fällen ist nützlicher als eine lange Beschreibung, die nach der ersten Änderung bereits nicht mehr stimmt.

Prüfen, bevor die echte Wirkung gebraucht wird

Die Dokumentation zur Konfigurationsfehlersuche beschreibt Prüf- und Diagnosemöglichkeiten. Für einen übernommenen Ausschnitt sind mehrere Stufen sinnvoll: Struktur prüfen, Konfiguration im passenden Zusammenhang akzeptieren lassen, einzelne Aktionen kontrolliert testen und schließlich den vollständigen Ablauf mit seinem echten Auslöser beobachten.

Ein manueller Aktionstest beantwortet nur einen Teil der Frage. Wenn die Lampe schaltet, sind Ziel und Aufruf möglicherweise passend. Ob die Automation zur richtigen Zeit startet und ihre Bedingungen sinnvoll auswertet, muss zusätzlich untersucht werden. Umgekehrt sollte ein ausbleibender Start nicht sofort zu Änderungen an einer funktionierenden Lampenaktion führen. Die Prüfung folgt den einzelnen Ebenen der Konfiguration.

Als Testumgebung eignet sich eine unkritische Funktion, deren Wirkung sofort erkennbar und leicht rückgängig zu machen ist. Nach jeder Probe wird der Ausgangszustand bewusst hergestellt. Andernfalls beeinflusst ein früherer Versuch den nächsten und erschwert die Interpretation. Ein kleines Protokoll mit Auslöser, beobachtetem Ergebnis und Änderung genügt, um aus zufälligem Ausprobieren einen nachvollziehbaren Lernprozess zu machen.

Aus einem übernommenen Beispiel wird eine eigene Regel

Am Ende sollte die Konfiguration nicht nur gespeichert, sondern erklärbar sein. Welche Zeilen beschreiben den Anlass? Welche wählen das Ziel? Welche Werte sind feste Einstellungen, welche werden berechnet? Welche Annahmen gelten für fehlende Zustände oder einen Neustart? Wer diese Fragen beantworten kann, ist nicht mehr von der ursprünglichen Vorlage abhängig.

Ein gutes Beispiel ist deshalb ein Ausgangspunkt für Verständnis. Es liefert eine überschaubare Struktur und eine konkrete Idee, ersetzt aber weder die Zuordnung zur eigenen Installation noch die Prüfung des gewünschten Verhaltens. Mit kleinen Änderungen, klaren Kennungen und getrennten Tests wird YAML zu einer lesbaren Beschreibung der eigenen Absicht. Genau das macht spätere Anpassungen einfacher: Man sucht nicht nach einem neuen Ausschnitt zum Kopieren, sondern verändert gezielt den Teil, dessen Bedeutung bereits bekannt ist.