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

Kézi konfiguráció

A TapHome Packet Parser konfigurálása harmadik fél eszközeinek csatlakoztatására TCP/IP protokollokon keresztül, ideértve az HTTP, TCP, UDP, FTP és MQTT protokollokat.

Megvalósítás a TapHome-ban

A TapHome-ban a Packet Parser egy hardveres interfész (Beállítások → Hardver → Új felület hozzáadása → Packet parser), amelyet harmadik féltől származó eszközök vezérlőhöz való csatlakoztatására használnak. Ezek az eszközök a vezérlőegységgel WiFi- vagy LAN‑kapcsolaton, TCP/IP protokollon keresztül kommunikálhatnak.

A Packet Parser egy saját scriptingnyelvet használ, amelyet kifejezetten a TapHome rendszerhez terveztek. Ezt a nyelvet a csatlakoztatott eszközök vezérlésére és kezelésére, valamint a vezérlőegységgel folytatott kommunikációjuk irányítására használják. Click here for more information on the TapHome scripting language

Hierarchia

A TapHome rendszer hierarchikus struktúrát használ a csatlakoztatott eszközök rendezésére. Ebben a felépítésben egy Modul szülőeszközként működik, és kommunikálhat a gyermek eszközeivel, valamint vezérelheti azokat.

Modul

Egy felület egy vagy több Modult tartalmazhat, amelyek többnyire az egész fizikai eszközzel való kommunikációt fedik le. Konfigurációs szempontból a Modul a következőket határozza meg:

  • eszköz IP-címe vagy mDNS neve
  • kommunikációs port
  • biztonságos kapcsolat: lásd a modul Szolgáltatási beállításai között a Hitelesítés szakaszt
  • SSL tanúsítványhibák figyelmen kívül hagyása

Eszköz

A TapHome rendszerben egy adott vezérlőelemet vagy szenzort képvisel. Mindig egy szülő Modullal kell összefüggésben állnia.

Támogatott eszközök:

  • digitális kimenet
  • analóg kimenet
  • termosztát
  • többértékű kapcsoló
  • hőmérséklet‑szenzor
  • változó
  • nyomógomb
  • villanymérő
  • reed érintkező
  • redőnyök, napellenzők, keverőszelepek
  • RGB fény
  • hangolható fehér fény

Példa: Shelly Plug S
A modul tartalmazza az IP-címre vonatkozó információkat, és rendelkezik az állapotolvasásra, beállításokra és szolgáltatási műveletekre szolgáló szkriptekkel. Két eszközt fed le: egy digitális kimenetet (relét) és egy villanymérőt, amely a csatlakoztatott fogyasztók energiafelhasználását méri.

Olvasási és írási szkriptek

A TapHome vezérlőegység és a hozzá csatlakoztatott eszközök HTTP- vagy HTTPS‑alapú GET / POST kéréseken keresztül kommunikálhatnak. Ezekre a kérésekre adott válaszok speciális függvényekkel értelmezhetők. Például lehet egy olyan függvény, amely XML‑válaszok értelmezésére szolgál, egy másik a JSON‑válaszokhoz, és egy harmadik a bájttömb‑válaszok feldolgozásához. Ezek a függvények megkönnyítik a válaszokban kapott információk értelmezését és felhasználását, lehetővé téve a hatékonyabb és eredményesebb kommunikációt a vezérlőegység és a csatlakoztatott eszközök között.

A TapHome több olyan attribútumot határoz meg, amelyek scriptingnyelvet tartalmazhatnak:

  • Initialize script: fut, amikor az eszköz elindul (például a vezérlőegység újraindítása után)
  • Read script: globális változók értékeinek beállítása vagy hibaállapotok olvasása
  • Read Value script: szkript egy adott érték (mennyiség) olvasására a csatlakoztatott eszközből (pl. a termosztáton beállított hőmérséklet vagy a termosztát által mért hőmérséklet)
  • Write Value script: érték írása a csatlakoztatott eszközbe
  • Listener script: minden csomag érkezésekor lefut. További információ az alábbi külön szakaszban

Click here for more information on the TapHome scripting language

