Ich habe mir jetzt schon eine Weile angeschaut, wie man Tuya-Geräte sauber lokal in Home Assistant einbindet, und eine Weile lang war der Weg dazu wirklich nervig. Entwicklerkonto anlegen, Cloud-Projekt konfigurieren, API-Keys raussuchen, und irgendwann ist die Testphase abgelaufen und nichts geht mehr. Das kenne ich selbst, denn meine offizielle Tuya-Cloud-Integration ist irgendwann einfach abgeschmiert. Mittlerweile geht das alles deutlich einfacher, und ich zeige dir heute, wie du deine Tuya-Geräte komplett lokal mit tuya-local steuerst.
Der wichtigste Punkt zuerst
Wenn du schon mal nach einer Anleitung für lokale Tuya-Anbindung gesucht hast, bist du vermutlich auf den alten Weg gestoßen: Tuya IoT-Portal, Entwicklerkonto, Cloud-Projekt anlegen, Geräte manuell verknüpfen. Das war umständlich, und die Testphase ist irgendwann abgelaufen.
Das brauchst du heute nicht mehr. Die Integration holt sich die nötigen Schlüssel heute selbst. Ein Konto in der Smart-Life-App reicht, und das hast du ohnehin schon. Zum Einrichten braucht man die Cloud kurz, das lässt sich nicht umgehen, denn auf den Geräten liegen Schlüssel, die man ohne Konto nicht bekommt. Aber nach der Einrichtung läuft alles lokal, und die Cloud spielt keine Rolle mehr.
Noch was, das ich kurz klarstellen möchte: tuya-local schickt deine Schaltbefehle nicht mehr nach außen, aber die Geräte selbst melden ihren Status weiterhin an die Tuya-Cloud. Das ist kein Sicherheitsfeature, sondern eine Verbesserung in Sachen Geschwindigkeit, Zuverlässigkeit und Verfügbarkeit, auch wenn das Internet mal hängt.
Was du brauchst
Bevor wir anfangen, kurz die Voraussetzungen. Du brauchst eine Home Assistant-Instanz mit HACS bereits installiert. Falls HACS noch nicht eingerichtet ist, hol das zuerst nach, sonst kommen wir nicht weit.
Dazu brauchst du ein Tuya- oder Smart-Life-Konto, in dem deine Geräte bereits eingerichtet sind. Und natürlich müssen die Geräte im selben Netzwerk hängen wie Home Assistant, denn die lokale Kommunikation läuft direkt über dein Heimnetz. Wenn das alles passt, können wir loslegen.
Schritt 1: tuya-local über HACS installieren
Die Integration heißt tuya-local und kommt von make-all. In HACS suchst du einfach danach, klickst sie an und installierst sie wie jede andere HACS-Erweiterung auch. Wichtig: Danach startest du Home Assistant komplett neu. Nicht nur neu laden, wirklich neu starten. Sonst taucht die Integration beim Hinzufügen nicht auf, und dann sitzt du da und weißt nicht warum.
Schritt 2: Den Benutzercode aus der App holen
Öffne die Smart-Life-App oder die Tuya-Smart-App auf deinem Smartphone. Beide funktionieren genauso, der Weg ist identisch. Unten rechts gehst du auf Profil, dann oben rechts auf das Zahnrad. Dort findest du Konto und Sicherheit, und ganz unten in der Liste steht Benutzercode. Sieben Zeichen, Groß- und Kleinschreibung zählt. Den kopierst du dir irgendwo rein, danach kannst du das Handy erstmal weglegen.
In der englischen App läuft der Weg über Settings, Account and Security, User Code. Das Prinzip ist dasselbe.
Schritt 3: Das Gerät in Home Assistant hinzufügen
In Home Assistant gehst du unter Einstellungen auf Geräte und Dienste, dann auf Integration hinzufügen, und suchst dort nach Tuya Local. Im Dialog wählst du die cloud-gestützte Geräteeinrichtung, gibst deinen Benutzercode ein, und bekommst dann einen QR-Code angezeigt. Den scannst du mit deinem Smartphone ein, bestätigst die Anmeldung in der App, und dann passiert das eigentlich Schöne: Du bekommst die Liste deiner Geräte aus dem Konto angezeigt.
Das ist der Teil, der früher richtig nervig war. Device ID, Local Key, IP-Adresse, alles musste man mühsam von Hand raussuchen. Heute füllt die Integration das alles automatisch aus, du wählst einfach dein Gerät aus der Liste und drückst auf weiter. Du kannst direkt mehrere Geräte hintereinander hinzufügen, ohne dich jedes Mal neu anzumelden.
Ein Detail noch, das gern für Verwirrung sorgt: Das Cloud-Token gilt nur ein paar Stunden und wird danach nicht gespeichert. Das ist kein Bug, das ist so gewollt. Nach der Einrichtung läuft alles lokal, die Cloud wird wirklich nur einmalig zum Abholen der Schlüssel gebraucht.
Schritt 4: Protokollversion prüfen
Die Integration erkennt die Protokollversion normalerweise selbst. Zur Auswahl stehen die Versionen 3.1 bis 3.5 sowie 3.22, und in den meisten Fällen muss man da gar nichts anfassen.
Trotzdem gibt es hier eine Falle, die ich kurz erwähnen möchte. Bei Protokoll 3.1 wird der Local Key nur zum Senden von Befehlen genutzt. Ist der Schlüssel falsch, sieht die Einrichtung trotzdem erfolgreich aus, und du merkst es erst, wenn du das Gerät schalten willst und nichts passiert. Bei neueren Protokollversionen fällt ein falscher Schlüssel sofort auf, weil auch die empfangenen Daten damit entschlüsselt werden. Also: Wenn nach der Einrichtung gar nichts passiert, lohnt sich ein Blick auf die Protokollversion.
Was lokal nicht funktioniert
Diesen Teil lassen die meisten Anleitungen einfach weg, und er ist der Grund für viele verlorene Abende. Deswegen schauen wir uns das kurz an.
Batteriebetriebene Geräte wie Türsensoren, Fensterkontakte und Rauchmelder lassen sich lokal nicht einbinden. Die schlafen die meiste Zeit und melden sich nur kurz bei der Cloud, wenn etwas passiert. Für diese Geräte bleibt nur die offizielle Cloud-Integration.
Nur eine lokale Verbindung gleichzeitig. Viele Tuya-Geräte akzeptieren nur eine einzige lokale Verbindung auf einmal. Wenn parallel noch die offizielle Tuya-Integration läuft oder die App aktiv zugreift, kämpfen beide um denselben Kanal und die Verbindung bricht ständig ab. Entscheide dich also pro Gerät für einen Weg. Bei mir läuft der Sternlichtprojektor noch parallel in der App und in Home Assistant, aber das ist nicht bei jedem Gerät so entspannt.
Geräte an einem Hub. Zigbee-Geräte, die über einen Tuya-Hub laufen, werden nur eingeschränkt unterstützt. Ein Hub schafft typischerweise ein bis drei gleichzeitige Verbindungen zu Untergeräten. Wenn du viele davon hast, ist ein eigener Zigbee-Koordinator die deutlich bessere Lösung.
Befehle in schneller Folge. Viele Tuya-Geräte kommen nicht damit klar, wenn mehrere Befehle direkt hintereinander eintreffen. In Automationen also kleine Verzögerungen einbauen, sonst kommt nur der erste Befehl an. Die Lösung ist ein kurzes Delay zwischen den Befehlen. 400 Millisekunden reichen meistens völlig aus, und das merkt man im Alltag nicht:
1- service: light.turn_on
2 target:
3 entity_id: light.sternprojektor
4- delay:
5 milliseconds: 400
6- service: light.turn_on
7 target:
8 entity_id: light.sternprojektor_laserDas gleiche Problem tritt übrigens auch bei anderen Integrationen auf, zum Beispiel bei Philips Hue. Wenn dir dort mal Befehle verloren gehen, kennst du jetzt die Lösung.
Tipps und Troubleshooting
Nach dem erneuten Koppeln geht nichts mehr. Der Local Key ändert sich, sobald du ein Gerät neu mit der App koppelst. Dann musst du es in Home Assistant erneut hinzufügen und den neuen Schlüssel abholen. Das passiert nicht oft, aber wenn es passiert, weiß man erstmal nicht warum.
Das Gerät wird nicht gefunden. Die automatische Erkennung braucht, dass Home Assistant und das Gerät im selben Netzsegment liegen. Wenn du ein separates IoT-VLAN betreibst, musst du die IP-Adresse von Hand eintragen. Andernfalls findet die Integration das Gerät schlicht nicht.
Wackelige Verbindung. Das ist fast immer der Konflikt, den ich oben beschrieben habe. Prüf zuerst, ob dasselbe Gerät noch in der offiziellen Tuya-Integration hängt, und wirf es dort raus. In den meisten Fällen löst das das Problem sofort.
Ich habe das Ganze selbst eingerichtet und bin wirklich überrascht, wie unkompliziert der Weg heute ist. Früher war das eine echte Geduldsprobe, heute dauert die Einrichtung ein paar Minuten. Nutzt du tuya-local schon, oder setzt du auf einen anderen Weg für deine Tuya-Geräte? Schreib's gerne in die Kommentare.
