V TapHome je Packet Parser hardvérové rozhranie (Nastavenia → Hardware → 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 pomocou WiFi alebo LAN prostredníctvom protokolu TCP/IP. Packet Parser používa proprietárny skriptovací jazyk, ktorý je špeciálne navrhnutý pre systém TapHome. Tento jazyk sa používa na riadenie a správu pripojených zariadení a ich komunikáciu s riadiacou jednotkou.

Automatická konfigurácia pomocou šablón#

Na konfiguráciu pripojenia k zariadeniu tretej strany pomocou Packet parsera postupujte nasledovne:

  1. Otvorte aplikáciu TapHome a prejdite na Nastavenia → Hardware → Packet parser.
  2. V sekcii analyzátora paketov uvidíte možnosť „Stiahnuť šablóny“, ktorá aktualizuje šablóny v aplikácii z verejného GitHub repozitára GitHub repository. Potom už len vyberiete špecifickú šablónu. Alebo vyberte „Pridať zo súboru“, ak ste si v aplikácii TapHome vygenerovali vlastnú šablónu (formát XML).
  3. Vyplňte základné atribúty pripojenia (IP adresa alebo skôr mDNS názov) a vyberte, ktoré zariadenia sa majú vytvoriť.
  4. Kliknite na „Vytvoriť“ a modul so zariadeniami sa vytvorí podľa definície šablóny. Gratulujeme! Práve ste úspešne nakonfigurovali pripojenie k zariadeniu tretej strany pomocou Packet parsera!

Pozor: šablóny nedefinujú žiadne automatické akcie (Smart Rules).

Manuálna konfigurácia#

Hierarchia#

Systém TapHome používa hierarchickú štruktúru na organizovanie pripojených zariadení. V tejto štruktúre Modul funguje ako nadradené zariadenie a môže komunikovať s a ovládať svoje podradené zariadenia.

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 konfiguračného hľadiska Modul definuje:

  • IP adresu alebo mDNS názov zariadenia
  • Komunikačný port
  • Zabezpečené pripojenie: Pozri sekciu Autentifikácia v Servisných nastaveniach Modulu
  • Ignorovať chyby certifikátu SSL

Zariadenie#

Predstavuje špecifický riadiaci prvok alebo senzor 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
  • Viachodnotový prepínač
  • Teplotný senzor
  • Premenná
  • Tlačidlo
  • Elektromer
  • Jazýčkový kontakt
  • Žalúzie, markízy, zmiešavacie ventily
  • RGB Svetlo
  • Laditeľné biele svetlo

Príklad: Shelly Plug S#

Modul obsahuje informácie o IP adrese, má skripty na čítanie stavu, nastavenia a vykonávanie servisných akcií. Pokrýva 2 zariadenia: digitálny výstup (relé) a elektromer merajúci dodávané zariadenia.

Skripty pre čí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 môžu byť parsované pomocou špecializovaných funkcií:

  • Funkcia pre parsovanie XML odpovedí
  • Funkcia pre parsovanie JSON odpovedí
  • Funkcia pre parsovanie odpovedí vo forme bajtového poľa

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

  • Inicializačný skript – Spustí sa, keď sa zariadenie spustí (napr. po reštarte riadiacej jednotky).
  • Skript na čítanie – Nastavuje hodnoty globálnych premenných alebo číta chybové stavy.
  • Skript na čítanie hodnoty – Skript na čítanie špecifickej hodnoty (napr. nastavená teplota na termostate alebo meraná teplota na termostate).
  • Skript na zápis hodnoty – Zapíše hodnotu do pripojeného zariadenia.
  • Skript poslucháča – Spustí sa pri prijatí každého paketu (Viac informácií v samostatnej sekcii nižšie).

Podporované protokoly#

  • HTTP
  • TCP
  • UDP
  • FTP
  • MQTT

HTTP#

SENDHTTPREQUEST#

Odošle HTTP požiadavku so špecifikovanými parametrami, počká na odpoveď a vráti JSON reťazec obsahujúci hodnoty ako Content, Headers, HTTP result code.

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

SENDHTTPREQUEST("/getValue")  
Result:
{
  "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é dáta (reťazec alebo Collection UInt8) pomocou TCP alebo UDP protokolu. Ak sú dáta objekt typu string, implicitne sa konvertujú na bajty pomocou ISO-8859-1 kódovania. Táto funkcia je podporovaná iba v skriptoch Packet parsera s TCP alebo UDP protokolom. Prijaté bajty môžu byť spracované v Listener skripte.

SENDDATA( string/Collection )

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

COMPLETESERVICEATTRIBUTE#

Funkcia sa používa v skriptoch Listener v Packet parseri s protokolom TCP/UDP na oznámenie dokončenia požiadavky hodnoty atribútu služby. Napr. vytvoríte požiadavku v skripte atribútu služby pomocou funkcie SENDDATA a po prijatí dát v skripte listenera dokončíte čítanie atribútu služby.

COMPLETESERVICEATTRIBUTE( attributeName, value, error ) Examples:

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

COMPLETESERVICEACTION#

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

COMPLETESERVICEACTION( actionName, result ) Examples:

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

FTP#

FTPDOWNLOAD#

Vráti dáta súboru (ako Collection UInt8) z FTP servera. Funkcia je podporovaná iba v Packet parser skriptoch s FTP protokolom.

FTPDOWNLOAD( pathToFile ) Examples:

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

FTPUPLOAD#

Nahrá dáta (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 systém TapHome umožňuje aj komunikáciu so zariadeniami tretích strán pomocou protokolu MQTT. MQTT, alebo Message Queuing Telemetry Transport, je odľahčený publish/subscribe messaging protokol, ktorý je navrhnutý pre efektívnu a spoľahlivú komunikáciu medzi zariadeniami v kontextoch machine-to-machine (M2M) a Internet of Things (IoT) contexts.

Pre umožnenie komunikácie so zariadeniami tretích strán pomocou MQTT je potrebné vytvoriť samostatný modul v Nastavenia → Hardware → Pridať nové rozhranie → MQTT Broker. Tento modul funguje ako sprostredkovateľ medzi zariadeniami tretích strán a riadiacou jednotkou, čo im umožňuje komunikovať pomocou protokolu MQTT. MQTT Broker môže bežať 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 na zariadeniach PacketParser s protokolom MQTT na publikovanie správy do MQTT brokera.

MQTTPUBLISH( topic, message ) Príklad:

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

Listener script#

Skript poslucháča sa vyvolá pri prijatí každého paketu, konkrétne pre MQTT sa skript poslucháča vyvolá, keď príde akákoľvek správa cez MQTT, ktorej téma (Topic) zodpovedá filtru tém nastavenému v TapHome;; týchto správ môžu byť stovky za minútu. Dve veci sú dôležité:

  • Filter tém je potrebné nastaviť čo najprísnejšie, aby správy s inou hodnotou témy vôbec neprišli a tým neaktivovali skript poslucháča. Napríklad, ak nás zaujíma iba téma 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 niekedy musíme nastaviť tému napr. na a.b, pretože nás zaujímajú správy a.b.c.d, ale aj a.b.x.y, čo samozrejme spôsobí príchod správ s témou a.b.k.l.m, ktoré nás nezaujímajú. To v zásade nie je zlé, ale niektoré zariadenia generujú rôzne aktualizácie stavu alebo správy, ktoré obsahujú popisy polí iných správ (metadata), a tieto môžu byť dlhé stovky KB a prichádzať relatívne často - každých pár sekúnd (napr. Zigbee2MQTT). Z vyššie uvedených dôvodov je v MQTT v skripte poslucháča veľmi dôležité na základe hodnoty Témy rozhodnúť, či ide o relevantnú správu, a ak nie, okamžite zastaviť vykonávanie skriptu a zbytočne v tom čase neanalyzovať obsah správy. Algoritmus v riadiacej jednotke TapHome obsahuje mechanizmy na zabránenie preťaženiu MQTT správami. Napriek tomu nemožno 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 môžu byť čítané 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 reťazec, musí sa použiť funkcia TOSTRING, ale vo všeobecnosti môže byť payload čokoľvek. RECEIVEDMSG obsahuje aj 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ého spôsobu, keď 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

Čím je to lepšie - ušetrí sa jedno volanie PARSEJSON na zistenie hodnoty témy. Ak prichádza veľa mqtt správ a iba niektoré z nich sú zaujímavé, je výhodnejš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 posiela mqtt server. Stará syntax stále funguje a bude fungovať.

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

Analýza paketov#

Informácie v Service Settings modulov Packet Parser 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, informácie sú zoradené podľa MQTT tém. To by malo pomôcť pri ladení skriptov a nastavení najvhodnejšieho filtra tém, aby sa zabezpečilo, že sa doručí čo najmenej správ, ktoré nie sú spracované Core.

Údaje o počasí#

TapHome umožňuje sťahovanie bezplatných údajov o počasí do aplikácie.

  • Prispôsobte výkon kúrenia/chladenia na základe vonkajšej teploty
  • Rozhodnite, či sa má spustiť zavlažovanie v závislosti od predpovede dažďa
  • Načítajte viac energie z fotovoltaických panelov do batérie, ak sa predpovedá oblačnosť
  • Chráňte žalúzie alebo markízy v závislosti od smeru vetra

Nastavenie#

  • Zaregistrujte sa na https://home.openweathermap.org/users/sign_up. Kliknite na odkaz na potvrdenie účtu v e-maile, ktorý dostanete.
  • Potom dostanete ďalší e-mail, ktorý obsahuje váš osobný API kľúč. Skopírujte ho do schránky.
  • Otvorte aplikáciu TapHome a prejdite do Menu → Settings → Hardware → Add new interface → Packet parser → Add from template → OpenWeather.
  • Vložte API kľúč do príslušného poľa. Zadajte aj správnu zemepisnú šírku a dĺžku pre umiestnenie inštalácie

MQTT Broker#

MQTT Broker je služba pre správu MQTT komunikácie medzi zariadeniami. Broker môže byť spustený na externej mašine alebo priamo na TapHome kontroléri.

Ako aktivovať MQTT Broker v TapHome#

  • Prejdite do Settings -> Hardware a potom vyberte MQTT Broker.
  • V nastaveniach MQTT Broker môže užívateľ zadať informácie ako číslo portu, prefix ID klienta, užívateľa a heslo.
  • Po zadaní týchto informácií a uložení nastavení je MQTT Broker pripravený na použitie. Konfigurácia MQTT komunikácie je definovaná v Hardware -> Packet parser
Backward Viac elektromerov na 1 zbernici Velux Forward