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

Ruční konfigurace

TapHome Packet Parser zjednodušuje integraci zařízení přes TCP/IP a podporuje HTTP, TCP, UDP, FTP a MQTT pro efektivní správu a ladění komunikace.

Implementace v TapHome

V TapHome je Packet Parser hardwarové rozhraní (Nastavení → Hardware → Přidat nové rozhraní → Packet parser), které slouží k připojení zařízení třetích stran k řídicí jednotce. Tato zařízení mohou komunikovat s řídicí jednotkou buď prostřednictvím Wi‑Fi, nebo LAN pomocí protokolu TCP/IP.

Packet Parser používá proprietární skriptovací jazyk, který je speciálně navržen pro systém TapHome. Tento jazyk slouží k řízení a správě připojených zařízení a jejich komunikace s řídicí jednotkou. Více informací o skriptovacím jazyce TapHome najdete zde

Hierarchie

Systém TapHome používá hierarchickou strukturu pro organizaci připojených zařízení. V této struktuře modul slouží jako nadřazené zařízení a může komunikovat se svými podřízenými zařízeními a ovládat je.

Modul

Rozhraní může obsahovat jeden nebo více modulů, které ve většině případů pokrývají komunikaci s celým fyzickým zařízením. Z konfiguračního hlediska modul definuje:

  • IP adresu nebo jméno mDNS zařízení
  • Komunikační port
  • Zabezpečené spojení: viz sekce Ověření v nastavení služby modulu
  • Ignorovat chyby SSL certifikátu

Zařízení

Představuje konkrétní řídicí prvek nebo senzor v systému TapHome. Musí vždy patřit do jednoho nadřazeného modulu.

Podporovaná zařízení:

  • Digitální výstup
  • Analogový výstup
  • Termostat
  • Vícehodnotový spínač
  • Teplotní senzor
  • Proměnná
  • Tlačítko
  • Elektrický měřič
  • Reed kontakt
  • Rolety, markýzy, směšovací ventily
  • RGB světlo
  • Světlo s nastavitelnou bílou barvou

Příklad: Shelly Plug S
Modul obsahuje informace o IP adrese, má skripty pro čtení stavu, nastavení a provádění servisních akcí. Zahrnuje 2 zařízení: digitální výstup (relé) a elektroměr měřící napájené zařízení.

Skripty pro čtení a zápis

Řídicí jednotka TapHome a připojená zařízení mohou komunikovat prostřednictvím HTTP nebo HTTPS GET / POST požadavků. Odezvy na tyto požadavky lze analyzovat pomocí sady specializovaných funkcí. Například může existovat funkce určená pro parsování XML odpovědí, další funkce pro parsování JSON odpovědí a další pro parsování odpovědí v poli bajtů. Tyto funkce usnadňují interpretaci a využití informací obdržených v odpovědích, což umožňuje efektivnější komunikaci se řídicí jednotkou a připojenými zařízeními.

TapHome definuje více atributů, které může skriptovací jazyk obsahovat:

  • Inicializační skript: spouští se při startu zařízení (např. po restartu řídicí jednotky)
  • Skript pro čtení: slouží k nastavování hodnot globálních proměnných nebo čtení stavů chyb
  • Skript pro čtení hodnoty: skript pro čtení konkrétní hodnoty (veličiny) z připojeného zařízení (např. nastavená teplota na termostatu nebo naměřená teplota na termostatu)
  • Skript pro zápis hodnoty: zapíše hodnotu na připojené zařízení
  • Skript posluchače: provede se při přijetí každé zprávy. Více informací v následující sekci

Více informací o skriptovacím jazyce TapHome najdete zde

Definice stavů chyby ze skriptů

Atributy služby a akce

Skripty a pomocné proměnné na modulu

Skripty a pomocné proměnné na zařízení

Více informací naleznete na Modbus dokumentační stránce

Podporované protokoly

  • HTTP
  • TCP
  • UDP
  • FTP
  • MQTT

HTTP

SENDHTTPREQUEST

Odesílá HTTP požadavek se zadanými parametry, čeká na odpověď a vrací odpověď jako řetězec JSON s hodnotami jako Content, Headers a HTTP stavový kód. Funkce je podporována pouze ve skriptech Packet Parseru s HTTP protokolem.

1
2

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

Příklady:

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

