Manuelle Konfiguration

Implementierung in TapHome#

In TapHome ist der Packet Parser eine Hardware-Schnittstelle (Einstellungen → Hardware → Neue Schnittstelle hinzufügen → Packet Parser), die verwendet wird, um Drittanbietergeräte an die Steuerzentrale anzuschließen. Diese Geräte können mit der Steuereinheit entweder über WiFi oder LAN via TCP/IP-Protokoll kommunizieren.

Der Packet Parser verwendet eine proprietäre Skriptsprache, die speziell für das TapHome-System entwickelt wurde. Diese Sprache wird genutzt, um die verbundenen Geräte zu steuern und deren Kommunikation mit der Steuereinheit zu verwalten. Klicken Sie hier für weitere Informationen zur TapHome-Skriptsprache

Hierarchie#

Das TapHome-System verwendet eine hierarchische Struktur zur Organisation der angeschlossenen Geräte. In dieser Struktur fungiert ein Modul als übergeordnetes Gerät und kann mit seinen untergeordneten Geräten kommunizieren und diese steuern.

Modul#

Eine Schnittstelle kann ein oder mehrere Module enthalten, die in den meisten Fällen die Kommunikation mit dem gesamten physischen Gerät abdecken. Aus Sicht der Konfiguration definiert das Modul:

• IP-Adresse oder mDNS-Name eines Geräts
• Kommunikationsport
• Sichere Verbindung: Siehe Abschnitt Authentifizierung in den Serviceeinstellungen eines Moduls
• SSL-Zertifikatfehler ignorieren

Gerät#

Stellt ein spezifisches Steuerelement oder einen Sensor im TapHome-System dar. Es muss immer Teil eines übergeordneten Moduls sein.

Unterstützte Geräte:

• Digitalausgang
• Analogausgang
• Thermostat
• Multi-Value-Schalter
• Temperatursensor
• Variable
• Taster
• Stromzähler
• Reed-Kontakt
• Rollläden, Markisen, Mischventile
• RGB-Licht
• einstellbares Weißlicht

Beispiel: Shelly Plug S
Das Modul enthält Informationen über die IP-Adresse, es verfügt über Skripte zum Lesen des Status, zu den Einstellungen und zur Durchführung von Servicetätigkeiten. Es deckt 2 Geräte ab: einen Digitalausgang (Relais) und einen Stromzähler, der die angeschlossenen Verbraucher misst.

Skripte zum Lesen und Schreiben#

Die TapHome-Steuereinheit und die verbundenen Geräte können über HTTP- oder HTTPS-GET/POST-Anfragen kommunizieren. Die Antworten auf diese Anfragen können mit einer Reihe spezialisierter Funktionen analysiert werden. So kann es beispielsweise eine Funktion geben, die speziell zum Parsen von XML-Antworten entwickelt wurde, eine weitere Funktion zum Parsen von JSON-Antworten und noch eine weitere Funktion zum Parsen von Byte-Array-Antworten. Diese Funktionen erleichtern die Interpretation und Nutzung der in den Antworten erhaltenen Informationen und ermöglichen eine effizientere und effektivere Kommunikation mit der Steuereinheit und den verbundenen Geräten.

TapHome definiert mehrere Attribute, die Skripte enthalten können:

• Initialisiere-Skript: wird ausgeführt, wenn das Gerät gestartet wird (z. B. nach dem Neustart der Steuereinheit)
• Read-Skript: setzt Werte globaler Variablen oder liest Fehlerzustände
• Read-Value-Skript: Skript zum Lesen eines bestimmten Werts (Größe) von einem verbundenen Gerät (z. B. eingestellte Temperatur am Thermostat oder gemessene Temperatur am Thermostat)
• Write-Value-Skript: schreibt einen Wert auf das verbundene Gerät
• Listener-Skript: wird ausgeführt, wenn ein Paket empfangen wird. Weitere Informationen finden Sie in einem separaten Abschnitt unten

