Tuya-Zigbee mit ZHA und Zigbee2MQTT: Warum Geräte trotz Zigbee 3.0 unterschiedlich funktionieren

Auf der Verpackung steht „Zigbee 3.0“, das Gerät lässt sich anlernen – und trotzdem fehlen in Home Assistant einzelne Schalter, Messwerte oder Einstellungen. Besonders bei Geräten aus dem Tuya-Umfeld ist das kein ungewöhnliches Bild. Der Funkstandard funktioniert, doch die verwendete Zigbee-Software muss auch die konkrete Gerätevariante und deren Funktionen kennen.

Der häufig gezogene Schluss „Tuya-Zigbee ist kein echtes Zigbee 3.0“ greift allerdings zu kurz. Tuya dokumentiert selbst Geräteprofile auf Basis eines Zigbee-3.0-Stacks. Gleichzeitig nutzen viele Tuya-Geräte einen herstellerspezifischen Cluster und sogenannte Data Points. Beides kann im selben Produkt vorkommen. Das eigentliche Problem ist daher nicht der Funkstandard allein, sondern die Interoperabilität auf Geräte- und Anwendungsebene.

Zigbee 3.0 ist kein universeller Gerätetreiber

Zigbee legt fest, wie Geräte ein Netzwerk bilden und miteinander kommunizieren. Für verbreitete Funktionen existieren standardisierte Gerätearten, Cluster, Befehle und Attribute. Ein einfacher Schalter kann seine Zustände beispielsweise über den standardisierten On/Off-Cluster bereitstellen.

Hersteller können darüber hinaus eigene Funktionen ergänzen. Genau hier entstehen Unterschiede: Ein Gateway kann ein Gerät erfolgreich ins Zigbee-Netz aufnehmen, ohne jede zusätzliche Funktion zu verstehen. „Gepaart“ bedeutet deshalb noch nicht „vollständig unterstützt“.

Auch eine Zigbee-Zertifizierung ist kein Versprechen, dass jede beliebige Zentrale jede produktspezifische Funktion ohne Anpassung anzeigt. Die Connectivity Standards Alliance prüft zertifizierte Endprodukte auf Konformität und führt sie in einer öffentlichen Datenbank. Ob Home Assistant mit ZHA oder Zigbee2MQTT eine konkrete Hardware- und Firmwarevariante vollständig abbildet, hängt zusätzlich von der jeweiligen Geräteunterstützung ab.

Wichtig ist die begriffliche Trennung: ZHA bezeichnet in diesem Artikel die Zigbee-Integration von Home Assistant. Der ähnlich klingende ältere Begriff „Zigbee Home Automation Profile“ ist damit nicht gemeint.

Was Tuya-Datenpunkte anders machen

Viele Tuya-Geräte übertragen Funktionen über den herstellerspezifischen Cluster 0xEF00, den Zigbee2MQTT als manuSpecificTuya bezeichnet. Innerhalb der Nachrichten stehen Data Point IDs, kurz DPs oder DPIDs. Ein solcher Datenpunkt kann etwa einen Schaltzustand, eine Temperatur, eine Betriebsart oder eine Geräteeinstellung repräsentieren.

Die Nummer allein sagt jedoch nicht zuverlässig, welche Funktion dahintersteckt. Laut Zigbee2MQTT sind Tuya-Datenpunkte nicht geräteübergreifend vereinheitlicht. Derselbe DPID kann bei verschiedenen Geräten eine andere Bedeutung haben. Deshalb benötigt die Software für die konkrete Gerätevariante eine passende Zuordnung einschließlich Datentyp und gegebenenfalls Wertumrechnung.

Das erklärt typische Symptome:

• Das Gerät wird erkannt, aber einzelne Entitäten fehlen.
• Ein Wert erscheint, besitzt jedoch den falschen Datentyp oder Maßstab.
• Mehrere äußerlich gleiche Geräte melden unterschiedliche Herstellerkennungen.
• Nach dem Pairing ist nur ein Teil der Funktionen nutzbar.
• Im Protokoll tauchen nicht zugeordnete Tuya-Datenpunkte oder unbekannte Befehle auf.

