Aqara Lichtschalter H2 EU in ZHA: Decoupled Mode per Custom-Quirk aktivieren

Die Aqara Lichtschalter H2 EU (Zigbee-Modell lumi.switch.agl009) laufen unter der ZHA-Integration von Home Assistant nur rudimentär: eine Schalt-Entität, Leistungs- und Energiewerte, sonst nichts. Kein Decoupled Mode, keine Klick-Events, keine LED- oder Power-On-Steuerung. Mit einem Custom-Quirk holst du das komplette Funktionsspektrum zurück – ganz ohne Wechsel zu Zigbee2MQTT. Diese Anleitung zeigt Schritt für Schritt, wie es geht, und wurde am 1. September 2026 auf sechs Schaltern real durchgeführt und verifiziert.

Warum die H2 unter ZHA nur halb funktioniert
Voraussetzungen
Schritt 1: Quirk-Ordner anlegen und in der YAML eintragen
Schritt 2: Die Quirk-Datei installieren
Schritt 3: Neu starten und prüfen
Diese neuen Entitäten bekommst du
Decoupled Mode sicher einschalten
Klick-Events in Automationen nutzen
Grenzen und Stolpersteine
FAQ

Warum die H2 unter ZHA nur halb funktioniert

Bindet man den H2 in ZHA ein, bekommt man eine switch-Entität, Leistung, Energiezähler, LQI/RSSI, Identify und die Firmware-Info – mehr nicht. Zum Vergleich: Unter Zigbee2MQTT ist exakt dasselbe Gerät vollständig unterstützt. Der Grund steckt in der Geräte-Diagnose. Lädt man sie herunter (Einstellungen → Geräte → das Gerät → Menü → „Diagnose herunterladen“), steht dort:

"quirk_applied": false,
"quirk_class": "zigpy.device.Device"

"quirk_applied": false,
"quirk_class": "zigpy.device.Device"

Es greift also gar kein Quirk – zigpy wertet nur das rohe ZCL-Profil aus. Der herstellerspezifische Cluster 0xFCC0 ist zwar auf mehreren Endpoints vorhanden, seine Attributliste ist aber leer. Genau dort liegen aber Decoupled Mode, LED-Steuerung, Power-On-Verhalten, Relay-Lock und Multi-Click. Zusätzlich bleiben die multistate_input-Cluster stumm, weshalb keine Tastendruck-Events entstehen. Ohne passenden Quirk kann ZHA diese Attribute schlicht nicht kennen. Wenn du die grundsätzlichen Unterschiede der beiden Zigbee-Wege noch sortieren willst, hilft unser Vergleich Zigbee2MQTT vs. ZHA.

Voraussetzungen

Home Assistant 2026.8 oder neuer (getestet mit 2026.8.3 auf HA OS 18.2)
Aktive ZHA-Integration (getestet mit zha 2.1.0 / zha-quirks 2.2.0)
Zugriff auf das /config-Verzeichnis, z. B. über das Add-on „Advanced SSH & Web Terminal“ oder „File editor“
Der H2 EU als lumi.switch.agl009 (2 Tasten/1 Kanal) – der Quirk deckt zusätzlich agl010, agl004, agl005 und agl006 ab

Der fertige Quirk stammt aus dem noch offenen Pull Request zigpy/zha-device-handlers #4141 („Add Aqara H2 switches (EU+US)“). Weil er noch nicht in zha-quirks 2.2.0 enthalten ist, binden wir ihn als lokalen Custom-Quirk ein.

Passendes Gerät: Aqara Lichtschalter H2 EU

Genau das in dieser Anleitung verwendete Modell: 2-in-1 (mit/ohne Neutralleiter), 2 Tasten / 1 Kanal, Thread & Matter, Zigbee-Modell lumi.switch.agl009.

Bei Amazon.de ansehen

Affiliate-Link – kaufst du darüber, unterstützt du netguide.io ohne Mehrkosten für dich.

Schritt 1: Quirk-Ordner anlegen und in der YAML eintragen

ZHA lädt Custom-Quirks aus einem Verzeichnis, das du in der configuration.yaml festlegst:

zha:
  enable_quirks: true
  custom_quirks_path: /config/zha_quirks/

zha:
  enable_quirks: true
  custom_quirks_path: /config/zha_quirks/

Reihenfolge beachten: Home Assistant prüft den Pfad beim Start mit cv.isdir. Existiert der Ordner noch nicht, scheitert die Konfigurationsprüfung. Lege deshalb zuerst das Verzeichnis /config/zha_quirks/ an und ergänze danach die YAML. Ein Feld im Options-Dialog der Integration gibt es dafür nicht – das ist reine YAML-Konfiguration.

Schritt 2: Die Quirk-Datei installieren

Am robustesten lädst du die Datei direkt auf einen festen Commit gepinnt herunter – so ändert sich der Inhalt nicht, während der PR weiterentwickelt wird. Im HA-Terminal:

wget -O /config/zha_quirks/switch_h2.py \
  https://raw.githubusercontent.com/lonevvolf/zha-device-handlers/c06083b1d655c1787f5c0c2f56edd84b970328d4/zhaquirks/xiaomi/aqara/switch_h2.py

# Integrität prüfen (optional, aber empfohlen)
sha256sum /config/zha_quirks/switch_h2.py
# fc846cbd24a37a51964196d999d46bc6516662d937227b9b1b2e1ed1410e017a  (19761 Bytes, 575 Zeilen)

ha core restart

wget -O /config/zha_quirks/switch_h2.py \
  https://raw.githubusercontent.com/lonevvolf/zha-device-handlers/c06083b1d655c1787f5c0c2f56edd84b970328d4/zhaquirks/xiaomi/aqara/switch_h2.py

# Integrität prüfen (optional, aber empfohlen)
sha256sum /config/zha_quirks/switch_h2.py
# fc846cbd24a37a51964196d999d46bc6516662d937227b9b1b2e1ed1410e017a  (19761 Bytes, 575 Zeilen)

ha core restart

Die Prüfsumme entspricht dem Commit c06083b vom 27. August 2026. Stimmt sie bei dir überein, hast du garantiert exakt dieselbe Datei wie in dieser Anleitung.

Schritt 3: Neu starten und prüfen

Nach dem Neustart lädst du erneut die Diagnose desselben Geräts herunter. Jetzt sollte dort stehen:

"quirk_applied": true,
"quirk_class": "switch_h2:(Aqara / lumi.switch.agl009)"

"quirk_applied": true,
"quirk_class": "switch_h2:(Aqara / lumi.switch.agl009)"

Im Systemprotokoll taucht die Meldung zhaquirks: Loaded custom quirks. Please contribute them to … auf – auf WARNING-Ebene. Das ist kein Fehler, sondern ein normaler Hinweis, dass ein Custom-Quirk aktiv ist.

Sichtbar wird das Ergebnis direkt am Gerät: Statt bisher 7 hat jeder Schalter nun 13 Entitäten. Die neue „Konfiguration“-Karte sieht so aus:

Home-Assistant-Konfigurationskarte des Aqara H2 EU mit Betriebsart Decoupled, LED-Anzeige, Lock relay, Multi click und Power on mode — Nach dem Quirk erscheinen Betriebsart (Decoupled), LED-Anzeige, Flip LED indicator, Lock relay, Multi click und Power on mode – die Werte werden echt vom Gerät gelesen.

Diese neuen Entitäten bekommst du

Entität	Typ	Funktion
Betriebsart	Select	Umschalten zwischen `Decoupled` und `Relay`
Power on mode	Select	Verhalten nach Stromrückkehr: `On`, `Previous`, `Off`, `Inverted`
LED-Anzeige	Switch	Status-LED ein-/ausschalten
Flip LED indicator	Switch	LED-Logik umkehren
Lock relay	Switch	Relais im aktuellen Zustand einfrieren
Multi click	Switch	Mehrfach-Klick-Erkennung aktivieren

Die Werte werden nicht nur angelegt, sondern real ausgelesen – bei unserem Test kam die Betriebsart als Relay und der Power-on-Modus als Previous zurück.

Decoupled Mode sicher einschalten

Im Decoupled Mode wird die Wippe vom Relais entkoppelt: Der physische Schalter kappt den Strom nicht mehr, sondern meldet nur noch den Tastendruck an Home Assistant. Das ist genau dann sinnvoll, wenn hinter dem Schalter smarte Leuchtmittel sitzen, die dauerhaft Strom brauchen. Damit die Lampen dabei zu keinem Zeitpunkt stromlos werden, gehst du in dieser Reihenfolge vor:

Zuerst die switch-Entität einschalten (Relais geschlossen, die Leuchtmittel haben Dauerstrom).
Dann die Betriebsart auf Decoupled stellen (die Wippe kann den Strom nun nicht mehr kappen).
Optional Lock relay aktivieren, damit auch keine versehentliche Automation das Relais öffnet.

Wichtig: Im Decoupled-Modus hängt der Lichtschalter an der Verfügbarkeit von Home Assistant. Ist HA aus, tut die Wippe nichts. Sitzt hinter dem Schalter eine ganz normale (nicht smarte) Lampe, brauchst du Decoupled deshalb gar nicht – dann schaltet die Wippe wie gewohnt direkt.

Klick-Events in Automationen nutzen

Der Quirk lässt die Tasten den zha_event feuern. Das Event-command setzt sich aus Endpoint und Druckart zusammen. Für den agl009 gilt:

Taste 1: 1_single, 1_double, 1_hold, 1_release
Taste 2: 4_single, 4_double, 4_hold, 4_release

Weil ZHA für diese Schalter keine event.*-Entitäten anlegt, triggerst du direkt auf das zha_event. Nutze dabei device_ieee statt device_id – die IEEE-Adresse übersteht ein Neuanlernen des Geräts. Verzweige über Trigger-IDs und choose:

alias: Küche – Wandschalter (decoupled)
triggers:
  - trigger: event
    event_type: zha_event
    event_data:
      device_ieee: "AA:BB:CC:DD:EE:FF:00:11"
      command: "1_single"
    id: toggle
  - trigger: event
    event_type: zha_event
    event_data:
      device_ieee: "AA:BB:CC:DD:EE:FF:00:11"
      command: "1_double"
    id: hell
conditions: []
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: toggle
        sequence:
          - action: light.toggle
            target:
              entity_id: light.kuche
      - conditions:
          - condition: trigger
            id: hell
        sequence:
          - action: light.turn_on
            target:
              entity_id: light.kuche
            data:
              brightness_pct: 100
mode: queued
max: 10

alias: Küche – Wandschalter (decoupled)
triggers:
  - trigger: event
    event_type: zha_event
    event_data:
      device_ieee: "AA:BB:CC:DD:EE:FF:00:11"
      command: "1_single"
    id: toggle
  - trigger: event
    event_type: zha_event
    event_data:
      device_ieee: "AA:BB:CC:DD:EE:FF:00:11"
      command: "1_double"
    id: hell
conditions: []
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: toggle
        sequence:
          - action: light.toggle
            target:
              entity_id: light.kuche
      - conditions:
          - condition: trigger
            id: hell
        sequence:
          - action: light.turn_on
            target:
              entity_id: light.kuche
            data:
              brightness_pct: 100
mode: queued
max: 10

mode: queued ist bewusst gewählt, damit schnelle Tastenfolgen nicht verworfen werden. Die Druckarten mappt der Quirk so: 0 = hold, 1 = single, 2 = double, 3 = triple, 255 = release.

Grenzen und Stolpersteine

Keine direkte Zigbee-Bindung an Lampen. EP 1 hat als Out-Cluster nur Time und OTA – keinen OnOff-Client. Der Schalter sendet also keine Zigbee-Schaltbefehle, sondern meldet Tastendrücke als Attributreport. „Binden“ und Zigbee-Gruppen scheiden damit aus; alles läuft über Home-Assistant-Automationen.
Schreibzugriffe können am Zigbee scheitern. Die H2 melden sich als EndDevice mit „Battery or Unknown“, obwohl sie netzbetrieben sind. ZHA behandelt sie dann zeitweise wie schlafende Geräte, und ein Umschalten quittiert mit ZIGBEE_DELIVERY_FAILED. Abhilfe: Wippe einmal drücken, um das Gerät zu wecken, dann erneut schreiben.
LED-Anzeige wirkt bei EU-Varianten evtl. nicht. Tester berichten, dass die LED-Steuerung bei EU-Modellen ohne Effekt bleibt, bei US/AU dagegen funktioniert. Decoupled Mode und Klick-Events sind davon nicht betroffen.
Lokale Kopie nach dem Merge löschen. Custom-Quirks haben Vorrang vor eingebauten. Sobald der PR gemergt und Teil von zha-quirks ist, solltest du switch_h2.py aus /config/zha_quirks/ entfernen – sonst überschreibt die eingefrorene Datei dauerhaft den gepflegten Upstream-Quirk.

FAQ

Was genau ist der Decoupled Mode?

Er entkoppelt die physische Wippe vom internen Relais. Der Schalter unterbricht den Strom dann nicht mehr selbst, sondern meldet nur den Tastendruck – ideal für smarte Leuchtmittel, die permanent Strom brauchen.

Brauche ich den Quirk auch bei einer normalen Lampe?

Nein. Sitzt eine gewöhnliche, nicht smarte Lampe hinter dem Schalter, funktioniert die Wippe im Standard-Modus (Relay) direkt und zuverlässig – auch ohne Home Assistant. Decoupled ergibt nur mit smarten Leuchtmitteln Sinn.

Was passiert, wenn der Pull Request gemergt wird?

Dann ist der Quirk irgendwann fester Bestandteil von zha-quirks. Lösche deine lokale switch_h2.py, damit die aktualisierte Upstream-Version verwendet wird und nicht deine eingefrorene Kopie.

Warum reagiert meine LED-Anzeige nicht?

Bei den EU-Varianten berichten mehrere Nutzer, dass die LED-Steuerung ohne Wirkung bleibt. Das ist bekannt und betrifft weder den Decoupled Mode noch die Klick-Events.

Kann ich den Schalter direkt an eine Zigbee-Lampe binden?

Nein. Dem Schalter fehlt der nötige OnOff-Client-Cluster. Die Verbindung zwischen Tastendruck und Lampe stellst du über eine Home-Assistant-Automation her (siehe oben).

Quellen: Pull Request #4141 (zha-device-handlers) · Device-Support-Request H2 EU · Zigbee2MQTT-Converter (Attribut-Semantik). Der Dimmer H2 EU (lumi.switch.agl011) wird von diesem Quirk übrigens nicht abgedeckt.