Kézi konfiguráció

Megvalósítás a TapHome-ban

A TapHome-ban a csomagelemző egy hardveres interfész (Beállítások → Hardver → Új felület hozzáadása → Packet parser), amely arra szolgál, hogy harmadik féltől származó eszközöket csatlakoztasson a vezérlőhöz. Ezek az eszközök a vezérlőegységgel WiFi vagy LAN segítségével, TCP/IP protokollon keresztül kommunikálhatnak.

A csomagelemző egy saját szkriptnyelvvel dolgozik, amelyet kifejezetten a TapHome rendszerhez terveztek. Ez a nyelv a csatlakoztatott eszközök és a vezérlővel való kommunikációjuk vezérlésére és kezelésére szolgál. Kattintson ide a TapHome szkriptnyelvről szóló további információkért

Hierarchia

A TapHome rendszer hierarchikus struktúrát használ a csatlakoztatott eszközök rendszerezésére. Ebben a struktúrában egy modul szülőeszközként működik, és képes kommunikálni és vezérelni a gyermek eszközeit.

Modul

Egy interfész tartalmazhat egy vagy több modult, amelyek a legtöbb esetben a teljes fizikai eszközzel való kommunikációt fedik le. A konfiguráció szempontjából egy modul a következőket határozza meg:

• Az mDNS eszköz IP-címe vagy neve
• kommunikációs port
• Biztonságos kapcsolat: Lásd a modul Hitelesítés szakaszát a Részletes beállítások modulban.
• SSL tanúsítvány hibák figyelmen kívül hagyása

Device

Egy adott vezérlőt vagy érzékelőt képvisel a TapHome rendszerben. Mindig az egyszülős modul részét kell képeznie.

Támogatott eszközök:

• Digitális kimenet
• Analóg kimenet
• Termosztát
• Többértékű kapcsoló
• Hő érzékelő
• Változó
• Nyomógomb
• Elektromos fogyasztásmérő
• Kontaktus
• Redőnyök, napellenzők, keverőszelepek
• RGB fény
• Hangolható fehér fény

Szkriptek olvasáshoz és íráshoz

A TapHome vezérlő és a csatlakoztatott eszközök HTTP vagy HTTPS GET/POST kérésekkel kommunikálhatnak. Az ezekre a kérésekre adott válaszok egy sor speciális függvény segítségével elemezhetők. Létezhet például egy kifejezetten XML-válaszok elemzésére szolgáló függvény, egy másik a JSON-válaszok elemzésére szolgáló függvény, és még egy másik a bájtmintatömb-válaszok elemzésére szolgáló függvény. Ezek a funkciók 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ővel és a csatlakoztatott eszközökkel.

A TapHome számos olyan attribútumot határoz meg, amelyek a szkriptnyelvben szerepelhetnek:

• Inicializáló szkript: az eszköz indításakor fut le (pl. a vezérlő újraindítása után).
• Skriptolvasás: globális változók értékeinek beállítása vagy hibaállapotok olvasása
• Értékolvasó szkript: szkript egy adott érték (változó) beolvasására egy csatlakoztatott eszközről (pl. beállított hőmérséklet egy termosztáton vagy mért hőmérséklet egy termosztáton).
• Write value script: értéket ír egy csatlakoztatott eszközre
• Listener script: minden egyes csomag fogadásakor végrehajtásra kerül. További információ lent egy külön részben

Támogatott protokollok

• HTTP

• TCP

• UDP

• FTP

• MQTT

HTTP

SENDHTTPREQUEST

Elküld egy HTTP-kérelmet a megadott paraméterekkel, vár a válaszra, és a választ JSON-stringként adja vissza, amely olyan értékeket tartalmaz, mint a Tartalom, fejlécek, HTTP eredménykód. A funkció csak a HTTP protokollt használó csomagelemző szkriptekben támogatott.

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

A megadott adatokat (karakterlánc vagy UInt8 kollekció) TCP vagy UDP protokoll segítségével küldi el. Ha az adat egy karakterlánc objektum, akkor az implicit módon bájtokká konvertálódik az iso-8859-1 kódolással. A funkció csak TCP vagy UDP protokollal rendelkező csomagelemző szkriptekben támogatott. A fogadott bájtokat egy Listener szkriptben lehet feldolgozni.

SENDDATA( string/Collection<UInt8> )

Examples:

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

COMPLETESERVICEATTRIBUTE

Ezt a funkciót a TCP/UDP csomagelemző Listener szkriptjei használják a Service Attribute értékének értesítésére a kérés befejezéséről.
Például a SENDDATA függvénnyel létrehoz egy kérést egy szolgáltatásattribútum-skriptben, és akkor fejezi be a szolgáltatásattribútum olvasását, amikor a figyelőszkript megkapja az adatokat.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Examples:

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

COMPLETESERVICEACTION

Ezt a funkciót a TCP/UDP protokollt használó csomagelemző csomagmegosztó szkriptekben használják a szolgáltatási műveletkérés befejezésének értesítésére.
Például a SENDDATA függvény használatával létrehozhat egy kérést egy szolgáltatási művelet parancsfájlban, és befejezheti a szolgáltatási műveletet, miután a figyelő parancsfájl megkapta az adatokat.

COMPLETESERVICEACTION( actionName, result )

Examples:

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

FTP

FTPDOWNLOAD

Visszaadja a fájl adatait (Collection UInt8-ként) az FTP-kiszolgálóról. A funkció csak az FTP protokollt használó csomagelemző szkriptekben támogatott.

FTPDOWNLOAD( pathToFile )

Examples:

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

FTPUPLOAD

Feltölti az adatokat (Collection UInt8 vagy string) egy fájlba az FTP-kiszolgálón.

