Kézi konfiguráció

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. További információ a TapHome szkriptnyelvről

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 szkript: minden csomag érkezésekor lefut. További információ az alábbi külön szakaszban

További információ a TapHome szkriptnyelvről

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 egy HTTP protokollt használó Packet parser szkriptben, megvárja a választ, és egy httpresponse objektumot ad vissza a Content, StatusCode, ReasonPhrase, IsSuccess és Headers tulajdonságokkal. Saját metódussal, törzzsel és fejlécekkel rendelkező kérést a HTTPREQUEST függvénnyel állíthatsz össze — paraméterek és példák: SENDHTTPREQUEST, HTTPREQUEST.

VAR response := SENDHTTPREQUEST("/getValue");
IF(response.IsSuccess, PARSEJSON(response.Content, "value"), NaN)

TCP, UDP#

SENDDATA#

Szöveget vagy collection<uint8> gyűjteményt küld TCP-n vagy UDP-n; az eszköz válaszát a listener szkript dolgozza fel — SENDDATA.

COMPLETESERVICEATTRIBUTE#

A listener szkriptben lezárja annak a szolgáltatási attribútumnak az olvasását, amelynek szkriptje a SENDDATA függvénnyel küldte el a kérést — COMPLETESERVICEATTRIBUTE.

COMPLETESERVICEACTION#

A listener szkriptben lezárja azt a szolgáltatási műveletet, amelynek szkriptje a SENDDATA függvénnyel küldte el a kérést — COMPLETESERVICEACTION.

FTP#

FTPDOWNLOAD#

Egy FTP-kiszolgálón lévő fájl tartalmát adja vissza collection<uint8> gyűjteményként — FTPDOWNLOAD.

FTPUPLOAD#

Adatokat (szöveget vagy collection<uint8> gyűjteményt) ír egy FTP-kiszolgálón lévő fájlba, vagy fűz a végéhez — FTPUPLOAD.

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#

Üzenetet tesz közzé az MQTT brókeren egy MQTT protokollt használó Packet parser eszközről — MQTTPUBLISH.

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 fogadott üzenet a RECEIVEDMSG konstansban található: a Payload blob (szöveggé a TOSTRING függvénnyel alakíthatod), a Topic az MQTT topic, a Protocol a protokoll, a Length pedig a méret. A RECEIVEDMSG.Topic kiolvasása gyors módja annak, hogy eldöntsd, releváns-e az üzenet, szemben a régebbi RECEIVEDBYTES konstanssal. Az összes tulajdonság és a példák: Listener szkriptek.

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

A következő kód helyett:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

így írható:

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 nemcsak MQTT, hanem TCP és UDP esetén is működik; ilyenkor a Payload, a Length és a Protocol ("tcp" vagy "udp") tulajdonságot tartalmazza — RECEIVEDMSG.

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.