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

Manuálna konfigurácia

Správa a riadenie externých zariadení pomocou systému TapHome s podporou protokolov HTTP, TCP, UDP, FTP a MQTT.

Implementácia v TapHome

V TapHome je parsovač paketov hardvérové rozhranie (Nastavenia → Hardvér → Pridať nové rozhranie → Parsovač paketov), ktoré slúži na pripojenie zariadení tretích strán k ovládacej jednotke. Tieto zariadenia môžu komunikovať s riadiacou jednotkou cez WiFi alebo LAN prostredníctvom TCP/IP protokolu.

Parsovač paketov používa proprietárny skriptovací jazyk, ktorý je špeciálne navrhnutý pre systém TapHome. Tento jazyk sa používa na ovládanie a správu pripojených zariadení a ich komunikácie s riadiacou jednotkou. Kliknite sem pre viac informácií o skriptovacom jazyku TapHome

Hierarchia

Systém TapHome používa hierarchickú štruktúru na organizáciu pripojených zariadení. V tejto štruktúre modul funguje ako nadradené zariadenie a môže komunikovať so svojimi podriadenými zariadeniami a riadiť ich.

Modul

Rozhranie môže obsahovať jeden alebo viac modulov, ktoré vo väčšine prípadov pokrývajú komunikáciu s celým fyzickým zariadením. Z hľadiska konfigurácie modul definuje:

  • IP adresu alebo mDNS názov zariadenia
  • Komunikačný port
  • Zabezpečené pripojenie: pozrite sekciu Autentifikácia v nastaveniach služby modulu
  • Ignorovanie chýb SSL certifikátu

Zariadenie

Predstavuje konkrétny riadiaci prvok alebo senzor v systéme TapHome. Musí vždy patriť do jedného nadriadeného modulu.

Podporované zariadenia:

  • Digitálny výstup
  • Analógový výstup
  • Termostat
  • Viachodnotový prepínač
  • Teplotný senzor
  • Premenná
  • Tlačidlo
  • Elektrický merač
  • Reed kontakt
  • Žalúzie, markízy, miešané ventily
  • RGB svetlo
  • Nastaviteľné biele svetlo

Príklad: Shelly Plug S
Modul obsahuje informácie o IP adrese, má skripty na čítanie stavu, nastavovanie a vykonávanie servisných akcií. Zastrešuje 2 zariadenia: digitálny výstup (relé) a merač elektriny merajúci pripojené zariadenia.

Skripty na čítanie a zápis

Riadiaca jednotka TapHome a pripojené zariadenia môžu komunikovať pomocou HTTP alebo HTTPS GET / POST požiadaviek. Odpovede na tieto požiadavky je možné analyzovať pomocou súboru špecializovaných funkcií. Napríklad môže existovať funkcia špeciálne navrhnutá na spracovanie XML odpovedí, iná funkcia na spracovanie JSON odpovedí a ďalšia funkcia na spracovanie odpovedí ako poľa bajtov. Tieto funkcie uľahčujú interpretáciu a použitie informácií získaných z odpovedí, čo umožňuje efektívnejšiu komunikáciu s riadiacou jednotkou a pripojenými zariadeniami.

TapHome definuje viacero atribútov, ktoré môže skriptovací jazyk obsahovať:

  • Inicializačný skript: spúšťa sa pri štarte zariadenia (napr. po reštarte riadiacej jednotky)
  • Skript na čítanie: slúži na nastavovanie hodnôt globálnych premenných alebo čítanie stavov chýb
  • Skript na čítanie hodnoty: skript na čítanie špecifickej hodnoty (množstva) z pripojeného zariadenia (napr. nastavená teplota na termostate alebo nameraná teplota)
  • Skript na zápis hodnoty: zapíše hodnotu do pripojeného zariadenia
  • Skript poslucháča (Listener): vykoná sa pri každom prijatom pakete. Viac informácií v samostatnej sekcii nižšie

Kliknite sem pre viac informácií o skriptovacom jazyku TapHome

