Aqara W100 Sync (ZHA) für Home Assistant

Home-Assistant-Blueprints, um ein Aqara Climate Sensor W100 (lumi.sensor_ht.agl001) über ZHA als Wandbedienteil für Heizung, Klimaanlage und Lüfter zu nutzen — mit getrennten Ziel-Entitäten für Heizen, Kühlen und Fan.

Basiert auf der ursprünglichen Idee von nokside/ha-toolbox und erweitert sie um getrenntes Heiz-/Kühl-/Fan-Routing, Dry-Modus, Mehrfach-/Label-/Bereichs-Auswahl, pro-Sektion-Wertsync und eine Hybrid-Auslösung.

⚠️ Ohne Gewähr. Die Blueprints sind sorgfältig geprüft (YAML-Parsing, Template-Logik), aber nicht in jeder HA-Umgebung getestet. Erst mit einem unkritischen Gerät testen, bevor echte Heiz-/Kühlsysteme angesteuert werden.

---

Inhalt

blueprints/automation/aqara-w100/
├── aqara_w100_direct.yaml    # Direktauswahl (Mehrfach-Entitäten + Labels)
├── aqara_w100_target.yaml    # Target-Auswahl (Entitäten/Geräte/Bereiche/Labels)
└── aqara_w100_hybrid.yaml    # Hybrid: Target + Sofort-Sync-Entitäten (empfohlen)
quirks/
└── aqara_w100.py             # ZHA-Quirk (Voraussetzung für ALLE Varianten)
examples/
├── climate.yaml              # Optional: Template-Climate-Wrapper (volle Lüfterstufen)
└── lovelace-cards.yaml       # Dashboard-Karten (nativ & mit Wrapper)

---

Voraussetzungen

• Home Assistant mit ZHA und angelerntem Aqara W100.
• Der Quirk quirks/aqara_w100.py muss installiert sein (siehe unten). Ohne ihn fehlen die number.*external_temperature/external_humidity-Entitäten sowie ein sauberer Climate-Betrieb.
• Je nach Nutzung im W100-Gerät aktivieren: External sensor, Thermostat control mode und/oder Show fan.
• Für Label-Auswahl: Home Assistant 2024.10+.

---

Installation

1. Quirk installieren

Custom-ZHA-Quirks liegen in einem Verzeichnis, das in configuration.yaml referenziert wird:

# configuration.yaml
zha:
  custom_quirks_path: /config/zha_quirks/

Datei quirks/aqara_w100.py nach /config/zha_quirks/aqara_w100.py kopieren und Home Assistant neu starten. Danach den W100 in ZHA einmal neu konfigurieren (Gerät → Neu konfigurieren), falls Entitäten fehlen.

2. Blueprint importieren

Eine der drei YAML-Dateien nach config/blueprints/automation/aqara-w100/ kopieren und unter Einstellungen → Automatisierungen & Szenen → Blueprints neu laden — oder per Blueprint importieren die Roh-URL der gewünschten Datei einfügen.

Die drei Varianten haben unterschiedliche Namen und stören sich nicht — du kannst sie parallel installieren und vergleichen.

3. Automatisierung anlegen

Blueprint auswählen, W100 setzen, mindestens eine Sektion (Heizen/Kühlen/Fan) befüllen, speichern.

---

Welche Variante? (3 Blueprints im Vergleich)

Nach dem Import erscheinen drei Blueprints in Home Assistant. Sie sind funktional gleichwertig — gleiches Modus-Routing, gleicher Dry-Modus, gleicher „Sync Werte"-Schalter. Sie unterscheiden sich nur in zwei Punkten:

1. Wie du die Geräte auswählst (nur Entitäten/Labels — oder auch Geräte/Bereiche).
2. Wie schnell eine Änderung am Gerät zurück zum W100 kommt (sofort oder per Polling).

	Direct (Multi/Label)	Target	Hybrid ⭐
Blueprint-Name in HA	…Heizen/Kühlen/Fan getrennt (Multi/Label)	…(Target-Auswahl)	…(Hybrid)
Datei	aqara_w100_direct.yaml	aqara_w100_target.yaml	aqara_w100_hybrid.yaml
Einzelne Entitäten wählen	✅	✅	✅
Auswahl per Label	✅	✅	✅
Auswahl per Gerät / Bereich	❌	✅	✅
Gerät→W100 bei direkt gewählten Entitäten	⚡ sofort	🕒 Polling	⚡ sofort
Gerät→W100 bei Label / Bereich / Gerät	🕒 Polling	🕒 Polling	🕒 Polling
Polling-Intervall	5 Min	2 Min	1 Min
Felder pro Sektion	2 (Entitäten + Labels)	1 (Target-Picker)	2 (Target + Sofort-Sync)
Empfehlung	kleine, einfache Setups	reine Massensteuerung	Standard

Warum überhaupt „Polling"?

Home Assistant kann State-Trigger nur auf direkt ausgewählte Entitäten legen — nicht auf Geräte, Bereiche oder Labels. Alles, was über einen Target-Picker (Gerät/Bereich/Label) ausgewählt wird, kann daher nicht „live" abgehört werden.

