Manuálna konfigurácia

Implementácia v TapHome#

V TapHome je Packet parser hardvérové rozhranie (Nastavenia → Hardvér → Pridať nové rozhranie → Packet parser), ktoré slúži na pripojenie zariadení tretích strán k ovládacej jednotke. Tieto zariadenia môžu komunikovať s riadiacou jednotkou cez WiFi alebo LAN prostredníctvom TCP/IP protokolu.

Packet parser používa proprietárny skriptovací jazyk, ktorý je špeciálne navrhnutý pre systém TapHome. Tento jazyk sa používa na ovládanie a správu pripojených zariadení a ich komunikácie s riadiacou jednotkou. Kliknite sem pre viac informácií o skriptovacom jazyku TapHome

Hierarchia#

Systém TapHome používa hierarchickú štruktúru na organizáciu pripojených zariadení. V tejto štruktúre modul funguje ako nadradené zariadenie a môže komunikovať so svojimi podriadenými zariadeniami a riadiť 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 mDNS názov zariadenia
• Komunikačný port
• Zabezpečené pripojenie: pozrite sekciu Autentifikácia v nastaveniach služby modulu
• Ignorovanie chýb SSL certifikátu

Zariadenie#

Predstavuje konkrétny riadiaci prvok alebo senzor v systéme TapHome. Musí vždy patriť do jedného nadriadeného modulu.

Podporované zariadenia:

• Digitálny výstup
• Analógový výstup
• Termostat
• Viachodnotový prepínač
• Teplotný senzor
• Premenná
• Tlačidlo
• Elektrický merač
• Reed kontakt
• Žalúzie, markízy, miešané ventily
• RGB svetlo
• Nastaviteľné biele svetlo

Príklad: Shelly Plug S
Modul obsahuje informácie o IP adrese, má skripty na čítanie stavu, nastavovanie a vykonávanie servisných akcií. Zastrešuje 2 zariadenia: digitálny výstup (relé) a merač elektriny merajúci pripojené zariadenia.

Skripty na čí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 je možné analyzovať pomocou súboru špecializovaných funkcií. Napríklad môže existovať funkcia špeciálne navrhnutá na spracovanie XML odpovedí, iná funkcia na spracovanie JSON odpovedí a ďalšia funkcia na spracovanie odpovedí ako poľa bajtov. Tieto funkcie uľahčujú interpretáciu a použitie informácií získaných z odpovedí, čo umožňuje efektívnejšiu komunikáciu s riadiacou jednotkou a pripojenými zariadeniami.

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

• Inicializačný skript: spúšťa sa pri štarte zariadenia (napr. po reštarte riadiacej jednotky)
• Skript na čítanie: slúži na nastavovanie hodnôt globálnych premenných alebo čítanie stavov chýb
• Skript na čítanie hodnoty: skript na čítanie špecifickej hodnoty (množstva) z pripojeného zariadenia (napr. nastavená teplota na termostate alebo nameraná teplota)
• Skript na zápis hodnoty: zapíše hodnotu do pripojeného zariadenia
• Listener skript: vykoná sa pri každom prijatom pakete. Viac informácií v samostatnej sekcii nižšie

Kliknite sem pre viac informácií o skriptovacom jazyku TapHome

Definícia chybových stavov zo skriptov#

Atribúty a akcie služby#

Skripty a pomocné premenné na module#

Skripty a pomocné premenné na zariadení#

Pozrite si viac informácií na stránke dokumentácie Modbusu

Podporované protokoly#

• HTTP
• TCP
• UDP
• FTP
• MQTT

HTTP#

SENDHTTPREQUEST#

Odošle HTTP požiadavku v skripte Packet parsera s protokolom HTTP, počká na odpoveď a vráti objekt httpresponse s vlastnosťami Content, StatusCode, ReasonPhrase, IsSuccess a Headers. Požiadavku s vlastnou metódou, telom a hlavičkami zostaví HTTPREQUEST — parametre a príklady: SENDHTTPREQUEST, HTTPREQUEST.

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

TCP, UDP#

SENDDATA#

Odošle reťazec alebo collection<uint8> cez TCP alebo UDP; odpoveď zariadenia sa spracuje v listener skripte — SENDDATA.

COMPLETESERVICEATTRIBUTE#

V listener skripte dokončí čítanie servisného atribútu, ktorého skript poslal požiadavku cez SENDDATA — COMPLETESERVICEATTRIBUTE.

COMPLETESERVICEACTION#

