Viele günstige Smart-Home-Geräte (Lampen, Steckdosen, Lüfter, Leisten) laufen auf der Tuya-Plattform und werden über die Smart-Life- oder Tuya-Smart-App gesteuert. In Home Assistant lassen sie sich auf zwei Wegen einbinden: über die Tuya-Cloud oder lokal im eigenen WLAN. In diesem Beitrag erfährst du, was LocalTuya ist, wie die Einrichtung grundsätzlich abläuft und welche Stolperfallen es gibt.

Cloud oder lokal: Was ist der Unterschied?

Die offizielle Tuya-Integration in Home Assistant steuert deine Geräte über die Server von Tuya. Das ist einfach einzurichten, aber du bist vom Internet und vom Dienst abhängig, und Befehle brauchen oft etwas länger.

LocalTuya spricht dagegen direkt mit dem Gerät im lokalen Netzwerk. Das ist schneller und funktioniert auch bei Internetausfall. Die Cloud wird laut Projektbeschreibung nur beim Start und bei einem nötigen Update des local_key angefragt.

Beide Integrationen können parallel laufen. Das ist praktisch, denn so hast du die Cloud-Variante als Rückfall, falls ein Gerät lokal mal nicht erreichbar ist.

Was brauchst du?

• Home Assistant mit installiertem HACS (der Community-Store für Zusatzintegrationen)
• Die Geräte sind in der Smart-Life- oder Tuya-App eingerichtet und funktionieren dort
• Ein kostenloses Konto auf der Tuya IoT Platform (iot.tuya.com) mit einem Cloud-Projekt, um die Zugangsdaten und die Geräteschlüssel abzufragen
• Die Geräte im selben Netzwerk wie Home Assistant

Welche LocalTuya-Version?

Das ursprüngliche LocalTuya-Projekt wird kaum noch weiterentwickelt. Neuere Geräte nutzen teils das Protokoll 3.5, und das beherrscht die ursprüngliche Version nicht. Viele nutzen deshalb den Fork von xZetsubou (Repository: github.com/xZetsubou/hass-localtuya), der Protokoll 3.5 unterstützt. Installation über HACS: Menü oben rechts, Benutzerdefinierte Repositories, Adresse eintragen, Kategorie Integration wählen und installieren. Danach Home Assistant neu starten.

Einrichtung in Kurzform

1. LocalTuya unter Einstellungen > Geräte & Dienste > Integration hinzufügen hinzufügen.
2. Die Zugangsdaten deines Tuya-IoT-Projekts (Client ID und Secret) eintragen.
3. Die Geräte werden anschließend aufgelistet. Pro Gerät brauchst du die Geräte-ID, die IP-Adresse und den local_key.
4. Protokollversion wählen (3.3, 3.4 oder 3.5) und die Entities (Schalter, Licht, Sensor) zuordnen.
5. Geräte einen aussagekräftigen Namen geben, bevor du sie in Automationen oder bei Alexa verwendest.

Häufige Fehler

• Falscher Schlüssel: Der „Secret“ des Cloud-Projekts ist nicht der local_key. Das ist einer der häufigsten Fehler. Der local_key gehört zum einzelnen Gerät.
• local_key ändert sich: Wenn du ein Gerät neu koppelst (zum Beispiel nach einem Reset), bekommt es einen neuen Schlüssel. Dann muss der Eintrag in LocalTuya aktualisiert werden.
• Falsche Protokollversion: Eine falsche Version und ein falscher Schlüssel sehen im Fehlerbild ähnlich aus. Probiere bei Verbindungsfehlern zuerst die anderen Versionen durch.
• IP-Adresse ändert sich: Vergib den Geräten in deinem Router feste IP-Adressen (DHCP-Reservierung). Sonst findet LocalTuya sie nach einer Weile nicht mehr.
• Eine Verbindung gleichzeitig: Viele Tuya-Geräte nehmen nur wenige lokale Verbindungen an. Wenn ein anderes Programm (z. B. ein Test-Tool) gerade verbunden ist, kann es zu Verbindungsabbrüchen kommen.
• Updates: Nach größeren Home-Assistant-Updates kurz prüfen, ob die Geräte noch erreichbar sind und im Log keine Fehler von LocalTuya stehen.

Gibt es eine Alternative?

Ja: Tuya Local (github.com/make-all/tuya-local) ist eine weitere HACS-Integration, die Geräte anhand vorgefertigter Profile einrichtet. Das spart Arbeit bei der Zuordnung der Datenpunkte, wenn dein Gerät dort bereits unterstützt wird. Welche Lösung besser passt, hängt vom Gerät ab.

Tipps für den Alltag

• Lege Cloud-Entities und lokale Entities nicht durcheinander: Benenne beide klar (zum Beispiel „Vitrine“ und „Vitrine Cloud“).
• Wenn du Alexa oder Google Assistant nutzt, gib vor der Geräteerkennung nur die lokalen Entities frei.
• Mach vor größeren Umstellungen ein Backup.

Frage im Forum

Wenn bei dir etwas nicht klappt, schreib hier ein neues Thema und nenne bitte:

• die Home-Assistant-Version und die LocalTuya-Version (Original oder Fork)
• den Gerätetyp und die Protokollversion
• die Fehlermeldung aus dem Log (bitte als Text)

Schlüssel, Secrets und Zugangsdaten bitte vor dem Posten entfernen.