Für die Richtung W100 → Geräte ist das egal: Ausgelöst wird durch den W100 selbst, und die Befehle erreichen immer sofort alle ausgewählten Ziele — unabhängig von der Variante.

Nur die Rückrichtung (du drehst am Thermostat → W100 soll nachziehen) ist betroffen: Sie funktioniert für Target-/Label-/Bereichsauswahl nur zeitgesteuert (Polling), also mit etwas Verzögerung. Genau hier setzt die Hybrid-Variante an.

Die drei Varianten im Klartext

• Direct (Multi/Label) — Pro Sektion zwei Felder: mehrere Entitäten und Labels. Direkt gewählte Entitäten melden sofort zurück, Label-Entitäten per Polling (5 Min). Kein Geräte-/Bereichs-Picker. Schlank für kleine Setups.

• Target — Pro Sektion ein Feld: der HA-Target-Dialog (Entitäten / Geräte / Bereiche / Labels gemischt). Am aufgeräumtesten und am flexibelsten bei der Auswahl — dafür läuft die Rückrichtung komplett über Polling (2 Min), auch bei einzeln gewählten Entitäten.

• Hybrid ⭐ (empfohlen) — Kombiniert beides: der Target-Picker für die Masse plus ein zusätzliches Feld „Sofort-Sync Entität(en)" für die Leit-Geräte. Die dort gewählten Entitäten bekommen echte State-Trigger und melden sofort zurück (inkl. der auslösenden Entität als Quelle); alles Übrige wird per Polling (1 Min) nachgezogen.

  Typische Nutzung: Klimaanlage / Haupt-Thermostat → Sofort-Sync-Feld. Alle Heizkörper eines Raums → per Bereich oder Label in den Target-Picker.

Kann ich alle drei parallel installiert lassen?

Ja. Die drei haben unterschiedliche Blueprint-Namen und stören sich nicht — du kannst sie nebeneinander behalten und pro Automatisierung auswählen. Wenn du dich entschieden hast (in der Regel Hybrid), lassen sich die anderen beiden einfach löschen.

---

Funktionsweise

Modus-Routing (W100 → Geräte)

Der am W100 gewählte HVAC-Modus wird auf die passenden Sektionen verteilt:

W100-Modus	Heizen	Kühlen	Fan
heat	heat	aus	aus
cool	aus	cool	aus
dry	aus	dry (Fallback cool)	aus
fan_only	aus	aus	fan_only / fan.turn_on
heat_cool / auto	heat	cool	aus
off	aus	aus	aus

Bei heat_cool/auto bekommt jede Sektion ihren eigenen Modus (Heizen heat, Kühlen cool) — es wird nicht versucht, heat_cool an ein einzelnes Gerät zu senden. Geräte ohne den passenden Modus fallen auf heat_cool/auto zurück, sofern verfügbar.

Rückrichtung (Geräte → W100)

Der W100 spiegelt den zusammengefassten Zustand: laufen Heizen und Kühlen → heat_cool/auto; nur Heizen → heat; nur Kühlen → cool; nur Fan → fan_only; sonst off.

Wichtige HA-Beschränkung: State-Trigger können keine Target-/Geräte-/Bereichs-/Label-Auswahl abhören. Deshalb ist die Rückrichtung für so ausgewählte Entitäten poll-basiert (Standard: Direct 5 Min, Target 2 Min, Hybrid 1 Min — im time_pattern-Trigger anpassbar). In der Hybrid-Variante lösen die zusätzlichen Sofort-Sync-Entitäten die Rückrichtung dagegen unmittelbar aus.

Schalter „Sync Werte" (pro Sektion)

• An (Standard): Der Sollwert wird bidirektional gespiegelt — bei Heizen/Kühlen die eingestellte Zieltemperatur, bei Fan die Lüfterstufe.
• Aus: Nur noch Moduswechsel (an/aus) für diese Sektion. Der Sollwert bleibt unangetastet — praktisch, wenn der W100 z.B. die Klimaanlage nur ein-/ausschalten, die Temperatur dort aber unabhängig geregelt werden soll.