Klicken Sie hier für weitere Informationen zur TapHome-Skriptsprache

Definition von Fehlerzuständen aus Skripten#

Service-Attribute und -Aktionen#

Skripte und Hilfsvariablen am Modul#

Skripte und Hilfsvariablen am Gerät#

Siehe weitere Informationen auf der Modbus-Dokumentationsseite

Unterstützte Protokolle#

• HTTP
• TCP
• UDP
• FTP
• MQTT

HTTP#

SENDHTTPREQUEST#

Sendet in einem Packet-Parser-Skript mit dem HTTP-Protokoll eine HTTP-Anfrage, wartet auf die Antwort und gibt ein httpresponse-Objekt mit Content, StatusCode, ReasonPhrase, IsSuccess und Headers zurück. Eine Anfrage mit eigener Methode, eigenem Body und eigenen Headern wird mit HTTPREQUEST erstellt — Parameter und Beispiele: SENDHTTPREQUEST, HTTPREQUEST.

VAR response := SENDHTTPREQUEST("/getValue");
IF(response.IsSuccess, PARSEJSON(response.Content, "value"), NaN)

TCP, UDP#

SENDDATA#

Sendet einen String oder eine collection<uint8> über TCP oder UDP; die Antwort des Geräts wird im Listener-Skript verarbeitet — SENDDATA.

COMPLETESERVICEATTRIBUTE#

Schließt im Listener-Skript das Lesen eines Service-Attributs ab, dessen Skript die Anfrage mit SENDDATA gesendet hat — COMPLETESERVICEATTRIBUTE.

COMPLETESERVICEACTION#

Schließt im Listener-Skript eine Service-Aktion ab, deren Skript die Anfrage mit SENDDATA gesendet hat — COMPLETESERVICEACTION.

FTP#

FTPDOWNLOAD#

Gibt den Inhalt einer Datei auf dem FTP-Server als collection<uint8> zurück — FTPDOWNLOAD.

FTPUPLOAD#

Schreibt Daten (einen String oder eine collection<uint8>) in eine Datei auf dem FTP-Server oder hängt sie an — FTPUPLOAD.

MQTT#

Zusätzlich zu den oben genannten Kommunikationsoptionen ermöglicht das TapHome-System auch die Kommunikation mit Drittanbietergeräten über das MQTT-Protokoll. MQTT (Message Queuing Telemetry Transport) ist ein leichtgewichtiges Publish/Subscribe-Messaging-Protokoll, das für eine effiziente und zuverlässige Kommunikation zwischen Geräten in Machine-to-Machine-(M2M-) und Internet-of-Things-(IoT-)Szenarien entwickelt wurde.

Um die Kommunikation mit Drittanbietergeräten über MQTT zu ermöglichen, ist es notwendig, ein separates Modul unter Einstellungen → Hardware → Neue Schnittstelle hinzufügen → MQTT-Broker zu erstellen. Dieses Modul fungiert als Vermittler zwischen den Drittanbietergeräten und der Steuereinheit und ermöglicht die Kommunikation über das MQTT-Protokoll. Der MQTT-Broker kann autonom auf der Steuereinheit ausgeführt werden, wodurch eine eigenständige und effiziente Kommunikation zwischen den Drittanbietergeräten und dem TapHome-System ermöglicht wird.

MQTTPUBLISH#

Veröffentlicht von einem Packet-Parser-Gerät mit dem MQTT-Protokoll eine Nachricht beim MQTT-Broker — MQTTPUBLISH.

Listener-Skript#

Das Listener-Skript wird aufgerufen, wenn ein Paket empfangen wird; speziell bei MQTT wird das Listener-Skript aufgerufen, wenn eine MQTT-Nachricht ankommt, deren Topic dem im TapHome gesetzten Topic-Filter entspricht; es können Hunderte solcher Nachrichten pro Minute eintreffen. Zwei Dinge sind hierbei wichtig zu erwähnen:

• Der Topic-Filter muss so restriktiv wie möglich gesetzt werden, damit Nachrichten mit einem anderen Topic-Wert gar nicht erst ankommen und somit das Listener-Skript nicht aktiviert wird. Wenn wir zum Beispiel nur an Topic a.b.c.d interessiert sind, sollte der Filter a.b.c.d sein, nicht nur a.b.

• Einige Geräte erzeugen viele unterschiedliche Nachrichten, die dasselbe Topic haben, oder manchmal müssen wir das Topic z. B. auf a.b setzen, weil wir an Nachrichten a.b.c.d interessiert sind, aber auch a.b.x.y, was natürlich dazu führt, dass Nachrichten mit Topic a.b.k.l.m ankommen, an denen wir kein Interesse haben. Das ist grundsätzlich nicht schlimm, aber manche Geräte erzeugen verschiedene Statusupdates oder Nachrichten, die Felddeskriptionen anderer Nachrichten (Metadaten) enthalten, und diese können hunderte KB groß sein und relativ häufig ankommen – alle paar Sekunden (z. B. Zigbee2MQTT).

Aus den genannten Gründen ist es bei MQTT in einem Listener-Skript sehr wichtig, anhand des Topic-Werts zu entscheiden, ob es sich um eine relevante Nachricht handelt, und andernfalls die Skriptausführung sofort zu stoppen und den Nachrichteninhalt zu diesem Zeitpunkt nicht unnötig zu analysieren. Der Algorithmus im TapHome-Controller enthält Mechanismen, um zu verhindern, dass MQTT von Nachrichten überflutet wird. Dennoch kann nicht ausgeschlossen werden, dass ein sehr locker gesetzter MQTT-Topic-Filter und eine große Anzahl großer Nachrichten zu einer Erhöhung der Reaktionszeit des Controllers führen.

Die empfangene Nachricht steht in RECEIVEDMSG: Payload ist ein Blob (Text wandeln Sie mit TOSTRING um), Topic das MQTT-Topic, Protocol das Protokoll und Length die Größe. Das Lesen von RECEIVEDMSG.Topic ist ein schneller Weg zu entscheiden, ob eine Nachricht relevant ist, anders als das ältere RECEIVEDBYTES. Alle Eigenschaften und Beispiele: Listener-Skripte.

Verbesserungen in Version 2024.1#

Stattdessen:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

if parsejson(jsonResponse, "Topic") = "my-topic"
  Va := todouble(parsejson(jsonResponse, "Payload"));
end

kann es so geschrieben werden:

if RECEIVEDMSG.TOPIC = "my-topic"
  Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD));
end

Worin ist das besser – es spart einen Aufruf von PARSEJSON, um den Wert des Topic herauszufinden. Wenn viele MQTT-Nachrichten hereinkommen und nur einige davon interessant sind, ist es sinnvoller, diese neue Methode zu verwenden.

RECEIVEDMSG enthält außerdem weitere MQTT-spezifische Werte – z. B. CLIENTID, DUP, CONTENTTYPE, EXPIRY – deren Inhalt davon abhängt, was der MQTT-Server sendet. Die alte Syntax funktioniert weiterhin und wird auch künftig funktionieren.

RECEIVEDMSG funktioniert auch mit TCP und UDP, nicht nur mit MQTT; dort enthält es Payload, Length und Protocol ("tcp" oder "udp") — RECEIVEDMSG.

Packet-Analyse#

Die Informationen in den Serviceeinstellungen der Packet-Parser-Module enthalten statistische Daten über empfangene und gesendete Nachrichten – Zählwerte der letzten 5 und 30 Minuten, die Anzahl der empfangenen Bytes, und bei MQTT werden die Informationen nach MQTT-Themen sortiert. Dies sollte bei der Fehlersuche in Skripten helfen und dabei unterstützen, den geeignetsten Topic-Filter festzulegen, damit so wenige wie möglich Nachrichten zugestellt werden, die vom Core nicht verarbeitet werden.