FTPUPLOAD( pathToFile, data, mode )

Examples:

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

MQTT

A fenti kommunikációs lehetőségeken kívül a TapHome rendszer az MQTT protokollt használó harmadik fél eszközeivel való kommunikációt is lehetővé teszi. Az MQTT (Message Queuing Telemetry Transport) egy könnyű üzenetek közzétételére és feliratkozására szolgáló protokoll, amelyet a Machine-to-Machine (M2M) és Internet of Things (IoT) környezetben lévő eszközök közötti hatékony és megbízható kommunikációra terveztek.

Ahhoz, hogy lehetővé tegye a kommunikációt harmadik fél eszközeivel az MQTT segítségével, egy külön modult kell létrehozni a Beállítások → Hardver → Új felület hozzáadása → MQTT Broker alatt. Ez a modul közvetítőként működik a harmadik féltől származó eszközök és a vezérlő között, lehetővé téve számukra az MQTT protokoll használatával történő kommunikációt. Az MQTT Broker modul önállóan futtatható a vezérlőegységen, lehetővé téve a független és hatékony kommunikációt harmadik féltől származó eszközök és a TapHome rendszer között.

MQTTPUBLISH

A funkciót az MQTT protokollt használó PacketParser eszközökön az MQTT brókerhez küldött üzenet közzétételére használják.

MQTTPUBLISH( topic, message )

Examples:

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

Listener script

A figyelő szkript minden egyes csomag fogadásakor meghívásra kerül, különösen az MQTT esetében a figyelő szkript akkor hívódik meg, amikor bármilyen olyan üzenet érkezik az MQTT-n keresztül, amelynek Topic-ja megfelel a TapHome-ban beállított Topic-szűrőnek; percenként több száz ilyen üzenet érkezhet. Két dolgot fontos itt megemlíteni:

• A Topic-szűrőt a lehető legszigorúbban kell beállítani, hogy az ettől eltérő Topic-értékkel rendelkező üzenetek egyáltalán ne érkezzenek, és így ne aktiválják a listener-szkriptet. Ha például csak az a.b.c.d téma érdekel minket, akkor a szűrőnek a.b.c.d-nek kell lennie, nem csak a.b-nek.
• Egyes eszközök sok különböző üzenetet produkálnak, amelyeknek ugyanaz a témájuk, vagy néha a témát pl. a.b-re kell beállítanunk, mert minket az a.b.c.d, de az a.b.x.y üzenetek is érdekelnek, ami természetesen azt eredményezi, hogy olyan a.b.k.l.m témájú üzenetek is érkeznek, amelyek nem érdekelnek minket. Ez elvileg nem rossz, de egyes eszközök különböző állapotfrissítéseket vagy más üzenetek mezőleírásait (metaadatokat) tartalmazó üzeneteket generálnak, és ezek több száz KB hosszúak lehetnek, és viszonylag gyakran - néhány másodpercenként - érkeznek (pl. Zigbee2MQTT).

A fent említett okok miatt az MQTT-ben egy figyelőszkriptben nagyon fontos, hogy a Topic értéke alapján döntse el, hogy releváns üzenetről van-e szó, és ha nem, akkor azonnal állítsa le a szkript végrehajtását, és ne elemezze feleslegesen az üzenet tartalmát ekkor. A TapHome vezérlő algoritmusa olyan mechanizmusokat tartalmaz, amelyek megakadályozzák, hogy az MQTT-t túlterheljék az üzenetek. Mindazonáltal nem zárható ki, hogy egy nagyon lazán beállított MQTT-témaszűrő és nagyszámú, nagyméretű üzenet nem fogja a vezérlő válaszidejének növekedését okozni.

A fogadott csomag a RECEIVEDMSG változóban (struktúrában) található. A kapott adatok a RECEIVEDMSG.Payload változóban olvashatók. A Payload adattípusa BLOB (nagy bináris objektum), nem string vagy bájt tömb. Ha a payload string típusú, akkor a TOSTRING függvényt kell használni, de általában a payload bármi lehet. A RECEIVEDMSG protokollspecifikus adatokat is tartalmaz, pl. RECEIVEDMSG.Topic az MQTT esetében. A RECEIVEDMSG.TOPIC használata nagyon gyors és hatékony módja a téma értékének kiderítésére, ellentétben a régi módszerrel, amikor a RECEIVEDBYTES-t használták.

Fejlesztések a 2024.1-es verzióban

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

Miben jobb ez - megspórol egy PARSEJSON hívást, hogy megtudjuk, mi a téma értéke. Ha sok mqtt üzenet érkezik, és csak néhány közülük érdekes, kényelmesebb ezt az új módszert használni.

A RECEIVEDMSG tartalmaz továbbá mqtt-specifikus értékeket - pl. CLIENTID, DUP, CONTENTTYPE, EXPIRY - ezek tartalma attól függ, hogy mit küld az mqtt szerver. A régi szintaxis továbbra is működik és működni fog.

A RECEIVEDMSG TCP és UDP protokollal is működik, nem csak az MQTT-vel. Ebben az esetben csak a PAYLOAD és LENGTH tulajdonságokat adja meg.

Csomagelemzés

A Packet Parser modulok Szolgáltatási Beállításainak információi statisztikai adatokat tartalmaznak a fogadott és elküldött üzenetekről - az utolsó 5 és 30 perc számai, a fogadott bájtok száma, és az MQTT esetében az információk MQTT-témák szerint vannak rendezve. Ez segíthet a szkriptek hibakeresésében és a legmegfelelőbb témaszűrő beállításában, hogy a Core-hoz a lehető legkevesebb olyan üzenet érkezzen, amelyet nem dolgoz fel.