Sollwert = die eingestellte Zieltemperatur (z.B. „21 °C"), nicht die gemessene Ist-Temperatur. Der Ist-Wert-Push aufs Display ist eine separate Funktion (Sensoren-Sektion, Schalter Sync Temperatur/Luftfeuchte).

Temperatur-Handling

• W100 → Gerät: Sollwert wird individuell auf min_temp/max_temp jedes Geräts geclampt.
• Gerät → W100: Sollwert wird auf den W100-Bereich (4.5–37.0 °C) geprüft; außerhalb wird übersprungen.
• Broadcast an alle aktiven Ziele einer Sektion (nur laufende, nicht off/unavailable).

Lüfterstufen am W100 (wichtig)

Der Lüftermodus in der Climate-Karte zeigt nur Auto / Ein. Das ist eine Limitierung von ZHA selbst (fan_modes ist im ZHA-Code fest auf [FAN_AUTO, FAN_ON] gesetzt und ignoriert fan_mode_sequence) — ein Quirk kann daran nichts ändern.

Die vollen Stufen stehen daher in einer eigenen Select-Entität „Fan mode" am W100-Gerät bereit:

Option	Wirkung am Display
Off	Lüfterzeile ausgeblendet
Low / Medium / High	1 / 2 / 3 Balken
Auto	Auto

Wählt man in der Climate-Karte dennoch Ein, wird das auf High gemappt (sonst würde das Lüfterfeld aus dem Protokoll-Frame fallen und der W100 gar keinen Lüfter mehr anzeigen).

Lösungsweg A — nativ (empfohlen)

Thermostat-Karte + Lüferstufe als Buttonleiste darunter — ohne Zusatz-Integration:

type: vertical-stack
cards:
  - type: thermostat
    entity: climate.<w100>
  - type: tile
    entity: select.<w100>_fan_mode
    name: Lüfterstufe
    icon: mdi:fan
    features:
      - type: select-options

Vollständiges Beispiel: examples/lovelace-cards.yaml

Lösungsweg B — Template-Climate-Wrapper (eine Karte, alle Stufen)

Wer die fünf Stufen unbedingt im Dropdown der Thermostat-Karte haben will, kann eine Wrapper-Entität anlegen. Sie spiegelt den W100 und schreibt die Lüterstufe intern auf die Select-Entität.

1. HACS → ⋮ → Custom repositories → https://github.com/litinoveweedle/hass-template-climate (Typ: Integration) → Template Climate installieren
2. examples/climate.yaml nach /config/climate.yaml kopieren und Entity-IDs anpassen
3. In configuration.yaml: climate: !include climate.yaml
4. Home Assistant neu starten (YAML-Plattformen werden nur beim Start geladen — „Konfiguration neu laden" genügt nicht, und ha core check prüft nur die Syntax)

Es entstehen zusätzliche Entitäten (climate.<name>_thermostat). Aufs Dashboard nur die Wrapper legen, die ZHA-Originale ggf. ausblenden.

⚠️ Wichtig für die Blueprints: In den Automatisierungen weiterhin die ZHA-Original-Entität als „Aqara W100" auswählen, nicht den Wrapper — sonst synchronisiert sich der Aufbau im Kreis. Der Wrapper ist reine Bedienoberfläche.

Fan-Sync

• Fan (Climate-Domäne): Sync per fan_mode-Attribut, gemappt auf die vom Zielgerät unterstützten fan_modes.
• Fan (fan-Domäne): einfache 3-Stufen-Zuordnung low/medium/high → 33/66/100 %, auto → Preset (falls vorhanden). Bei Bedarf im Action-Block anpassbar.

Sensor-Push aufs W100-Display

Über den Schalter Sync Temperatur/Luftfeuchte in der Sensoren-Sektion wird current_temperature/current_humidity aufs Display geschrieben — Quelle sind dedizierte Sensoren (Priorität, sofort) oder sonst die erste Heizen-/Kühlen-Entität (per Polling).

---

Bekannte Einschränkungen

• Poll-basierte Rückrichtung für Label/Bereich/Gerät (HA-State-Trigger-Limitierung). In Hybrid über Sofort-Sync-Entitäten umgehbar.
• Bereich/Label ziehen ALLE passenden Entitäten der Domäne — ein Bereich für „Heizen" nimmt alle climate.* darin. Für präzise Steuerung einzelne Entitäten/gezielte Labels verwenden.
• Änderungen an der Bereichs-/Label-/Gerätezuordnung wirken erst nach einem Automatisierungs-Reload (bzw. HA-Neustart).
• Beim Polling mit mehreren Entitäten pro Sektion dient die erste aktive Entität als Referenz für den W100 (kein Trigger-Kontext). Bei genau einem Gerät irrelevant.
• Die Fan-(fan-Domäne)-Stufenzuordnung ist eine 3-Stufen-Annahme.

---

Änderungsverlauf gegenüber dem Original

• Getrennte Sektionen Heizen / Kühlen / Fan statt eines einzelnen Primär-Thermostats.
• Dry-Modus-Routing (→ Kühlen, Fallback cool).
• Mehrfach-Auswahl je Sektion, plus Label-/Bereichs-/Geräte-Auswahl (Target/Hybrid).
• Pro-Sektion-Schalter „Sync Werte" (Sollwert/Stufe an/aus).
• Hybrid-Auslösung: sofortige Rückrichtung für direkt gewählte Leit-Entitäten, Polling für den Rest.

---

Credits & Lizenz

• Ursprüngliches Blueprint-Konzept und Quirk-Grundlage: nokside — https://github.com/nokside/ha-toolbox
• Erweiterungen in diesem Repo: siehe README oben.

Lizenz: siehe LICENSE (MIT). Der Quirk unterliegt ggf. der Lizenz des Ursprungsprojekts — bitte dort prüfen, bevor er weiterverbreitet wird.