Manuálna konfigurácia

Implementácia v TapHome

V systéme TapHome je Packet Parser hardvérové rozhranie (Nastavenia → Hardvér → Pridať nové rozhranie → Packet parser), ktoré sa používa na pripojenie zariadení tretích strán k riadiacej jednotke. Tieto zariadenia môžu komunikovať s riadiacou jednotkou buď pomocou WiFi alebo LAN cez protokol TCP/IP.

Packet Parser používa proprietárny skriptovací jazyk, ktorý je špeciálne navrhnutý pre systém TapHome. Tento jazyk slúži na ovládanie a správu pripojených zariadení a ich komunikáciu s riadiacou jednotkou. Kliknutím sem získate ďalšie informácie o TapHome skriptovacom jazyku

Hierarchia

Systém TapHome používa hierarchickú štruktúru na usporiadanie pripojených zariadení. V tejto štruktúre modul funguje ako nadradené zariadenie a môže komunikovať so svojimi podradenými zariadeniami a ovládať 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 názov mDNS zariadenia
• komunikačný port
• Zabezpečené pripojenie: Pozri oddiel Autentifikácia v Servisné nastavenia Modulu
• Ignorovať chyby certifikátu SSL

Zariadenie

Predstavuje konkrétny ovládací prvok alebo snímač v systéme TapHome. Musí byť vždy súčasťou jedného nadradeného Modulu.

Podporované zariadenia:

• Digitálny výstup
• Analógový výstup
• Termostat
• Viac-hodnotový prepínač
• Teplotný senzor
• Premenná
• Tlačidlo
• Elektromer
• Stavový kontakt
• Rolety, markízy, zmiešavacie ventily
• RGB svetlo
• Tunable white light

Skripty na čítanie a zápis

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

TapHome definuje viacero atribútov, ktoré môžu obsahovať jazyk skriptu:

• Initialize script: sa spustí pri spustení zariadenia (napr. po reštarte riadiacej jednotky)
• Read skriptu: nastavenie hodnôt globálnych premenných alebo čítanie chybových stavov
• Read value script: skript na čítanie konkrétnej hodnoty (veličiny) z pripojeného zariadenia (napr. nastavená teplota na termostate alebo nameraná teplota na termostate)
• Write value script: zápis hodnoty do pripojeného zariadenia
• Listener script: spúšťa sa pri prijatí každého packetu. Viac info v samostatnej sekcii nižsie

Podporované protokoly

• HTTP

• TCP

• UDP

• FTP

• MQTT

HTTP

SENDHTTPREQUEST

Odošle HTTP požiadavku so zadanými parametrami, počká na odpoveď a vráti odpoveď ako reťazec JSON s hodnotami ako Obsah, Hlavičky, Výsledný kód HTTP. Funkcia je podporovaná len v Packet parser skriptoch s protokolom HTTP.

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

Odošle zadané údaje (reťazec alebo Collection UInt8) pomocou protokolu TCP alebo UDP. Ak sú dáta objektom reťazca, sú implicitne konvertované na bajty pomocou kódovania iso-8859-1. Funkcia je podporovaná len v skriptoch Packet parseru s protokolom TCP alebo UDP. Prijaté bajty možno spracovať v Listener skripte.

SENDDATA( string/Collection<UInt8> )

Examples:

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

COMPLETESERVICEATTRIBUTE

Funkcia sa používa v Listener skriptoch TCP/UDP Packet parseri na oznámenie ukončenia požiadavky na hodnotu Servisného atribútu.
Napr. vytvoríte požiadavku v skripte Servisného atribútu pomocou funkcie SENDDATA a po prijatí údajov v Listener skripte dokončíte čítanie Servisného atribútu.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Examples:

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

COMPLETESERVICEACTION

Funkcia sa používa v Listener skriptoch v Packet parseri s protokolom TCP/UDP na oznámenie dokončenia požiadavky na Servisnú akciu.
Napr. vytvoríte požiadavku v skripte Servisnej akcie pomocou funkcie SENDDATA a po prijatí údajov v Listener skripte dokončíte Servisnú akciu.

COMPLETESERVICEACTION( actionName, result )

Examples:

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

FTP

FTPDOWNLOAD

Vráti údaje o súbore (ako Collection UInt8) z FTP servera. Funkcia je podporovaná len v Packet parser skriptoch s protokolom FTP.

FTPDOWNLOAD( pathToFile )

Examples:

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

FTPUPLOAD

Nahrá údaje (Collection UInt8 alebo string) do súboru na FTP server.

FTPUPLOAD( pathToFile, data, mode )

Examples:

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

MQTT

Okrem vyššie uvedených možností komunikácie umožňuje systém TapHome aj komunikáciu so zariadeniami tretích strán pomocou protokolu MQTT. MQTT, alebo Message Queuing Telemetry Transport, je ľahký protokol publikovania/odberu správ, ktorý je navrhnutý na efektívnu a spoľahlivú komunikáciu medzi zariadeniami v kontexte Machine-to-machine (M2M) a internetu vecí (IoT).