Definícia chybových stavov zo skriptov

Atribúty a akcie služby

Skripty a pomocné premenné na module

Skripty a pomocné premenné na zariadení

Pozrite si viac informácií na stránke dokumentácie Modbusu

Podporované protokoly

  • HTTP
  • TCP
  • UDP
  • FTP
  • MQTT

HTTP

SENDHTTPREQUEST

Posiela HTTP požiadavku so zadanými parametrami, čaká na odpoveď a vracia odpoveď ako reťazec JSON s hodnotami ako Content, Headers, HTTP result code. Funkcia je podporovaná iba v skriptoch parsovača paketov s HTTP protokolom.

1
2

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

Príklady:

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

SENDHTTPREQUEST("/getValue")		Responz:
{
  "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

Odosiela zadané dáta (reťazec alebo Kolekcia) cez TCP alebo UDP protokol. Ak sú dáta reťazec, implicitne sa prevedú na bajty pomocou kódovania iso-8859-1. Funkcia je podporovaná iba v skriptoch parsovača paketov s TCP alebo UDP protokolom. Prijaté bajty je možné spracovať v skripte poslucháča.

1

SENDDATA( string/Collection<UInt8> )

Príklady:

1
2

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

COMPLETESERVICEATTRIBUTE

Funkcia sa používa v skriptoch poslucháča v parsovači paketov s TCP/UDP protokolom na oznámenie dokončenia požiadavky na hodnotu atribútu služby. Napríklad vytvoríte požiadavku v skripte atribútu služby pomocou funkcie SENDDATA a po prijatí dát v skripte poslucháča dokončíte čítanie atribútu služby.

1

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Príklady:

1
2

COMPLETESERVICEATTRIBUTE("Uptime", "2d:21h:43m")
COMPLETESERVICEATTRIBUTE("Status", "", "Zariadenie je offline")

COMPLETESERVICEACTION

Funkcia sa používa v skriptoch poslucháča v parsovači paketov s TCP/UDP protokolom na oznámenie dokončenia požiadavky na akciu služby. Napríklad vytvoríte požiadavku v skripte akcie služby pomocou funkcie SENDDATA a po prijatí dát v skripte poslucháča dokončíte akciu služby.

1

COMPLETESERVICEACTION( actionName, result )

Príklady:

1
2

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

FTP

FTPDOWNLOAD

Vráti dáta súboru (ako Collection) z FTP servera. Funkcia je podporovaná iba v skriptoch parsovača paketov s FTP protokolom.

1

FTPDOWNLOAD( pathToFile )

Príklady:

1

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

FTPUPLOAD

Nahráva dáta (Collection alebo reťazec) do súboru na FTP serveri.

1

FTPUPLOAD( pathToFile, data, mode )

Príklady:

1
2

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

MQTT

Okrem vyššie uvedených komunikačných možností systém TapHome tiež umožňuje komunikáciu s externými zariadeniami prostredníctvom protokolu MQTT. MQTT, alebo Message Queuing Telemetry Transport, je ľahký publish/subscribe protokol, ktorý je navrhnutý pre efektívnu a spoľahlivú komunikáciu medzi zariadeniami v kontextoch stroj-ku-stroju (M2M) a IoT.

Na umožnenie komunikácie s externými zariadeniami prostredníctvom MQTT je potrebné vytvoriť samostatný modul v Nastavenia → Hardvér → Pridať nové rozhranie → MQTT broker. Tento modul slúži ako prostredník medzi externými zariadeniami a riadiacou jednotkou, čo umožňuje ich komunikáciu cez protokol MQTT. MQTT broker môže bežať samostatne na riadiacej jednotke, čo umožňuje nezávislú a efektívnu komunikáciu medzi externými zariadeniami a systémom TapHome.

MQTTPUBLISH

Funkcia sa používa na zariadeniach PacketParser s protokolom MQTT na publikovanie správy do MQTT brokera.

1

MQTTPUBLISH( topic, message )

Príklady:

1

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

Poslucháč skriptu

Poslucháč skriptu sa vyvolá pri každom prijatom pakete, špecificky pre MQTT sa poslucháč skriptu vyvolá pri každej správe, ktorá príde cez MQTT, ktorej téma (Topic) zodpovedá filtru témy nastavenému v TapHome; môže ísť o stovky týchto správ za minútu. Dve veci sú tu dôležité:

  • Filter témy musí byť nastavený čo najprísnejšie, aby správy s inou hodnotou témy vôbec nedorazili a tým sa neaktivoval poslucháč skriptu. Napríklad, ak máme záujem len o tému a.b.c.d, filter by mal byť a.b.c.d, nie len a.b.

  • Niektoré zariadenia produkujú mnoho rôznych správ, ktoré majú rovnakú tému, alebo občas musíme nastaviť tému napr. na a.b, pretože máme záujem o správy a.b.c.d, ale aj a.b.x.y, čo samozrejme spôsobí doručenie správ s témou a.b.k.l.m, o ktoré nemáme záujem. To nie je z princípu zlé, ale niektoré zariadenia generujú rôzne stavy alebo správy obsahujúce popisy polí iných správ (metadáta) a tieto môžu mať stovky kB a prichádzať pomerne často – každých niekoľko sekúnd (napr. Zigbee2MQTT).

Z uvedených dôvodov je pri MQTT v poslucháčskom skripte veľmi dôležité rozhodovať na základe hodnoty témy, či ide o relevantnú správu, a ak nie, okamžite ukončiť vykonávanie skriptu a zbytočne neanalyzovať obsah správy v danom čase. Algoritmus v riadiacej jednotke TapHome obsahuje mechanizmy na zabránenie zahltenia správ MQTT; napriek tomu nemožno vylúčiť, že príliš voľný filter témy MQTT a veľké množstvo veľkých správ povedú k zvýšeniu odozvy riadiacej jednotky.

Prijatý paket sa nachádza v premennej (štruktúre) RECEIVEDMSG. Prijaté dáta možno čítať v premennej RECEIVEDMSG.Payload. Payload má dátový typ BLOB (veľký binárny objekt), nie je to reťazec ani pole bajtov. Ak je payload typu string, musí sa použiť funkcia TOSTRING, ale vo všeobecnosti môže mať payload akýkoľvek obsah. RECEIVEDMSG tiež obsahuje protokolovo špecifické dáta, napr. RECEIVEDMSG.Topic pre MQTT. Použitie RECEIVEDMSG.TOPIC je veľmi rýchly a efektívny spôsob, ako zistiť hodnotu témy, na rozdiel od staršieho spôsobu, keď sa používalo RECEIVEDBYTES.

Vylepšenia vo verzii 2024.1

Namiesto:

1
2
3
4
5

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

sa dá napísať takto:

1
2
3

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

Ako je to lepšie – ušetrí jedno volanie PARSEJSON na zistenie hodnoty témy. Ak prichádza veľa MQTT správ a len niektoré sú zaujímavé, je pohodlnejšie použiť túto novú metódu.

RECEIVEDMSG ďalej obsahuje MQTT-špecifické hodnoty – napr. CLIENTID, DUP, CONTENTTYPE, EXPIRY – ich obsah závisí od toho, čo MQTT server posiela. Stará syntax zostáva funkčná a bude fungovať.

RECEIVEDMSG tiež funguje s TCP a UDP, nielen s MQTT. V takom prípade poskytuje iba vlastnosti PAYLOAD a LENGTH.

Analýza paketov

Informácie v nastaveniach služby modulov parsovača paketov obsahujú štatistické údaje o prijatých a odoslaných správach – počty za posledných 5 a 30 minút, počet prijatých bajtov, a pre MQTT sú informácie rozdelené podľa tém MQTT. To by malo pomôcť pri ladení skriptov a nastavení najvhodnejšieho filtra témy tak, aby bolo do Core doručených čo najmenej správ, ktoré sa ďalej nespracúvajú.