Nicht jedes Tuya-Gerät verwendet ausschließlich 0xEF00. Manche Produkte stellen Basisfunktionen über Standard-Cluster bereit und nutzen herstellerspezifische Erweiterungen nur für Zusatzoptionen. Andere benötigen für fast jede Funktion eine gerätespezifische Übersetzung. Eine pauschale Einteilung allein anhand des Markennamens wäre daher falsch.

ZHA und Zigbee2MQTT lösen dasselbe Problem unterschiedlich

ZHA basiert auf zigpy. Weicht ein Gerät von der erwarteten Beschreibung ab oder nutzt herstellerspezifische Funktionen, kann ein ZHA Device Handler – meist „Quirk“ genannt – diese Besonderheiten übersetzen. Die offizielle Home-Assistant-Dokumentation weist ausdrücklich darauf hin, dass ein Gerät trotz erfolgreichem Beitritt unvollständig erscheinen und einen solchen Handler benötigen kann.

Zigbee2MQTT verwendet Geräte-Definitionen und Konverter aus dem Projekt zigbee-herdsman-converters. Bei Tuya-Geräten werden Modellkennung und Herstellerkennung als Fingerprint herangezogen, weil generische Modellnamen wie TS0601 für viele technisch unterschiedliche Produkte verwendet werden. Der Konverter legt fest, welche Funktionen Zigbee2MQTT als sogenannte Exposes veröffentlicht.

Damit ist weder ZHA grundsätzlich ungeeignet noch Zigbee2MQTT automatisch vollständig. Entscheidend ist, ob die konkrete Kombination aus Modell-ID, Hersteller-ID und Firmware bereits unterstützt wird. Der Entwicklungsstand kann zwischen beiden Projekten verschieden sein.

Praxisfall: BSEED EC-GL86ZPCS21

Im Schlafzimmer sind bei uns zwei BSEED-Schalter des Modells EC-GL86ZPCS21 im Einsatz. Die Geräte melden sich mit der Herstellerkennung _TZ3002_zjuvw9zf. Zigbee2MQTT führt das Modell EC-GL86ZPCS21 als BSEED-Zweifachschalter mit Szenen- und Hintergrundbeleuchtungsfunktionen. Die Unterstützung der Kennung _TZ3002_zjuvw9zf wurde im Projektverlauf für dieses Modell ergänzt. Bereitgestellt werden unter anderem die getrennten Schaltzustände state_l1 und state_l2 sowie Schalteraktionen.

Unter ZHA wurden die beiden Schaltkanäle bei unseren Exemplaren nicht sauber getrennt: Beim Schalten reagierten beide Kanäle. Ein getesteter Quirk beseitigte das Verhalten nicht. Nach dem Wechsel zu Zigbee2MQTT wurden die Schaltfunktionen getrennt bereitgestellt und ließen sich unabhängig auswerten.

Die elektrische Installation nutzt dabei nur den tatsächlich an die Last angeschlossenen Schaltweg. Die zusätzliche Schaltfunktion läuft logisch: Zigbee2MQTT liefert den Tastendruck beziehungsweise die zugehörige Entität, Node-RED wertet ihn aus und schaltet den jeweils gewünschten Kanal. So entsteht eine virtuelle Wechselschaltung, ohne dass der zweite Bedienpunkt die Last direkt über eine klassische korrespondierende Leitung schaltet.

Dieser Aufbau zeigt zwei Dinge. Erstens kann ein bereits vorhandener Konverter in Zigbee2MQTT ein konkretes Gerät besser abbilden als der zum Testzeitpunkt verfügbare ZHA-Handler. Zweitens ersetzt die Automatisierung keine elektrische Wechselschaltung: Fällt Home Assistant, Zigbee2MQTT, MQTT, Node-RED oder das Funknetz aus, funktioniert der logisch angebundene Bedienweg nicht. Der lokal verdrahtete Schaltweg bleibt davon getrennt zu betrachten.

Der Fall ist eine dokumentierte Erfahrung mit den hier eingesetzten BSEED-Schaltern EC-GL86ZPCS21. Er belegt nicht, dass jedes BSEED- oder Tuya-Gerät unter ZHA dasselbe Verhalten zeigt. Selbst zu diesem Modell sind unterschiedliche Hardwarechargen dokumentiert; die konkrete Gerätekennung bleibt deshalb wichtiger als das Aussehen oder die Verkaufsbezeichnung.

