====== TinyTuya Plugin ====== ++++ Version History... | [[https://github.com/mschlenstedt/LoxBerry-Plugin-TinyTuya/releases]] ++++ ---- ===== Funktion des Plugins ===== Das Plugin bindet Tuya kompatible%% WiFi Smart Devices (z.B. Steckdosen, Lights, Wärmepumpen, etc.) über das LAN%% an Loxone an. Es können Statusdaten aus den Devices ausgelesen werden als auch Befehle an die Geräte gesendet werden. Alles, was mit der %%Smart Life App gesteuert und ausgelesen werden kann, kann auch mit dem Plugin verarbeitet werden.%% Zur Einrichtung muss euer Gerät in der Tuya Cloud registriert sein, die Kommunikation zwischen Plugin und den Geräten erfolgt später aber rein lokal ohne die Cloud. Das Plugin nutzt die Software [[https://github.com/jasonacox/tinytuya]] zur Anbindung. ===== Installation ===== Das Plugin wird ganz normal über die Pluginschnittstelle installiert. **Auf LoxBerry V2.x ist zwingend das MQTT Gateway Plugin notwendig**. LoxBerry 3.x hat dieses bereits an Bord - hier sind keine weiteren Voraussetzungen notwendig. ===== Vorbereitungen ===== Um eure Devices später mit dem Plugin nutzen zu können, müssen sie zunächst mit Deinem Tuya Cloud Account verbunden und eingerichtet werden. Anschließend benötigst Du einen Developer-Zugang bei Tuya (kostenlos), damit Du Zugriff auf die Tuya API bekommst. Erst dann kannst Du die Devices über das Plugin abrufen und steuern. Die Kommunikation zwischen Plugin und Devices erfolgt dabei rein lokal - lediglich für die Ersteinrichtung ist die Einrichtung in der Tuya-Cloud notwendig. === Pairing der Devices === Zum Pairing mit Deinem Cloudaccount gehe bitte nach der Anleitung vom Hersteller vor. Je nach Gerät ist der Vorgang etwas anders. Du benötigt die "Smart Life" App von Tuya auf dem Handy. Anschließend bringst Du die Geräte in den Pairing Modus. === API Zugang einrichten === == Beschränkte Gültigkeit == Euer kostenloser API Key läuft jeweils nach **einem Monat** ab und muss dann erneuert werden. Ohne gültigen API-Key könnt ihr die EInstellungen im Plugin nicht abspeichern! Bitte stellt also sicher, dass euer API-Key immer gültig ist, sobald ihr die Einstellungen des Plugins speichern/ändern wollt! Zur Erneuerung der API Services geht in euren Tuya-Account auf ''Cloud --> --> Service API'' und klickt dort bei jedem Service auf "View Details" und erneuert euren Zugang für 6 Monate. Die Erneuerung dauert normalerweise einen Arbeitstag. Für den täglichen lokalen Betrieb benötigt ihr keinen API Key! NUr wenn ihr die Konfiguration speichern wollt (z. B. wenn ihr neue Geräte hinzufügen wollt) ist der API Key nötig! Nachdem Du die Devices mit Deinem Cloudzugang und Handy verbunden hast, kannst Du Dir Deinen API-Zugang einrichten. Das ist etwas kompliziert - muss aber nur einmal durchgeführt werden. Die Original-Anleitung findest Du hier: [[https://github.com/jasonacox/tinytuya]] == Data Center == Du siehst Deine Geräte in Deinem Tuya Developer Account nur, wenn Du das korrekte Data Center auswählst. Das dürfte meist "Central Europe Datacenter" sein (und nicht "Western Europe"). HIer findest Du eine gesamte Übersicht, welches Land zu welchem Data Cente rzugeordnet ist: [[https://developer.tuya.com/en/docs/iot/oem-app-data-center-distributed?id=Kafi0ku9l07qb]] TUYA ACCOUNT - Set up a Tuya Account (see%% %%[[https://github.com/jasonacox/tinytuya/files/8145832/Tuya.IoT.API.Setup.pdf|PDF Instructions]]): * //NOTE: Tuya often changes their portal and services. Please open an%% %%[[https://github.com/jasonacox/tinytuya/issues|issue]]%% %%with screenshots if we need to update these instructions.// * Create a Tuya Developer account on%% %%[[https://iot.tuya.com|iot.tuya.com]]. When it asks for the "Account Type", select "Skip this step..." (see%% %%[[https://user-images.githubusercontent.com/836718/213877860-34c39851-5671-4c9f-b4d5-251873f18c77.png|screenshot]]). * Click on "Cloud" icon -> "Create Cloud Project" - Remember the "Data Center" you select. This will be used by TinyTuya Wizard ([[https://user-images.githubusercontent.com/836718/138598647-c9657e49-1a89-4ed6-8105-ceee95d9513f.png|screenshot]]). - Skip the configuration wizard but remember the Authorization Key:%% %%//API ID//%% %%and%% %%//Secret//%% %%for below ([[https://user-images.githubusercontent.com/836718/138598788-f74d2fe8-57fa-439c-8003-18735a44e7e5.png|screenshot]]). * Click on "Cloud" icon -> Select your project ->%% %%**Devices**%% %%->%% %%**Link Tuya App Account**%% %%(see [[https://user-images.githubusercontent.com/836718/155827671-44d5fce4-0119-4d0e-a224-ef3715fafc24.png|screenshot]]) * Click%% %%**Add App Account**%% %%([[https://user-images.githubusercontent.com/836718/155827671-44d5fce4-0119-4d0e-a224-ef3715fafc24.png|screenshot]]) and it will display a QR code. Scan the QR code with the%% %%//Smart Life app//%% %%on your Phone (see step 1 above) by going to the "Me" tab in the%% %%//Smart Life app//%% %%and clicking on the QR code button%% %%''[-]''%% %%in the upper right hand corner of the app. When you scan the QR code, it will link all of the devices registered in your%% %%//Smart Life app//%% %%into your Tuya IoT project. * **NO DEVICES?**%% %%If no devices show up after scanning the QR code, you will need to select a different data center and edit your project (or create a new one) until you see your paired devices from the%% %%//Smart Life App//%% %%show up. ([[https://user-images.githubusercontent.com/35581194/148679597-391adecb-a271-453b-90c0-c64cdfad42e4.png|screenshot]]). The data center may not be the most logical. As an example, some in the UK have reported needing to select "Central Europe" instead of "Western Europe". * **SERVICE API:**%% %%Under "Service API" ensure these APIs are listed:%% %%''IoT Core'',%% %%''Authorization''%% %%and%% %%''Smart Home Scene Linkage''. To be sure, click subscribe again on every service. Very important:%% %%**disable popup blockers**%% %%otherwise subscribing won't work without providing any indication of a failure. Make sure you authorize your Project to use those APIs: * Click "Service API" tab * Click "**Go to Authorize**" button * Select the API Groups from the dropdown and click%% %%''Subscribe''%% %%([[https://user-images.githubusercontent.com/38729644/128742724-9ed42673-7765-4e21-94c8-76022de8937a.png|screenshot]]) Bei Tuya hat jeder Sensor oder Aktor in Deinem Gerät eine eindeutige ID (die sogenannte DPS oder DP ID - DP steht für Datapoint). Das sind willkürliche Nummern, der Ein/Aus Switch meiner Wärmepumpe hat zum Beispiel die DPS 1. Damit die Einbindung in Loxone später leichter wird, holt sich das Plugin vom Tuya-Server die passende Übersetzung dieser Data Points - so wird aus der 1 bei meiner Wärmepumpe dann "Power". Der Zugriff auf die Übersetzungstabellen (Mapping) in der Tuya Cloud muss teilweise extra für jedes Gerät aktiviert werden. **Die Aktivierung kann bis zu 12-24h Stunden dauern**! Solltest Du im Webserver oder MQTT Gateway keine Übersetzungen finden, dann speichere einfach die Einstellungen in der Pluginoberfläche nach 24h erneut. Dabei versucht das Plugin automatisch, sich die neuesten Übersetzungen herunterzuladen. Das Mapping aktivierst Du wie folgt - Die Original-Anleitung findest Du hier: [[https://github.com/jasonacox/tinytuya/blob/master/DP_Mapping.md|https://github.com/jasonacox/tinytuya/blob/master/DP_Mapping.md]] **How to get the full DPS mapping from Tuya Cloud.** This how-to will show you how to activate “DP Instruction” mode for your Tuya devices when using Tuya Cloud to pull data. This will result in getting the full list of DPS values and their properties for your devices. * Step 1 - Log in to your account on [[https://iot.tuya.com|iot.tuya.com]] * Step 2 - Navigate to "Cloud" -> "Development" then select your project. * Step 3 - Select "Devices" tab. (see [[https://user-images.githubusercontent.com/836718/218344965-8f6cd378-d8fd-4e46-b35e-5e2ba2d3a9d4.png|screenshot]]) * Step 4- Select the device types and click the the "pencil icon" to edit. (see [[https://user-images.githubusercontent.com/836718/218361449-f8c03832-8be3-4b25-b2cd-223dc2c89923.png|screenshot]]) * Step 5 - Select the "DP Instruction" box and "Save Configuration" (see [[https://user-images.githubusercontent.com/836718/218344985-41183289-ee0e-4484-aa8d-7489fc3a9f15.png|screenshot]]) There doesn't appear to be a way to globally set "DP Instruction" for all device types. You will need to select each device type and repeat the above step. ===== Konfigurationsoptionen ===== Auf der Plugin Hauptseite musst Du die API Daten aus Deinem Tuya Developer Account eingeben und zusätzlich noch eine beliebige DeviceID aus Deinem Account. Alle Angaben müssen denen aus dem Account entsprechen. Im Reiter "MQTT" kannst Du das MQTT Topic anpassen, wenn Du möchtest. Zusätzlich kannst Du noch die Polling Time festlegen. Diese gibt an, in welchem Zyklus die Statusdaten aus Deinen Geräten ausgelesen werden. Achtung! Gehe hier mit Bedacht vor - jede Abfrage erzeugt eine Last auf dem LoxBerry und vor allem im Gerät! {{plugins:tinytuya:pasted:20230612-125424.png?600}} Wenn Du keine Daten im MQTT Gateway bekommst, schaue als erstes in das "Wizard"-Logfile, es enthält den Scan nach Devices in Deinem Netzwerk und alle Logeinträge zum Versuch mit Deinem Gerät zu kommunizieren. == Achtung! == Das Plugin stellt bei jeder Abfrage eine Verbindung zu Deinen Geräten her. Die Tuya-Geräte können nur eine Verbindung zur gleichen Zeit verarbeiten. Verwende also nach Möglichkeit die TuyaApp nicht mehr, ansonsten kann es zu Problemen kommen. ===== TinyTuya WebUI ===== Das Plugin nutzt einen Server, den das TinyTuya Projekt mitliefert. Dieser wird mit installiert und im Hintergrund für sämtliche Aktionen des Plugins verwendet. Der Server eignet sich auch hervorragend für die Fehlersuche oder als guten Überblick, welche Geräte erkannt wurden. Auch könnt ihr direkt zum Testen hier die einzelnen Werte der Geräte auslesen und auch setzen. Ihr erreicht den Server über die Menüleiste oben im Plugin. {{plugins:tinytuya:pasted:20230612-132255.png}} {{plugins:tinytuya:pasted:20230612-132107.png}} ===== Einrichtung in der Loxone Config Software ===== === Messwerte auslesen/verwenden === Das Plugin sendet alle ausgelesenen Messwerte per MQTT an den MQTT Broker bzw. das [[konfiguration:widget_help:widget_mqtt:|MQTT Gateway]]. Im Gateway muss das Topic des Plugins abonniert werden (standardmäßig lautet das Topic "tinytuya/#") - das wird aber automatisch vom Plugin gemacht. Bitte lest in der Dokumentation des [[konfiguration:widget_help:widget_mqtt:|MQTT Widget]] nach, wie genau die Werte in der Loxone Config verwendet werden: [[konfiguration:widget_help:widget_mqtt:mqtt_gateway:mqtt_schritt_fur_schritt_mqtt_loxone|MQTT - Schritt für Schritt: MQTT -> Loxone]] Ich behandele das Thema "Anlegen eines Virtuellen Eingangs" hier nur in Kürze: * Virtuellen Eingang anlegen * Bezeichnung aus der Incoming Overview des Gateway kopieren und im Virtuellen Eingang exakt so einfügen.  * Als Digitaleingang verwenden: NEIN * Validierung korrekt setzen. === Geräte steuern - per MQTT - Default === Befehle (Werte setzen) können an die Geräte über das Topic **''%%tinytuya/set//%%''** gesendet werden. Dazu muss für das [[konfiguration:widget_help:widget_mqtt:|MQTT Gateway]] ein Virtueller Ausgang angelegt werden. Bitte lest in der Dokumentation des  [[[konfiguration:widget_help:widget_mqtt:|MQTT Gateway]] nach, wie genau die Werte in der Loxone Config verwendet werden: [[konfiguration:widget_help:widget_mqtt:mqtt_gateway:mqtt_schritt_fur_schritt_loxone_mqtt|MQTT - Schritt für Schritt: Loxone -> MQTT]] Die notwendige DeviceID und den Datapoint könnt ihr aus den MQTT Topics des Gerätes auslesen. Auch die Datapoints findet ihr im Topic "status_raw" des Gerätes. Alternativ könnt ihr auch die Namen der Geräte anstelle der Device IDs verwenden (darauf achten, dass in der Cloud jedes Gerät einen individuellen Namen hat!) und anstelle der numerischen Datapoints auch deren Namen (im Topic "status" anstelle "status_raw). {{plugins:tinytuya:pasted:20230612-130657.png?500}} Beispiel meiner Wärmepumpe - der Ein/Aus Switch meiner Wärmepumpe ist Datapoint 1, der Datapoint-Name ist "Power", die DeviceID ist a1234567890b, der Gerätename ist "pool heat pump, der Schalter kann den Wert "true" oder "false" haben. Folgende beide Befehle schalten die Wärmepumpe ein: **''%%tinytuya/set/a1234567890b/1%%''** **''true''** **''%%tinytuya/set/pool heat pump/Power%%''** **''true''** Ich behandele das Thema "Anlegen eines Virtuellen Ausgangs" hier nur in Kürze: * Virtuellen Ausgang anlegen, Adresse: /dev/udp/192.168.3.212/11884 (IP und ggf. Port müsst ihr anpassen) * Darunter einen "Virtuellen Ausgang Befehl" anlegen * Befehl bei EIN: **''%%publish tinytuya/set// %%''** * **//Optional: //**Befehl bei AUS analog setzen * Als Digitalausgang verwenden: je nach Bedarf, meist hier NEIN (um Werte über an das Plugin zu übertragen === Geräte steuern - per HTTP - Alternative === Als Alternative könnt ihr Geräte und Werte auch direkt über den mitgelieferten TinyTuya Webserver (siehe oben) setzen. Die API Dokumentation findet ihr hier: [[https://github.com/jasonacox/tinytuya/blob/master/server/README.md|https://github.com/jasonacox/tinytuya/blob/master/server/README.md]] ===== Roadmap ===== Deutsche Übersetzung ===== Fragen stellen und Fehler melden ===== [[https://www.loxforum.com/forum/projektforen/loxberry/plugins/393805-plugin-loxberry-tinytuya]]