Ich habe vor einer Weile ein Video darüber gemacht, wie man Tuya-Geräte lokal in Home Assistant einbindet, also komplett ohne Tuya-Cloud. Danach kamen so viele Kommentare mit denselben Problemen, dass ich die acht häufigsten Fehlerquellen hier noch mal sauber zusammenfasse. Bei einigen gibt es eine einfache Lösung, bei anderen ist die ehrliche Antwort: Das wird so nicht funktionieren.
Die falsche Integration erwischt
Im HACS-Store gibt es zwei verschiedene lokale Tuya-Integrationen, die auf den ersten Blick ähnlich aussehen. Einmal die make-all/tuya-local Integration und einmal die von rospogrigio/localtuya. Wer einfach im HACS-Store nach "Tuya" sucht, bekommt standardmäßig die zweite angezeigt, weil sie mehr GitHub-Sterne hat.
Das klingt erstmal nach einem guten Zeichen, ist es aber nicht. Wenn du dir die offenen Issues bei beiden anschaust, sieht man den Unterschied relativ schnell. Die make-all-Integration hat deutlich weniger offene Probleme, wird aktiv gepflegt und ist die, die ich empfehle.
Damit sie im HACS-Store auftaucht, musst du sie erst als benutzerdefiniertes Repository hinzufügen. Dafür gehst du im HACS-Store auf die drei Punkte oben rechts, dann auf "Benutzerdefinierte Repositories", trägst die URL des Repositories ein, wählst als Typ "Integration" und klickst auf Hinzufügen. Danach taucht sie in der Liste auf und du kannst sie wie gewohnt installieren.
Die Tuya-App läuft noch im Hintergrund
Das ist ein Klassiker. Du startest das lokale Setup, Home Assistant findet das Gerät nicht oder das Koppeln schlägt fehl, obwohl alles eigentlich stimmen müsste. Der Grund ist oft, dass die Tuya-App auf deinem Smartphone noch geöffnet ist und aktiv mit dem Gerät kommuniziert.
Viele Tuya-Geräte unterstützen nur eine einzige lokale Verbindung gleichzeitig. Wenn die App diese Verbindung belegt, kommt Home Assistant nicht ran. Schließ die App also vollständig, bevor du das Setup startest, oder nimm dein Smartphone kurz aus dem WLAN. Danach sollte das Koppeln problemlos klappen.
Die Fehlermeldung mit der IP-Adresse
Wer die Integration auf Deutsch betreibt, sieht manchmal diese Meldung: "Die Tuya Cloud stellt keine lokalen IP-Adressen bereit." Das klingt nach einem echten Fehler, ist aber eigentlich eine schlechte Übersetzung.
Im Englischen steht da sinngemäß: Die IP-Adresse konnte nicht automatisch ermittelt werden, bitte warte 20 Sekunden und trag sie danach manuell ein. Das ist der entscheidende Hinweis, der in der deutschen Version fehlt. Lass dich also nicht davon abbringen. Schau einfach in deiner Fritz!Box oder in deinem Router nach, welche IP-Adresse das Gerät bekommen hat, und trag sie manuell ein.
Gerät von Hand eintragen
Wenn die automatische Erkennung nicht klappt, kannst du das Gerät manuell hinzufügen. Dafür brauchst du die IP-Adresse des Geräts aus deinem Router, die Geräte-ID und den lokalen Schlüssel.
Beides bekommst du entweder aus dem Tuya-Entwicklerportal, falls du dort schon ein Konto hast, oder direkt aus der Tuya- oder Smart-Life-App in den Gerätedetails. Die DEVICE_DETAILS.md im Repository erklärt Schritt für Schritt, wo du diese Informationen findest.
Das Entwicklerkonto ist abgelaufen
Wer Tuya-Geräte früher über das offizielle Tuya-Entwicklerportal eingebunden hat, kennt dieses Problem. Die App, die man dort für den lokalen Zugriff anlegt, hat ein Ablaufdatum, solange sie nicht als offizielle App veröffentlicht wird. Irgendwann hört sie auf zu funktionieren.
Die gute Nachricht: Die make-all/tuya-local Integration braucht das Entwicklerkonto überhaupt nicht. Du kannst diesen Fehler also komplett ignorieren, wenn du auf den neuen Weg wechselst.
Der Gerätetyp wird nicht erkannt
Beim Hinzufügen versucht die Integration automatisch zu erkennen, um welchen Gerätetyp es sich handelt. Das klappt nicht immer, weil es einfach wahnsinnig viele verschiedene Tuya-Geräte gibt und die Liste nicht nach Marken, sondern nach Gerätekonfigurationen aufgebaut ist.
Wenn die automatische Erkennung fehlschlägt, musst du den Typ von Hand auswählen. Das Repository gibt dazu eine klare Empfehlung: Bei Geräten mit Verbrauchsmessung probierst du die verschiedenen Smartplug-Varianten durch. Für alles andere startest du mit "Simple Switch". Wenn keiner davon passt, schaust du dir die Liste der unterstützten Geräte an und probierst dich durch die Typen, die inhaltlich passen könnten.
Nicht unterstützte Geräte melden
Wenn dein Gerät in keiner der vorhandenen Kategorien landet, kann der Entwickler nur dann helfen, wenn du ihm die Geräteinformationen zur Verfügung stellst. Das machst du, indem du ein neues Issue im Repository öffnest und dort alles einträgst, was du über das Gerät weißt: Modell, Geräte-ID, die DPS-Datenpunkte aus der App und was das Gerät können soll. Je mehr Informationen, desto besser die Chance, dass der Gerätetyp irgendwann offiziell unterstützt wird.
Batteriebetriebene Geräte funktionieren grundsätzlich nicht lokal
Das ist leider einer der Fälle, bei denen es keine Lösung gibt. Batteriebetriebene Tuya-Geräte, also zum Beispiel Türsensoren oder Temperaturfühler auf Batterie, schalten sich zwischen den Übertragungen komplett ab, um Energie zu sparen. Eine dauerhafte lokale Verbindung ist damit nicht möglich, und genau das braucht die Integration.
Wenn dein Gerät allerdings auch über Zigbee kommuniziert, gibt es einen anderen Weg. Über Zigbee2MQTT kannst du solche Geräte dann trotzdem lokal in Home Assistant einbinden, ohne auf die Tuya-Cloud angewiesen zu sein. Das lohnt sich auf jeden Fall zu prüfen, bevor du das Gerät abschreibst.
Geräte nicht aus der App löschen
Zum Schluss noch ein Punkt, den man leicht übersieht: Lösche deine Tuya-Geräte nicht aus der Smart-Life- oder Tuya-App, nachdem du sie lokal in Home Assistant eingebunden hast. Beim lokalen Setup wird der Schlüssel des Geräts an Home Assistant übergeben. Wenn du das Gerät in der App löschst, wird dieser Schlüssel ungültig und die lokale Verbindung funktioniert nicht mehr. Also einfach in Ruhe lassen und alles bleibt stabil.
Hast du beim Einrichten von Tuya Local noch einen anderen Fehler erlebt, der hier nicht auftaucht? Schreib ihn gerne in die Kommentare, dann können alle davon profitieren.