Na umožnenie komunikácie so zariadeniami tretích strán pomocou MQTT je potrebné vytvoriť samostatný modul v Nastavenia → Hardvér → Pridať nové rozhranie → MQTT Broker. Tento modul funguje ako sprostredkovateľ medzi zariadeniami tretích strán a riadiacou jednotkou a umožňuje im komunikovať pomocou protokolu MQTT. Modul MQTT Broker môže byť spustený autonómne na riadiacej jednotke, čo umožňuje nezávislú a efektívnu komunikáciu medzi zariadeniami tretích strán a systémom TapHome.

MQTTPUBLISH

Funkcia sa používa v zariadeniach PacketParser s protokolom MQTT na publikovanie správy sprostredkovateľovi MQTT.

MQTTPUBLISH( topic, message )

Examples:

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

Listener script

Listener script sa spusti pri prijati každého paketu, konkrétne pri MQTT sa zavolá listener skript vtedy, ak cez MQTT príde akákoľvek správa, ktorej Topic zodpovedá Topic-filtru nastaveného v TapHome;; tých správ môžu byť aj stovky za minútu. Tu je dôležité spomenúť dve veci:

• Topic filter je potrebné nastaviť čo najreštriktívnejšie, aby správy s inou hodnotou Topic vôbec neprichádzali a tým sa neaktivoval listener skript. Napr. ak nás zaujíma iba topic a.b.c.d, filter má byť a.b.c.d, nie iba a.b.
• Niektoré zariadenia produkujú mnoho rôznych správ, ktoré majú rovnaký topic, resp. niekedy musíme nastaviť topic napr. na a.b pretože nás zaujímajú správy a.b.c.d ale aj a.b.x.y, čo sa samozrejme spôsobí, že dorazia aj správy s topic a.b.k.l.m, ktoré nás nezaujímajú. To nie je v zásade zlé, ale niektoré zariadenia generujú rôzne aktualizácie statusu alebo správy, ktoré obsahujú popisy polí iných správ (metadáta) a tie môžu mať aj stovky KB a môžu prichádzať relatívne často - každých pár sekúnd (napr. Zigbee2MQTT).

Kvôli hore spomenutým dôvodom je pri MQTT, v listener skripte, veľmi dôležité na základe hodnoty Topic rozhodnúť, či sa jedná o relevantnú správu a ak nie, okamžite ukončiť vykonávanie skriptu a neanalyzovať vtedy zbytočne obsah správy. Algoritmus v TapHome riadiacej jednotke obsahuje mechanizmy, ako zabrániť zahlteniu MQTT správami. Napriek tomu sa ale nedá vylúčiť, že veľmi voľne nastavený MQTT topic filter a veľké množstvo veľkých správ nespôsobia zvýšenie doby odozvy riadiacej jednotky.

Prijatý paket sa nachádza v premennej (štruktúre) RECEIVEDMSG. Prijaté dáta sa dajú prečítať v premennej RECEIVEDMSG.Payload. Payload má dátový typ BLOB (large binary object), nie je to string ani pole bytov. Pokiaľ je payload typu string, je potrebné použiť funkciu TOSTRING, ale vo všeobecnosti payload môže byť hocičo. RECEIVEDMSG tiež obsahuje údaje špecifické pre protokol, napr. RECEIVEDMSG.Topic pri MQTT. Použitie RECEIVEDMSG.TOPIC je veľmi rýchla a efektívna možnosť ako zistiť hodnotu topic na rozdiel od starého spôsobu kedy sa používalo RECEIVEDBYTES.

Vylepšenia vo verzii 2024.1

Namiesto:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

if parsejson(jsonResponse, "Topic") = "my-topic"

	Va := todouble(parsejson(jsonResponse, "Payload"));

end

sa to dá napísať takto:

if RECEIVEDMSG.TOPIC = "my-topic"

	Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD));

end

V čom je to lepšie - ušetrí sa jedno volanie PARSEJSON na zistenie, aká je hodnota topic. V prípade, že prichádza veľmi veľa mqtt správ a zaujímavé sú len niektoré, je výhodnejšie použiť tento nový spôsob.

RECEIVEDMSG obsahuje ďalej mqtt špecifické hodnoty - napr. CLIENTID, DUP, CONTENTTYPE, EXPIRY - ich obsah závisí od toho, čo posiela mqtt server. Stará syntax stále funguje a bude fungovať.

RECEIVEDMSG funguje aj s TCP a UDP, nielen MQTT. Vtedy poskytuje iba vlastnosti PAYLOAD a LENGTH.

Analýza packetov

Informácie v "Servisných Nastavaniach" Packet Parser modulov obsahujú štatistické údaje o prijatých a odoslaných správach - počty za ostatných 5 a 30 minút, počet prijatých bytov a pre MQTT sú informácie roztriedené podľa MQTT-topic. To by malo pomôcť pri ladení skriptov a nastavení najvhodnejšieho topic filtra, aby sa na Core doručovalo čo najmenej správ, ktoré vôbec nespracováva.