YAML & Konfiguration
YAML verstehen, configuration.yaml beherrschen und Template-Sensoren erstellen.
Was ist YAML?
YAML (YAML Ain't Markup Language) ist ein einfaches Textformat für Konfigurationen. Es nutzt Einrückungen statt Klammern und ist damit sehr gut lesbar. Home Assistant verwendet YAML für alles, was nicht (oder noch nicht) über die UI konfigurierbar ist.
Die 5 goldenen YAML-Regeln
- Einrückung mit Leerzeichen (2 Leerzeichen empfohlen, KEINE Tabs!)
- Schlüssel: Wert — immer mit Doppelpunkt und Leerzeichen
- Listen beginnen mit
-(Bindestrich + Leerzeichen) - Kommentare beginnen mit
# - Strings mit Sonderzeichen immer in Anführungszeichen
1# YAML Grundlagen — alle Konzepte
2# Das ist ein Kommentar
3
4# ── Einfacher Schlüssel-Wert ──
5name: "Mein Zuhause"
6elevation: 250
7debug_mode: true # Boolean: true/false
8
9# ── Verschachtelung (Einrückung!) ──
10location:
11 latitude: 52.52
12 longitude: 13.405
13 timezone: "Europe/Berlin"
14
15# ── Einfache Liste ──
16rooms:
17 - Wohnzimmer
18 - Küche
19 - Bad
20 - Schlafzimmer
21
22# ── Liste mit Objekten ──
23lights:
24 - name: Deckenlampe
25type: dimmbar
26room: Wohnzimmer
27 - name: Stehlampe
28type: farbe
29room: Schlafzimmer
30
31# ── Mehrzeiliger String (>) ──
32description: >
33 Dieser Text wird zu einer
34 einzigen Zeile zusammengefügt.
35
36# ── Mehrzeiliger String mit Zeilenumbrüchen (|) ──
37notes: |
38 Zeile 1 bleibt erhalten.
39 Zeile 2 auch.
40
41# ── Inline-Liste ──
42weekdays: [mon, tue, wed, thu, fri]
43
44# ── Inline-Objekt ──
45server: {host: "192.168.1.1", port: 8123}💡 Merkhilfe: Der Unterschied zwischen
>und|: Das Größer-Zeichen faltet Zeilen zusammen (→ eine Zeile), der Strich bewahrt Zeilenumbrüche.
configuration.yaml
Die zentrale Konfigurationsdatei liegt unter /config/configuration.yaml.
Hier definierst du Einstellungen, die nicht über die UI konfigurierbar sind.
1# configuration.yaml — kommentiertes Beispiel
2# ── Grundeinstellungen ──
3homeassistant:
4 name: "Wohnung Berlin" # Name deines Zuhauses
5 unit_system: metric # Metrisches System
6 currency: EUR # Währung
7 country: DE # Land (ISO 3166)
8
9# ── Standardmäßig eingebaut ──
10default_config: # Lädt alle Standard-Integrationen
11
12# ── HTTP-Server Konfiguration ──
13http:
14 use_x_forwarded_for: true # Nötig hinter Reverse Proxy
15 trusted_proxies:
16- 172.16.0.0/12 # Docker-Netzwerk
17 ip_ban_enabled: true # IP nach Fehlversuchen sperren
18 login_attempts_threshold: 5 # Nach 5 Fehlversuchen
19
20# ── Recorder-Einstellungen ──
21recorder:
22 purge_keep_days: 7 # Verlaufsdaten 7 Tage behalten
23 exclude:
24domains:
25 - media_player
26 - weather
27entity_globs:
28 - sensor.sun_*
29
30# ── Logger-Einstellungen ──
31logger:
32 default: warning # Standard-Level
33 logs:
34homeassistant.components.mqtt: debug
35custom_components: info
36
37# ── Eigene Template-Sensoren ──
38template:
39 - sensor:
40 - name: "Durchschnittstemperatur"
41 unit_of_measurement: "°C"
42 state: >
43 {{ ((states('sensor.wohnzimmer_temp') | float(0)) +
44 (states('sensor.schlafzimmer_temp') | float(0))) / 2 | round(1) }}
45
46# ── Dateien aufteilen ──
47automation: !include automations.yaml
48scene: !include scenes.yaml
49script: !include scripts.yamlDateien aufteilen mit !include
Bei wachsender Konfiguration wird die configuration.yaml schnell unübersichtlich.
Mit !include kannst du sie in mehrere Dateien aufteilen:
| Syntax | Beschreibung | Beispiel |
|---|---|---|
!include datei.yaml | Lädt eine einzelne Datei | automation: !include automations.yaml |
!include_dir_list ordner/ | Lädt alle Dateien als Liste | automation: !include_dir_list automations/ |
!include_dir_merge_list ordner/ | Lädt und merged Listen | Mehrere Dateien mit jeweils einer Liste |
!include_dir_named ordner/ | Dateiname wird Schlüssel | Ordner mit sensor/temp.yaml etc. |
1# Aufgeteilte Konfiguration
2# configuration.yaml:
3automation: !include_dir_merge_list automations/
4
5# Dann erstellst du separate Dateien:
6# automations/licht.yaml:
7- alias: "Flur-Licht bei Bewegung"
8 trigger: ...
9 action: ...
10
11# automations/heizung.yaml:
12- alias: "Heizung morgens"
13 trigger: ...
14 action: ...secrets.yaml
Sensible Daten wie Passwörter und API-Keys sollten NICHT direkt in der configuration.yaml stehen.
Stattdessen nutzt du secrets.yaml:
1# secrets.yaml
2# Passwörter und API-Keys hier speichern:
3mqtt_password: "mein-sicheres-passwort"
4openweather_api: "abc123def456"
5telegram_token: "bot123:ABC-DEF"
6latitude: "52.52"
7longitude: "13.405"# Verwendung in configuration.yaml
mqtt:
broker: 192.168.1.100
username: homeassistant
password: !secret mqtt_password # ← Liest aus secrets.yaml💡 Tipp: Wenn du deine HA-Konfiguration mit Git versionierst, füge
secrets.yamlzur.gitignorehinzu. So landen deine Passwörter nie im Repository.
YAML vs. UI-Konfiguration
| Aspekt | UI | YAML |
|---|---|---|
| Einfachheit | ✅ Klicken und auswählen | ⚠️ Text schreiben |
| Flexibilität | ⚠️ Begrenzt | ✅ Alles möglich |
| Versionierung | ❌ Schwer nachvollziehbar | ✅ Git-freundlich |
| Backup | In HA-Backup enthalten | Einfach als Textdatei |
| Template-Sensoren | ✅ Seit 2023 auch per UI | ✅ Immer möglich |
| Portabilität | ❌ An Installation gebunden | ✅ Einfach übertragbar |
| Massenbearbeitung | ❌ Einzeln | ✅ Suchen & Ersetzen |
💡 Empfehlung: Starte mit der UI! Du kannst jederzeit zu YAML wechseln, wenn die UI an ihre Grenzen stößt. Viele Automationen zeigen dir in der UI den YAML-Code an — so lernst du nebenbei.
Häufige YAML-Fehler
| Fehler | Problem | Lösung |
|---|---|---|
| Tabs statt Leerzeichen | YAML erlaubt keine Tabs | Nutze 2 Leerzeichen. Stelle den Editor auf „Spaces" ein. |
| Fehlende Einrückung | Untergeordnete Elemente müssen eingerückt sein | Jede Ebene = 2 zusätzliche Leerzeichen |
: ohne Leerzeichen | name:wert statt name: wert | Immer Leerzeichen nach dem Doppelpunkt |
| Anführungszeichen vergessen | Strings mit :, #, {} etc. | In Anführungszeichen setzen: "Wert: mit Doppelpunkt" |
| Falsche Einrückungs-Ebene | Element auf falscher Ebene | Genau prüfen, zu welchem übergeordneten Element es gehört |
| Doppelte Schlüssel | Gleicher Schlüssel zweimal | Jeden Schlüssel nur einmal pro Ebene |
Tipp: Nutze den „Konfiguration prüfen"-Button unter Entwicklerwerkzeuge → YAML! Er zeigt dir genau die Zeile des Fehlers an.
Template-Sensoren (Jinja2)
Home Assistant nutzt Jinja2 als Template-Sprache. Damit kannst du berechnete Werte erstellen, dynamische Texte in Automationen schreiben und eigene Sensoren definieren.
Jinja2 Grundlagen
1# Jinja2 Syntax
2# ── Werte ausgeben ──
3{{ states('sensor.temperatur') }} # → "21.5"
4{{ state_attr('light.wohnzimmer', 'brightness') }} # → 200
5
6# ── Rechnen ──
7{{ states('sensor.temperatur') | float + 2 }} # → 23.5
8{{ states('sensor.preis') | float * 100 | round(2) }}
9
10# ── Bedingungen ──
11{{ "warm" if states('sensor.temp') | float > 25 else "kühl" }}
12
13# ── Filter ──
14{{ states('sensor.name') | upper }} # → "WOHNZIMMER"
15{{ states('sensor.name') | replace('_', ' ') }}
16{{ 1234.5 | round(0) }} # → 1235
17
18# ── Datum & Zeit ──
19{{ now().strftime('%H:%M') }} # → "14:30"
20{{ as_timestamp(now()) | timestamp_custom('%d.%m.%Y') }}
21
22# ── Listen filtern ──
23{{ states.light
24 | selectattr('state', 'eq', 'on')
25 | list | count }} # → Anzahl eingeschalteter LichterTemplate-Sensor Beispiele
1# Praktische Template-Sensoren
2template:
3 - sensor:
4 # ── Fenster-Zähler ──
5 - name: "Offene Fenster"
6 icon: mdi:window-open
7 state: >
8 {{ states.binary_sensor
9 | selectattr('attributes.device_class', 'eq', 'window')
10 | selectattr('state', 'eq', 'on')
11 | list | count }}
12
13 # ── Wer ist zuhause? ──
14 - name: "Personen zuhause"
15 icon: mdi:account-group
16 state: >
17 {{ states.person
18 | selectattr('state', 'eq', 'home')
19 | map(attribute='name')
20 | list | join(', ') or 'Niemand' }}
21
22 # ── Durchschnittstemperatur ──
23 - name: "Durchschnitt Innen"
24 unit_of_measurement: "°C"
25 device_class: temperature
26 state: >
27 {% set temps = [
28 states('sensor.wohnzimmer_temp') | float(0),
29 states('sensor.schlafzimmer_temp') | float(0),
30 states('sensor.kueche_temp') | float(0)
31 ] | reject('equalto', 0) | list %}
32 {{ (temps | sum / temps | count) | round(1) if temps else 'unavailable' }}
33
34 # ── Tägliche Stromkosten ──
35 - name: "Stromkosten heute"
36 unit_of_measurement: "€"
37 icon: mdi:currency-eur
38 state: >
39 {{ (states('sensor.strom_taeglich') | float(0) * 0.35) | round(2) }}
40
41 # ── Müll-Erinnerung ──
42 - name: "Nächste Abholung"
43 icon: mdi:trash-can
44 state: >
45 {% set events = state_attr('calendar.abfallkalender', 'description') %}
46 {{ events or 'Unbekannt' }}
47
48 # ── Binary Sensor (Ja/Nein) ──
49 - binary_sensor:
50 - name: "Jemand zuhause"
51 device_class: presence
52 state: >
53 {{ states.person
54 | selectattr('state', 'eq', 'home')
55 | list | count > 0 }}
56
57 - name: "Alle Fenster zu"
58 device_class: window
59 state: >
60 {{ states.binary_sensor
61 | selectattr('attributes.device_class', 'eq', 'window')
62 | selectattr('state', 'eq', 'on')
63 | list | count == 0 }}Packages: Alles zu einem Thema in einer Datei
Packages erlauben es dir, zusammengehörige Konfigurationen (Automationen, Sensoren, Scripts) in einer einzigen Datei zu bündeln:
1# Package: Waschmaschine (packages/waschmaschine.yaml)
2# Alles zur Waschmaschine in einer Datei:
3
4template:
5 - sensor:
6 - name: "Waschmaschine Status"
7 state: >
8 {% set power = states('sensor.waschmaschine_power') | float(0) %}
9 {% if power > 1000 %}Waschen
10 {% elif power > 5 %}Laufen
11 {% elif power > 0 %}Standby
12 {% else %}Aus{% endif %}
13
14automation:
15 - alias: "Waschmaschine fertig"
16trigger:
17 - platform: state
18 entity_id: sensor.waschmaschine_status
19 from: "Waschen"
20 to: "Standby"
21 for: "00:02:00"
22action:
23 - service: notify.mobile_app_mein_handy
24 data:
25 title: "👕 Waschmaschine fertig!"
26 message: "Die Wäsche kann aufgehängt werden."
27
28input_boolean:
29 waschmaschine_benachrichtigt:
30name: "Waschmaschine bereits benachrichtigt"1# Packages in configuration.yaml einbinden
2homeassistant:
3 packages:
4waschmaschine: !include packages/waschmaschine.yaml
5heizung: !include packages/heizung.yaml
6licht: !include packages/licht.yamlNützliche YAML-Patterns
Anchors & Aliases (Wiederverwendung)
1# YAML Anchors
2# Definiere einen Wert einmal mit &name
3defaults: &light_defaults
4 brightness_pct: 80
5 color_temp_kelvin: 3000
6 transition: 2
7
8# Verwende ihn mit *name
9automation:
10 - alias: "Licht Wohnzimmer"
11action:
12 - service: light.turn_on
13 target:
14 entity_id: light.wohnzimmer
15 data:
16 <<: *light_defaults # ← Fügt alle Werte ein!
17
18 - alias: "Licht Schlafzimmer"
19action:
20 - service: light.turn_on
21 target:
22 entity_id: light.schlafzimmer
23 data:
24 <<: *light_defaults # ← Gleiche Werte!
25 brightness_pct: 40 # ← Überschreibt nur diesen WertBedingte Konfiguration mit Template
1# Dynamische Werte in Automationen
2automation:
3 - alias: "Adaptive Helligkeit"
4trigger:
5 - platform: state
6 entity_id: binary_sensor.flur_motion
7 to: "on"
8action:
9 - service: light.turn_on
10 target:
11 entity_id: light.flur
12 data:
13 brightness_pct: >
14 {% if now().hour < 7 %}
15 20
16 {% elif now().hour < 18 %}
17 100
18 {% else %}
19 60
20 {% endif %}
21 color_temp_kelvin: >
22 {% if now().hour < 7 or now().hour > 20 %}
23 2700
24 {% else %}
25 4500
26 {% endif %}Konfiguration prüfen & validieren
Bevor du Home Assistant neustartest, immer die Konfiguration prüfen:
- Gehe zu Entwicklerwerkzeuge → YAML
- Klicke auf „Konfiguration prüfen"
- Wenn „Konfiguration ist gültig" erscheint → Neustart sicher
- Bei Fehlern: Die Fehlermeldung zeigt Dateiname und Zeilennummer
💡 Profi-Tipp: Installiere das File Editor Add-on — es hat Syntax-Highlighting und zeigt YAML-Fehler direkt an. Alternativ: VS Code mit der Home Assistant Config Helper Extension für Auto-Completion und Validierung auf deinem PC.
