tuya2mqtt – Wilkware

tuya2mqtt ist eine Brücke zwischen Tuya-Geräten und MQTT. Tuya-Technik steckt in unzähligen Steckdosen, Leuchten, Ventilatoren oder Saugrobotern, die unter vielen verschiedenen Marken verkauft werden. tuya2mqtt übersetzt das Tuya-Protokoll in einfache MQTT-Topics, sodass sich diese Geräte direkt im eigenen Netz abfragen und steuern lassen, ganz ohne Tuya-Cloud.

In Symcon setzt die Bibliothek Local Tuya auf tuya2mqtt auf.

Die Funktionen im Überblick

Lokale Steuerung: Kommunikation direkt mit dem Gerät, ohne Umweg über die Cloud
Automatische Erkennung: Gerät und Protokollversion werden im selben Subnetz selbst gefunden, IP und Version lassen sich aber auch fest vorgeben
DPS-Topics: Zugriff auf alle Datenpunkte eines Geräts, wahlweise als Tuya-JSON oder als einzelne Werte
Friendly Topics: Geräte-Templates bilden die Datenpunkte auf verständliche Topics ab, auch über Geräte mit unterschiedlicher Belegung hinweg
Statusmeldungen: Online-Status pro Gerät und für die Brücke selbst (per MQTT Last Will), jeweils mit Retain-Flag
Betrieb als Dienst oder Container: systemd-Unit und fertiges Docker-Image für amd64, arm64 und arm/v7 (z. B. Raspberry Pi)

Voraussetzungen

Node.js ab Version 18 oder Docker
ein MQTT-Broker
Device-ID und lokaler Schlüssel (Local Key) jedes Geräts

Die Schlüssel zu beschaffen gehört nicht zum Umfang des Projekts. Dafür braucht man ein Tuya-IoT-Entwicklerkonto oder eine der alternativen Methoden, die das TuyAPI-Projekt beschreibt. Ein guter Test vorab: Lässt sich ein Gerät mit tuya-cli auslesen und schalten, funktioniert es auch mit tuya2mqtt.

Installation

Als systemd-Dienst

cd /opt
git clone https://github.com/wilkware/tuya2mqtt
cd tuya2mqtt
npm install

sudo cp ./docs/tuya2mqtt.service /etc/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable tuya2mqtt.service
sudo systemctl start tuya2mqtt.service

Mit Docker

Bei jeder neuen Version wird ein Image gebaut und veröffentlicht. Die Konfiguration bleibt außerhalb des Containers und wird nur lesbar eingebunden:

services:
  tuya2mqtt:
    image: ghcr.io/wilkware/tuya2mqtt:latest
    container_name: tuya2mqtt
    restart: unless-stopped
    environment:
      - CONFIG_DIR=/config
    volumes:
      - /opt/services/tuya2mqtt:/config:ro

Der Container läuft als Benutzer node (UID 1000), die Konfigurationsdateien müssen für ihn lesbar sein. Wichtig: Im Container zeigt localhost nicht auf den Host. Der MQTT-Broker wird deshalb mit seiner IP-Adresse oder seinem Containernamen angesprochen.

Konfiguration

tuya2mqtt nutzt zwei Dateien. Die config.json enthält die Verbindung zum MQTT-Broker:

Option	Beschreibung	Standard
`host`	Adresse des MQTT-Brokers	–
`port`	Port des MQTT-Brokers	–
`topic`	Basis-Topic, auch mehrstufig, z. B. `home/tuya/`	`tuya2mqtt/`
`mqtt_user`	Benutzername für den Broker	–
`mqtt_pass`	Passwort für den Broker	–
`qos`	QoS-Level für alle Nachrichten	`1`
`retain`	Zustands-Topics mit Retain-Flag senden	`false`

Die devices.conf im JSON5-Format listet die Geräte auf. Sie hat dasselbe Format wie die Ausgabe von tuya-cli wizard und lässt sich daher direkt übernehmen:

[
  {
    name: 'Tuya Device 1',
    id: '86435357d8b123456789',
    key: '8b2a69c9876543210'
  }
]

Optional lassen sich pro Gerät ip und version (3.4 oder 3.5) festlegen, zum Beispiel wenn die Geräte in einem anderen Subnetz liegen. Wie Gerätetypen und eigene Templates angelegt werden, beschreibt die Geräte-Dokumentation .

So sehen die Topics aus

Die oberste Ebene bildet der Gerätename in Kleinbuchstaben, Leerzeichen werden zu Unterstrichen. Ohne Namen wird die Geräte-ID verwendet.

tuya/kitchen_table/status          --> online/offline
tuya/bridge/status                 --> online/offline
tuya/kitchen_table/command         <-- get-states
tuya/dimmer_device/DPS/1/state     --> true/false
tuya/dimmer_device/DPS/2/command   <-- 1–255

Mit get-states meldet ein Gerät sofort alle bekannten Werte. Werte, die direkt an DPS-Topics gesendet werden, prüft tuya2mqtt nicht. Falsche Typen oder Bereiche können ein Gerät zum Neustart bringen, deshalb sind die Friendly Topics mit Template die bessere Wahl.

tuya2mqtt ist aus dem Projekt tuya-mqtt von TheAgentK hervorgegangen, inzwischen aber stark überarbeitet. Die Kommunikation mit den Geräten übernimmt TuyAPI . tuya2mqtt steht unter der MIT-Lizenz .