SENDHTTPREQUEST("/getValue")		Výsledek je:
{
  "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

Odesílá zadaná data (řetězec nebo Collection) prostřednictvím protokolů TCP nebo UDP. Pokud jsou data objektem typu řetězec, jsou implicitně převedena na bajty pomocí kódování iso-8859-1. Funkce je podporována pouze ve skriptech Packet Parseru s protokolem TCP nebo UDP. Přijaté bajty lze zpracovat ve skriptu posluchače.

1

SENDDATA( string/Collection<UInt8> )

Příklady:

1
2

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

COMPLETESERVICEATTRIBUTE

Funkce se používá ve skriptech posluchače v Packet Parseru s protokolem TCP/UDP k oznámení dokončení požadavku na hodnotu atributu služby. Například vytvoříte požadavek ve skriptu atributu služby pomocí funkce SENDDATA a po obdržení dat ve skriptu posluchače dokončíte čtení atributu služby.

1

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Příklady:

1
2

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

COMPLETESERVICEACTION

Funkce se používá ve skriptech posluchače v Packet Parseru s protokolem TCP/UDP k oznámení dokončení požadavku na akci služby. Například vytvoříte požadavek ve skriptu akce služby pomocí funkce SENDDATA a po obdržení dat ve skriptu posluchače dokončíte akci služby.

1

COMPLETESERVICEACTION( actionName, result )

Příklady:

1
2

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

FTP

FTPDOWNLOAD

Vrací data souboru (jako Collection) z FTP serveru. Funkce je podporována pouze ve skriptech Packet Parseru s FTP protokolem.

1

FTPDOWNLOAD( pathToFile )

Příklady:

1

FTPDOWNLOAD("/path/to/file")		(Výsledkem je Collection<UInt8>)

FTPUPLOAD

Nahrává data (Collection nebo řetězec) do souboru na FTP serveru.

1

FTPUPLOAD( pathToFile, data, mode )

Příklady:

1
2

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

MQTT

Kromě výše uvedených komunikačních možností umožňuje systém TapHome také komunikaci se zařízeními třetích stran pomocí protokolu MQTT. MQTT, neboli Message Queuing Telemetry Transport, je lehký protokol pro publikování/odebírání zpráv, navržený pro efektivní a spolehlivou komunikaci mezi zařízeními v kontextech stroj–stroj (M2M) a Internetu věcí (IoT).

Chcete-li umožnit komunikaci se zařízeními třetích stran prostřednictvím MQTT, je nutné vytvořit samostatný modul v Nastavení → Hardware → Přidat nové rozhraní → MQTT Broker. Tento modul slouží jako prostředník mezi zařízeními třetích stran a řídicí jednotkou a umožňuje jim komunikovat prostřednictvím protokolu MQTT. MQTT Broker může běžet autonomně na řídicí jednotce, což umožňuje nezávislou a efektivní komunikaci mezi zařízeními třetích stran a systémem TapHome.

MQTTPUBLISH

Funkce se používá na zařízeních Packet Parser se serverem MQTT k publikování zprávy na MQTT broker.

1

MQTTPUBLISH( topic, message )

Příklady:

1

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

Listener skript

Skript posluchače je vyvolán při každém příjmu balíčku; zejména pro MQTT je skript posluchače spuštěn, když dorazí jakákoliv zpráva prostřednictvím MQTT, jejíž Topic odpovídá Filtru tématu nastavenému v TapHome; může jich být i stovky za minutu. Dvě věci, které je třeba zmínit, jsou:

  • Filtr tématu musí být nastaven co nejvíce restriktivně, aby zprávy s jinou hodnotou Topic vůbec nedorazily a tím se neaktivoval skript posluchače. Například pokud nás zajímá pouze téma a.b.c.d, filtr by měl být a.b.c.d, ne jen a.b.

  • Některá zařízení produkují mnoho různých zpráv se stejným tématem, nebo občas musíme nastavit téma např. na a.b, protože máme zájem o zprávy a.b.c.d, ale také a.b.x.y, což pochopitelně povede k doručení zpráv s tématem a.b.k.l.m, o které nemáme zájem. To není zásadně špatně, ale některá zařízení generují různá oznámení o stavu nebo zprávy, které obsahují popisy polí jiných zpráv (metadata) a tyto mohou být stovky kB dlouhé a doručovány relativně často – každé několik sekund (např. Zigbee2MQTT).

Z výše uvedených důvodů je v MQTT, ve skriptu posluchače, velmi důležité rozhodovat na základě hodnoty Topic, zda jde o relevantní zprávu, a pokud ne, okamžitě ukončit vykonávání skriptu a zbytečně neanalyzovat obsah zprávy. Algoritmus v řídicí jednotce TapHome obsahuje mechanismy, které brání tomu, aby MQTT bylo zahlceno zprávami. Přesto nelze vyloučit, že velmi volně nastavený filtr tématu MQTT a velké množství velkých zpráv nezpůsobí prodloužení doby odezvy řídicí jednotky.

Přijatý paket se nachází v proměnné (struktura) RECEIVEDMSG. Přijatá data lze číst v proměnné RECEIVEDMSG.Payload. Payload má datový typ BLOB (velký binární objekt), není to řetězec ani pole bajtů. Pokud je payload typu řetězec, musí být použita funkce TOSTRING, ale obecně může být payload cokoliv. RECEIVEDMSG dále obsahuje protokol‑specifická data, např. RECEIVEDMSG.Topic pro MQTT. Použití RECEIVEDMSG.TOPIC je velmi rychlý a efektivní způsob, jak zjistit hodnotu tématu, na rozdíl od staršího způsobu, kdy se používalo RECEIVEDBYTES.

Vylepšení ve verzi 2024.1

Namísto:

1
2
3
4
5

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

lze napsat takto:

1
2
3

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

V čem je to lepší – ušetří se jedno volání PARSEJSON při zjišťování hodnoty tématu. Pokud MQTT přijímá mnoho zpráv a jen některé z nich jsou zajímavé, je pohodlnější použít tento nový způsob.

RECEIVEDMSG dále obsahuje MQTT‑specifické hodnoty – např. CLIENTID, DUP, CONTENTTYPE, EXPIRY – jejich obsah závisí na tom, co MQTT server odesílá. Starší syntaxe stále funguje a bude fungovat.

RECEIVEDMSG také funguje s TCP a UDP, nejen s MQTT. V takovém případě poskytuje pouze vlastnosti PAYLOAD a LENGTH.

Analýza paketů

Informace v nastavení služby modulů Packet Parser obsahují statistické údaje o přijatých a odeslaných zprávách – počty za posledních 5 a 30 minut, počet přijatých bajtů, a pro MQTT jsou informace tříděny podle témat MQTT. To by mělo pomoci při ladění skriptů a nastavení nejvhodnějšího filtru témat tak, aby bylo doručeno co nejméně zpráv, které Core nezpracovává.