Manuelle Konfiguration

Implementierung in TapHome

In TapHome ist der Packet Parser eine Hardwareschnittstelle (Einstellungen → Hardware → Neues Interface hinzufügen → Packet parser), die dazu dient, Geräte von Drittanbietern mit dem Controller zu verbinden. Diese Geräte können entweder über WiFi oder LAN über das TCP/IP-Protokoll mit der Steuereinheit kommunizieren.

Der Packet Parser verwendet eine proprietäre Skriptsprache, die speziell für das TapHome-System entwickelt wurde. Diese Sprache wird zur Steuerung und Verwaltung der angeschlossenen Geräte und ihrer Kommunikation mit dem Controller verwendet. Klicken Sie hier für weitere Informationen über die TapHome-Skriptsprache

Hierarchie

Das TapHome-System verwendet eine hierarchische Struktur, um angeschlossene Geräte zu organisieren. 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 physikalischen Gerät abdecken. Was die Konfiguration betrifft, so definiert ein Modul:

• Die IP-Adresse oder der Name des mDNS-Geräts
• Kommunikationsanschluss
• Sichere Verbindung: Siehe Abschnitt Authentifizierung in Service-Einstellungen des Moduls
• SSL-Zertifikatsfehler ignorieren

Gerät

Stellt eine bestimmte Steuerung oder einen Sensor im TapHome-System dar. Es muss immer Teil eines Moduls für Alleinerziehende sein.

Unterstützte Geräte:

• Digitaler Ausgang
• Analogausgang
• Thermostat
• Mehrfachschalter
• Temperatursensor
• Variable
• Taster
• Stromzähler
• Status Eingang
• Rollläden, Markisen, Mischventile
• RGB Licht
• Abstimmbares weißes Licht

Skripte zum Lesen und Schreiben

Der TapHome-Controller und die angeschlossenen Geräte können über HTTP- oder HTTPS-GET/POST-Anfragen kommunizieren. Die Antworten auf diese Anfragen können mit einer Reihe von speziellen Funktionen analysiert werden. So kann es beispielsweise eine Funktion geben, die speziell für das Parsen von XML-Antworten konzipiert ist, eine andere Funktion für das Parsen von JSON-Antworten und eine weitere Funktion für das 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 dem Controller und den angeschlossenen Geräten.

TapHome definiert eine Reihe von Attributen, die in die Skriptsprache aufgenommen werden können:

• Initialisierungsskript: wird ausgeführt, wenn das Gerät gestartet wird (z. B. nach einem Neustart des Controllers)
• Skript lesen: Werte von globalen Variablen setzen oder Fehlerzustände lesen
• Skript zum Lesen von Werten:** Skript zum Lesen eines bestimmten Wertes (Variable) von einem angeschlossenen Gerät (z. B. eingestellte Temperatur an einem Thermostat oder gemessene Temperatur an einem Thermostat)
• Skript Wert schreiben: einen Wert in ein angeschlossenes Gerät schreiben
• Listener-Skript: wird ausgeführt, wenn jedes Paket empfangen wird. Weitere Informationen finden Sie weiter unten in einem separaten Abschnitt

Unterstützte Protokolle

• HTTP

• TCP

• UDP

• FTP

• MQTT

HTTP

SENDHTTPREQUEST

Sendet eine HTTP-Anfrage mit den angegebenen Parametern, wartet auf eine Antwort und gibt die Antwort als JSON-String mit Werten wie Inhalt, Kopfzeilen und HTTP-Ergebniscode zurück. Die Funktion wird nur in Packet-Parser-Skripten mit HTTP-Protokoll unterstützt.

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

Examples:

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
}

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

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 die angegebenen Daten (String oder Collection UInt8) über das TCP- oder UDP-Protokoll. Handelt es sich bei den Daten um ein String-Objekt, werden sie implizit unter Verwendung der Kodierung iso-8859-1 in Bytes umgewandelt. Die Funktion wird nur in Packet Parser-Skripten mit TCP- oder UDP-Protokoll unterstützt. Die empfangenen Bytes können in einem Listener-Skript verarbeitet werden.

SENDDATA( string/Collection<UInt8> )

Examples:

SENDATA(BYTECOLLECTION(“0a dd ef a2”)
SENDATA(“{\”value\”:212}”)

COMPLETESERVICEATTRIBUTE

Diese Funktion wird in den Listener-Skripten des TCP/UDP-Paketparsers verwendet, um den Dienstattributwert über die Beendigung der Anfrage zu informieren.
Sie erstellen beispielsweise eine Abfrage in einem Skript für Serviceattribute mit der Funktion SENDDATA und beenden das Lesen des Serviceattributs, wenn das Listener-Skript die Daten erhält.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Examples:

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

COMPLETESERVICEACTION

Diese Funktion wird in Listener-Skripten im Packet Parser mit TCP/UDP-Protokoll verwendet, um den Abschluss einer Service-Action-Anforderung zu melden.
Sie erstellen z. B. eine Anforderung in einem Service Action Script mit der Funktion SENDDATA und schließen die Service Action ab, nachdem das Listener Script die Daten erhalten hat.

COMPLETESERVICEACTION( actionName, result )

Examples:

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

FTP

FTPDOWNLOAD

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

FTPDOWNLOAD( pathToFile )

Examples:

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

FTPUPLOAD

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

FTPUPLOAD( pathToFile, data, mode )

Examples:

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 TapHome auch die Kommunikation mit Geräten von Drittanbietern über das MQTT-Protokoll. MQTT (Message Queuing Telemetry Transport) ist ein leichtgewichtiges Protokoll zum Veröffentlichen und Abonnieren von Nachrichten, das für die effiziente und zuverlässige Kommunikation zwischen Geräten im Machine-to-Machine- (M2M) und Internet of Things- (IoT) Kontext entwickelt wurde.

Um die Kommunikation mit Geräten von Drittanbietern über MQTT zu ermöglichen, muss ein separates Modul in Einstellungen → Hardware → Neues Interface hinzufügen → MQTT Broker erstellt werden. Dieses Modul fungiert als Vermittler zwischen Geräten von Drittanbietern und dem Controller und ermöglicht ihnen die Kommunikation über das MQTT-Protokoll. Das MQTT-Broker-Modul kann autonom auf der Steuereinheit betrieben werden und ermöglicht eine unabhängige und effiziente Kommunikation zwischen Drittgeräten und dem TapHome-System.

MQTTPUBLISH

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

MQTTPUBLISH( topic, message )

Examples:

MQTTPUBLISH(“shellies/deviceid/relay/0/command”, “off”)

Listener script

Das Listener-Skript wird bei jedem empfangenen Paket aufgerufen, speziell für MQTT wird das Listener-Skript aufgerufen, wenn eine Nachricht über MQTT eintrifft, deren Topic mit dem in TapHome eingestellten Topic-Filter übereinstimmt; es kann Hunderte dieser Nachrichten pro Minute geben. Zwei Dinge sind hier wichtig zu erwähnen:

• Der Topic-Filter muss so restriktiv wie möglich gesetzt werden, damit Nachrichten mit einem anderen Topic-Wert erst gar nicht ankommen und somit das Listener-Skript nicht aktivieren. Wenn wir uns zum Beispiel nur für das Thema a.b.c.d interessieren, sollte der Filter a.b.c.d lauten, nicht nur a.b.
• Manche Geräte produzieren viele verschiedene Nachrichten, die das gleiche Thema haben, oder manchmal müssen wir das Thema z.B. auf a.b setzen, weil wir an Nachrichten a.b.c.d, aber auch an a.b.x.y interessiert sind, was natürlich dazu führt, dass auch Nachrichten mit dem Thema a.b.k.l.m ankommen, an denen wir nicht interessiert sind. Das ist im Prinzip nicht schlecht, aber einige Geräte generieren verschiedene Status-Updates oder Nachrichten, die Feldbeschreibungen anderer Nachrichten (Metadaten) enthalten, und diese können Hunderte von KB lang sein und kommen relativ häufig an - alle paar Sekunden (z. B. Zigbee2MQTT).

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

Das empfangene Paket befindet sich in der Variablen (Struktur) RECEIVEDMSG. Die empfangenen Daten können in der Variablen RECEIVEDMSG.Payload gelesen werden. Payload hat den Datentyp BLOB (large binary object), es handelt sich nicht um einen String oder ein Array von Bytes. Wenn die Nutzlast vom Typ String ist, muss die Funktion TOSTRING verwendet werden, aber im Allgemeinen kann die Nutzlast alles sein. RECEIVEDMSG enthält auch protokollspezifische Daten, z. B. RECEIVEDMSG.Topic für MQTT. Die Verwendung von RECEIVEDMSG.TOPIC ist ein sehr schneller und effizienter Weg, um den Topic-Wert herauszufinden, im Gegensatz zu der alten Methode, bei der RECEIVEDBYTES verwendet wurde.

Verbesserungen in Version 2024.1

Anstatt:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

if parsejson(jsonResponse, "Topic") = "my-topic"

	Va := todouble(parsejson(jsonResponse, "Payload"));

end

es kann so geschrieben werden:

if RECEIVEDMSG.TOPIC = "my-topic"

	Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD));

end

Was ist daran besser - es spart einen Aufruf von PARSEJSON, um herauszufinden, was der Wert des Topics ist. Wenn viele mqtt-Nachrichten eingehen und nur einige von ihnen interessant sind, ist es bequemer, diese neue Methode zu verwenden.

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

RECEIVEDMSG funktioniert auch mit TCP und UDP, nicht nur mit MQTT. In diesem Fall liefert es nur die Eigenschaften PAYLOAD und LENGTH.

Paketanalyse

Die Informationen in den Service-Einstellungen der Packet Parser-Module enthalten statistische Daten über empfangene und gesendete Nachrichten - Zählungen für die letzten 5 und 30 Minuten, die Anzahl der empfangenen Bytes und für MQTT sind die Informationen nach MQTT-Themen sortiert. Dies sollte beim Debuggen von Skripten und beim Festlegen des am besten geeigneten Themenfilters helfen, damit so wenige Nachrichten wie möglich an Core geliefert werden, die überhaupt nicht verarbeitet werden.