Packet Parser (HTTP, TCP, UDP, FTP, MQTT)

Manuelle Konfiguration

Integration von Drittanbieter-Geräten über den Packet Parser in TapHome, eigene Skriptsprache und Unterstützung mehrerer Kommunikationsprotokolle.

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

Serviceattribute 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 eine HTTP-Anfrage mit angegebenen Parametern, wartet auf die Antwort und gibt die Antwort als JSON-String mit den Werten Content, Headers und HTTP-Statuscode zurück. Die Funktion wird nur in Packet-Parser-Skripten mit dem HTTP-Protokoll unterstützt.

1
2

SENDHTTPREQUEST( path, method, body, header1, header2… )
SENDHTTPREQUEST( HttpRequest )

Beispiele:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

SENDHTTPREQUEST("/getValue")		Result is:
{
  "Headers": [
    {
      "Key": "Content-Type",
      "Value": ["application/json"]
    },
    {
      "Key": "Content-Length",
      "Value": ["1007"]
    }
  ],
  "Content": "{\"value\":31}",
  "ReasonPhrase": "OK",
  "StatusCode": 200,
  "IsSuccess": true
}

1

SENDHTTPREQUEST("/doSomething", "POST", "someData", "header1:value1", "header2:value2", "header3:value3")

1
2
3
4
5
6
7
8
9

VAR request := HTTPREQUEST("/path", "PUT", "someData");
request.Headers := { "name1: value1", "name2: value2" … };
request.Method := "POST";
VAR response := SENDHTTPREQUEST(request);

IF response.IsSuccess
  VAR content := response.Content;
  …
END

TCP, UDP

SENDDATA

Sendet angegebene Daten (String oder Collection) über das TCP- oder UDP-Protokoll. Wenn Daten ein String-Objekt sind, werden sie implizit mittels ISO-8859-1-Kodierung in Bytes konvertiert. Die Funktion wird nur in Packet-Parser-Skripten mit dem TCP- oder UDP-Protokoll unterstützt. Empfangene Bytes können im Listener-Skript verarbeitet werden.

1

SENDDATA( string/Collection<UInt8> )

Beispiele:

1
2

SENDDATA(BYTECOLLECTION("0a dd ef a2"))
SENDDATA("{\"value\":212}")

COMPLETESERVICEATTRIBUTE

Die Funktion wird in Listener-Skripten im Packet Parser mit TCP/UDP-Protokoll verwendet, um den Abschluss einer Service-Attribut-Wert-Anfrage zu melden. Z. B. erstellen Sie eine Anfrage im Service-Attribut-Skript unter Verwendung der SENDDATA-Funktion, und nachdem Sie die Daten im Listener-Skript empfangen haben, schließen Sie den Service-Attribut-Lesevorgang ab.

1

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Beispiele:

1
2

COMPLETESERVICEATTRIBUTE("Uptime", "2d:21h:43m")
COMPLETESERVICEATTRIBUTE("Status", "", "Device is offline")

COMPLETESERVICEACTION

Die Funktion wird in Listener-Skripten im Packet Parser mit TCP/UDP-Protokoll verwendet, um den Abschluss einer Service-Aktionsanfrage zu melden. Z. B. erstellen Sie eine Anfrage im Service-Aktions-Skript unter Verwendung der SENDDATA-Funktion, und nachdem Sie die Daten im Listener-Skript empfangen haben, schließen Sie die Service-Aktion ab.

1

COMPLETESERVICEACTION( actionName, result )

Beispiele:

1
2

COMPLETESERVICEACTION("Reboot", "Rebooted successfully")
COMPLETESERVICEACTION("Enable cloud", "Device is offline")

FTP

FTPDOWNLOAD

Gibt die Dateidaten (als Collection) vom FTP-Server zurück. Die Funktion wird nur in Packet-Parser-Skripten mit dem FTP-Protokoll unterstützt.

1

FTPDOWNLOAD( pathToFile )

Beispiele:

1

FTPDOWNLOAD("/path/to/file")		(Result is Collection<UInt8>)

FTPUPLOAD

Lädt Daten (Collection oder String) in eine Datei auf dem FTP-Server hoch.

1

FTPUPLOAD( pathToFile, data, mode )

Beispiele:

1
2

FTPUPLOAD("/path/to/file", "some data", "write")
FTPUPLOAD("/path/to/file", BYTECOLLECTION("a7 ff e2"), "append")

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

Die Funktion wird auf Packet-Parser-Geräten mit dem MQTT-Protokoll verwendet, um eine Nachricht an den MQTT-Broker zu veröffentlichen.

1

MQTTPUBLISH( topic, message )

Beispiele:

1

MQTTPUBLISH("shellies/deviceid/relay/0/command", "off")

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 empfangenen Paketdaten befinden sich in der Variablen (Struktur) RECEIVEDMSG. Die empfangenen Daten können in RECEIVEDMSG.Payload gelesen werden. Payload hat den Datentyp BLOB (Binary Large Object); es ist kein String oder Byte-Array. Wenn der Payload vom Typ String ist, muss die TOSTRING-Funktion verwendet werden, aber im Allgemeinen kann der Payload alles sein. RECEIVEDMSG enthält außerdem protokollspezifische Daten, z. B. RECEIVEDMSG.Topic für MQTT. Die Verwendung von RECEIVEDMSG.TOPIC ist eine sehr schnelle und effiziente Methode, den Topic-Wert herauszufinden, im Gegensatz zur alten Methode, bei der RECEIVEDBYTES verwendet wurde.

Verbesserungen in Version 2024.1

Stattdessen:

1
2
3
4
5

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

kann es so geschrieben werden:

1
2
3

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. In diesem Fall liefert es nur die Eigenschaften PAYLOAD und LENGTH.

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.