A szkriptekből származó hibafázisok definíciói

Szolgáltatási attribútumok és műveletek

A modul szkriptjei és kiegészítő változók

Eszközön lévő szkriptek és segédváltozók

Lásd még a Modbus dokumentációs oldalát

Támogatott protokollok

  • HTTP
  • TCP
  • UDP
  • FTP
  • MQTT

HTTP

SENDHTTPREQUEST

HTTP‑kérést küld a megadott paraméterekkel, megvárja a választ, és JSON‑stringként adja vissza azt, a Content, Headers és HTTP eredménykód értékekkel együtt. A függvény csak HTTP protokollt használó Packet parser szkriptekben érhető el.

1
2

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

Példák:

 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

Tranzferálja a megadott adatokat (string vagy Collection) TCP vagy UDP protokollon. Ha az adat egy string objektum, akkor iso-8859-1 kódolást használva bájtokra konvertálódik. A függvény csak TCP vagy UDP protokollt használó Packet parser szkriptekben érhető el. A kapott bájtok a Listener szkriptben dolgozhatók fel.

1

SENDDATA( string/Collection<UInt8> )

Példák:

1
2

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

COMPLETESERVICEATTRIBUTE

Ez a függvény a Listener szkriptben használható a TCP/UDP protokollt használó Packet parserben a Szolgáltatási attribútum‑érték kérésének befejezéséről szóló értesítésre. Például egy Service attribute szkriptben a SENDDATA függvényt használva létrehozol egy kérést, és a Listener szkriptben, az adatok megérkezése után, befejezed a szolgáltatási attribútum olvasását.

1

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Példák:

1
2

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

COMPLETESERVICEACTION

Ez a függvény a Listener szkriptben használható a TCP/UDP protokollt használó Packet parserben a Szolgáltatás művelet kérésének befejezéséről szóló értesítésre. Például egy Service action szkriptben a SENDDATA függvényt használva létrehozol egy kérést, és a Listener szkriptben, a beérkezett adatok alapján, befejezed a Szolgáltatás műveletet.

1

COMPLETESERVICEACTION( actionName, result )

Példák:

1
2

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

FTP

FTPDOWNLOAD

Visszaadja a fájl adatait (Collection) az FTP szerverről. A függvény csak FTP protokollt használó Packet parser szkriptekben érhető el.

1

FTPDOWNLOAD( pathToFile )

Példák:

1

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

FTPUPLOAD

Adatokat (Collection vagy szöveg) tölt fel egy fájlba az FTP szerverre.

1

FTPUPLOAD( pathToFile, data, mode )

Példák:

1
2

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

MQTT

Az előbbiekben említett kommunikációs lehetőségek mellett a TapHome rendszer lehetővé teszi harmadik féltől származó eszközökkel való kommunikációt MQTT protokollon keresztül is. Az MQTT (Message Queuing Telemetry Transport) egy könnyű publish/subscribe üzenetküldő protokoll, amelyet gép‑gép (M2M) és IoT környezetek közötti hatékony és megbízható kommunikációra terveztek.

A harmadik fél eszközeivel való MQTT‑kommunikáció engedélyezéséhez szükséges egy külön modul létrehozása a Beállítások → Hardver → Új felület hozzáadása → MQTT Broker menüben. Ez a modul közvetítőként működik a harmadik fél eszközei és a vezérlőegység között, lehetővé téve számukra az MQTT protokollon keresztüli kommunikációt. Az MQTT Broker önállóan futtatható a vezérlőegységen, lehetővé téve a harmadik fél eszközei és a TapHome rendszer közötti független és hatékony kommunikációt.

MQTTPUBLISH

Ezt a függvényt Packet Parser eszközökön használják, hogy MQTT protokollon keresztül üzenetet publikáljanak az MQTT bróker felé.

1

MQTTPUBLISH( topic, message )

Példák:

1

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

Listener szkript