So arbeitet die virtuelle Wechselschaltung

Der Node-RED-Flow benötigt im Kern drei Schritte:

1. Er erkennt den Zustandswechsel oder das von Zigbee2MQTT veröffentlichte Schalterereignis.

2. Er ordnet dieses Ereignis der Ziel-Entität in Home Assistant zu.

3. Er schaltet die Ziel-Entität gezielt ein, aus oder um.

Für einen belastbaren Betrieb sollten zusätzlich Wiederholungen und Rückkopplungen bedacht werden. Ein Flow darf nicht auf seine eigene Zustandsänderung erneut reagieren und dadurch eine Schleife erzeugen. Nach einem Neustart muss außerdem klar sein, ob der reale Zustand des Aktors oder ein zuvor gespeicherter Sollzustand maßgeblich ist. Bei einer reinen Toggle-Logik können verlorene oder doppelte Nachrichten sonst zu einem unerwarteten Zustand führen.

Für die konkrete Installation wurde in diesem Artikel bewusst kein importierbarer Node-RED-Flow ergänzt. Entitätsnamen, Ereignisse und das von Zigbee2MQTT veröffentlichte Datenformat sind geräte- und installationsabhängig. Ein scheinbar universeller Flow wäre ohne diese Angaben nicht verlässlich.

Vor dem Kauf: Nicht nur nach „Zigbee 3.0“ suchen

Die Produktbeschreibung allein reicht selten. Sinnvoller ist diese Reihenfolge:

1. Exakte Gerätevariante ermitteln

Markenname und Verkaufsbezeichnung sind bei White-Label-Produkten oft nicht eindeutig. Aussagekräftiger sind die in der Zigbee-Software sichtbaren Angaben modelID und manufacturerName. Bei Tuya beginnen Herstellerkennungen häufig beispielsweise mit _TZ3000_, _TZ3002_, _TZE200_ oder _TZE204_. Diese Präfixe sind ein Hinweis auf die Gerätefamilie, aber keine vollständige Kompatibilitätsaussage.

2. Zigbee2MQTT-Datenbank prüfen

Die Datenbank zeigt, welche Eigenschaften eine konkrete Definition tatsächlich bereitstellt. Ein bloßer Treffer nach dem Produktnamen genügt nicht; Fingerprints und dokumentierte Exposes müssen zur gewünschten Funktion passen. Fehlt das Gerät, kann es neu, anders gelabelt oder noch nicht unterstützt sein.

3. ZHA-Unterstützung separat prüfen

Eine Listung bei Zigbee2MQTT belegt nicht automatisch die vollständige Unterstützung durch ZHA – und umgekehrt. Für ZHA sind Geräte-Signatur, vorhandener Device Handler und aktuelle Erfahrungsberichte zur konkreten Kennung entscheidend.

4. Zertifizierung verifizieren

Werbeaussagen und Logos lassen sich über die Certified Products Search der Connectivity Standards Alliance gegenprüfen. Entscheidend ist der passende Endprodukteintrag, nicht nur die Zertifizierung des verbauten Funkmoduls oder einer zugrunde liegenden Plattform.

5. Rückgabemöglichkeit einplanen

Bei Geräten ohne klar dokumentierten Fingerprint bleibt ein Restrisiko. Gerade bei fest einzubauenden Schaltern sollte die Kompatibilität vor Ablauf der Rückgabefrist geprüft werden.

Fehlersuche nach dem Pairing

Wenn ein Gerät nur teilweise funktioniert, hilft ein geordnetes Vorgehen:

1. Modell-ID, Hersteller-ID, Firmwareangaben und Geräte-Signatur sichern.

2. Prüfen, welche Endpunkte, Entitäten oder Exposes tatsächlich erkannt wurden.

3. Gerät nahe am Koordinator erneut anlernen; ZHA empfiehlt bei fehlenden Entitäten auch ein erneutes Pairing.

4. Protokolle auf unbekannte Cluster, Befehle oder nicht definierte Data Points prüfen.