V listener skripte dokončí servisnú akciu, ktorej skript poslal požiadavku cez SENDDATA — COMPLETESERVICEACTION.

FTP#

FTPDOWNLOAD#

Vráti obsah súboru na FTP serveri ako collection<uint8> — FTPDOWNLOAD.

FTPUPLOAD#

Zapíše alebo pripojí dáta (reťazec alebo collection<uint8>) do súboru na FTP serveri — FTPUPLOAD.

MQTT#

Okrem vyššie uvedených komunikačných možností systém TapHome tiež umožňuje komunikáciu s externými zariadeniami prostredníctvom protokolu MQTT. MQTT, alebo Message Queuing Telemetry Transport, je ľahký publish/subscribe protokol, ktorý je navrhnutý pre efektívnu a spoľahlivú komunikáciu medzi zariadeniami v kontextoch stroj-ku-stroju (M2M) a IoT.

Na umožnenie komunikácie s externými zariadeniami prostredníctvom MQTT je potrebné vytvoriť samostatný modul v Nastavenia → Hardvér → Pridať nové rozhranie → MQTT broker. Tento modul slúži ako prostredník medzi externými zariadeniami a riadiacou jednotkou, čo umožňuje ich komunikáciu cez protokol MQTT. MQTT broker môže bežať samostatne na riadiacej jednotke, čo umožňuje nezávislú a efektívnu komunikáciu medzi externými zariadeniami a systémom TapHome.

MQTTPUBLISH#

Publikuje správu do MQTT brokera zo zariadenia Packet parsera s protokolom MQTT — MQTTPUBLISH.

Listener skript#

Listener skript sa vyvolá pri každom prijatom pakete, špecificky pre MQTT sa listener skript vyvolá pri každej správe, ktorá príde cez MQTT, ktorej téma (Topic) zodpovedá filtru témy nastavenému v TapHome; môže ísť o stovky týchto správ za minútu. Dve veci sú tu dôležité:

• Filter témy musí byť nastavený čo najprísnejšie, aby správy s inou hodnotou témy vôbec nedorazili a tým sa neaktivoval listener skript. Napríklad, ak máme záujem len o tému 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 občas musíme nastaviť tému napr. na a.b, pretože máme záujem o správy a.b.c.d, ale aj a.b.x.y, čo samozrejme spôsobí doručenie správ s témou a.b.k.l.m, o ktoré nemáme záujem. To nie je z princípu zlé, ale niektoré zariadenia generujú rôzne stavy alebo správy obsahujúce popisy polí iných správ (metadáta) a tieto môžu mať stovky kB a prichádzať pomerne často – každých niekoľko sekúnd (napr. Zigbee2MQTT).

Z uvedených dôvodov je pri MQTT v listener skripte veľmi dôležité rozhodovať na základe hodnoty témy, či ide o relevantnú správu, a ak nie, okamžite ukončiť vykonávanie skriptu a zbytočne neanalyzovať obsah správy v danom čase. Algoritmus v riadiacej jednotke TapHome obsahuje mechanizmy na zabránenie zahltenia správ MQTT; napriek tomu nemožno vylúčiť, že príliš voľný filter témy MQTT a veľké množstvo veľkých správ povedú k zvýšeniu odozvy riadiacej jednotky.

Prijatá správa je v RECEIVEDMSG: Payload je blob (text z neho získate cez TOSTRING), Topic téma MQTT, Protocol protokol a Length veľkosť. Čítanie RECEIVEDMSG.Topic je rýchly spôsob, ako rozhodnúť, či je správa relevantná, na rozdiel od staršieho RECEIVEDBYTES. Všetky vlastnosti a príklady: Listener skripty.

Vylepšenia vo verzii 2024.1#

Namiesto:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

sa dá napísať takto:

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

Ako je to lepšie – ušetrí jedno volanie PARSEJSON na zistenie hodnoty témy. Ak prichádza veľa MQTT správ a len niektoré sú zaujímavé, je pohodlnejš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 MQTT server posiela. Stará syntax zostáva funkčná a bude fungovať.

RECEIVEDMSG funguje aj s TCP a UDP, nielen s MQTT; vtedy nesie Payload, Length a Protocol ("tcp" alebo "udp") — RECEIVEDMSG.

Analýza paketov#

Informácie v servisných nastaveniach modulov Packet parsera 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 sú informácie rozdelené podľa tém MQTT. To by malo pomôcť pri ladení skriptov a nastavení najvhodnejšieho filtra témy tak, aby bolo do Core doručených čo najmenej správ, ktoré sa ďalej nespracúvajú.