A Listener szkript minden csomag érkezésekor meghívásra kerül; különösen MQTT esetén a Listener szkript akkor fut le, amikor MQTT‑n keresztül bármilyen üzenet érkezik, amelynek Topic‑ja megegyezik a TapHome-ban beállított Topic‑filterrel; ezek az üzenetek percenként akár több száz példányban is érkezhetnek. Két dolgot fontos megemlíteni:

  • A Topic‑szűrőt a lehető legszűkebbre kell beállítani, hogy a különböző Topic‑értékű üzenetek egyáltalán ne érkezzenek be, és így ne aktiválják a Listener szkriptet. Például ha csak az a.b.c.d témára vagyunk kíváncsiak, a szűrő legyen a.b.c.d, ne csak a.b.

  • Bizonyos eszközök sok különböző üzenetet adhatnak ugyanazzal a témával, vagy előfordulhat, hogy a témát pl. a.b‑re kell állítani, mert az a.b.c.d üzenetek is érdekelnek bennünket, de ugyanakkor az a.b.x.y üzenetek is; ez természetesen olyan üzenetek beérkezéséhez is vezethet, amelyek topicja a.b.k.l.m, és amelyeket nem szeretnénk figyelembe venni. Ez önmagában nem probléma, de néhány eszköz különféle állapotfrissítéseket vagy olyan üzeneteket generál, amelyek más üzenetek leírását (metadatatát) tartalmazzák, és ezek akár több száz kB méretűek is lehetnek, valamint viszonylag gyakran – akár néhány másodpercenként – érkezhetnek (pl. Zigbee2MQTT).

A fentiek miatt MQTT‑nél a Listener szkriptben nagyon fontos a Topic értéke alapján eldönteni, hogy releváns‑e az üzenet, és ha nem az, azonnal leállítani a szkript végrehajtását, feleslegessé téve a payload részletes elemzését. A TapHome vezérlő algoritmusa rendelkezik olyan mechanizmusokkal, amelyek megakadályozzák, hogy az MQTT üzenetekkel elárassza a rendszert. Ennek ellenére előfordulhat, hogy egy nagyon lazán beállított MQTT topic‑szűrő és sok, nagy méretű üzenet növeli a vezérlő válaszidejét.

A kapott csomag a RECEIVEDMSG nevű változóban (struktúrában) található. A beérkezett adat a RECEIVEDMSG.Payload változóban olvasható. A Payload BLOB típusú (nagy bináris objektum), nem string vagy bájttömb. Ha a payload típusa string, a TOSTRING függvényt kell használni, de általánosságban a payload bármi lehet. A RECEIVEDMSG tartalmazza a protokoll‑specifikus adatokat is, pl. RECEIVEDMSG.Topic MQTT esetén. A RECEIVEDMSG.TOPIC használata rendkívül gyors és hatékony módja annak, hogy megállapítsuk a téma értékét, ellentétben a régi módszerrel, amikor a RECEIVEDBYTES volt használatban.

Javítások a 2024.1-es verzióban

A következő kód helyett:

1
2
3
4
5

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

így írható:

1
2
3

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

Miért jobb ez? Egy PARSEJSON‑hívást spórolunk meg a téma értékének kiderítéséhez. Ha sok MQTT‑üzenet érkezik, és ezek közül csak néhány releváns, praktikusabb ezt az új módszert használni.

A RECEIVEDMSG továbbra is tartalmazza az MQTT‑specifikus értékeket – pl. CLIENTID, DUP, CONTENTTYPE, EXPIRY –, tartalmuk attól függ, hogy az MQTT szerver mit küld. A régi szintaxis továbbra is működőképes marad.

A RECEIVEDMSG emellett TCP és UDP esetén is működik, nem csak MQTT‑vel. Ilyenkor csak a PAYLOAD és LENGTH tulajdonságokat adja vissza.

Csomagelemzés

A Packet Parser modulok Szolgáltatási beállításaiban statisztikai adatok találhatók a fogadott és küldött üzenetekről – az utolsó 5 és 30 percben mért számlálások, a fogadott bájtok száma, és MQTT esetén az információk MQTT‑témák szerint rendezve. Ez segít a szkriptek hibakeresésében és a legmegfelelőbb témaszűrő beállításában, annak érdekében, hogy minél kevesebb, a Core által feldolgozatlanul maradó üzenet érkezzen.