5. Nach der exakten Hersteller-ID in den offiziellen Repositories von ZHA Device Handlers beziehungsweise zigbee-herdsman-converters suchen.

6. Vor Änderungen an Konvertern, Quirks oder Firmware ein Backup der Zigbee- und Home-Assistant-Konfiguration anlegen.

Ein nicht unterstützter Datenpunkt sollte nicht durch Ausprobieren beliebiger Schreibwerte erforscht werden. Bei Rollladenmotoren, Thermostaten oder Schaltaktoren können falsche Befehle unerwünschte Bewegungen, Schaltzustände oder Grenzwerte auslösen. Zunächst sollte nur beobachtet und protokolliert werden.

Sicherheit bei Unterputzschaltern

Unterputzschalter arbeiten in der Regel an Netzspannung. Ein Zigbee-Koordinator, ein Quirk oder ein Node-RED-Flow ändert nichts an den Anforderungen der elektrischen Anlage. Auswahl, Einbau, Schutzmaßnahmen und Prüfung müssen zu Gerät, Last und Installation passen und nach den geltenden Herstellervorgaben sowie durch entsprechend qualifizierte Personen erfolgen.

Ein unverdrahteter Ausgang darf nicht automatisch als frei nutzbarer Szenentaster betrachtet werden. Ob ein Schalter einen entkoppelten beziehungsweise „Detached“-Betrieb unterstützt, ist eine Geräteeigenschaft. Fehlt diese Funktion, kann das Relais trotz Automatisierung physisch schalten. Vor der Nutzung muss deshalb das konkrete Verhalten des Geräts geprüft sein.

Fazit: Kompatibilität hängt an der konkreten Gerätekennung

Das Problem ist nicht „Tuya statt Zigbee 3.0“. Viele Tuya-Produkte basieren durchaus auf Zigbee 3.0, erweitern den Standard aber um herstellerspezifische Funktionen. Für offene Systeme zählt deshalb, ob ZHA oder Zigbee2MQTT genau diese Gerätevariante übersetzen kann.

Der BSEED-Fall zeigt den praktischen Unterschied: Unter ZHA ließen sich die Kanäle in unserer Installation nicht korrekt trennen; mit einer passenden Zigbee2MQTT-Unterstützung funktionierte es. Node-RED machte daraus zusätzlich eine virtuelle Wechselschaltung. Das ist eine brauchbare Lösung, solange ihre Abhängigkeit von Server, MQTT und Funknetz bewusst eingeplant wird.

Vor dem Kauf sind daher nicht das Zigbee-Logo oder die Modellbezeichnung auf der Shopseite entscheidend, sondern die exakten Geräte-Fingerprints und die dokumentierten Funktionen in der tatsächlich eingesetzten Zigbee-Software.

Quellen und technische Dokumentation

• Tuya: Zigbee Connection Standard for Smart Switch – Tuya-Dokumentation eines Schalters auf Basis des Zigbee-3.0-Standards.
• Tuya: Zigbee Generic Interfaces – Dokumentation des privaten Clusters 0xEF00.
• Zigbee2MQTT: Support new Tuya devices – Fingerprints, Data Points und gerätespezifisches Mapping.
• Zigbee2MQTT: Find Tuya Data Points – Ermittlung und Bedeutung von Tuya-DPIDs.
• Zigbee2MQTT: Supported devices – aktuelle Gerätedatenbank.
• Zigbee2MQTT: BSEED EC-GL86ZPCS21 – unterstützte Gerätekennung, getrennte Endpunkte und bereitgestellte Funktionen.
• Home Assistant: Zigbee Home Automation – Funktionsweise von ZHA und Vorgehen bei unvollständig unterstützten Geräten.
• Connectivity Standards Alliance: Certified Products Search – öffentliche Suche nach zertifizierten Endprodukten und Plattformen.
• Connectivity Standards Alliance: Certification Process – Anforderungen und Aussage der Produktzertifizierung.
• Node-RED: Dokumentation – Grundlagen zu Flows, Nachrichten und Nodes.

• Zigbee2MQTT-Issue: Aufnahme von _TZ3002_zjuvw9zf – ursprüngliche Gerätesignatur und Support-Verlauf.