Ruční konfigurace

Implementace v TapHome#

V TapHome je Packet Parser hardwarové rozhraní (Nastavení → Hardware → Přidat nové rozhraní → Packet parser), které slouží k připojení zařízení třetích stran k řídicí jednotce. Tato zařízení mohou komunikovat s řídicí jednotkou buď prostřednictvím Wi-Fi, nebo LAN pomocí protokolu TCP/IP.

Packet Parser používá proprietární skriptovací jazyk, který je speciálně navržen pro systém TapHome. Tento jazyk slouží k řízení a správě připojených zařízení a jejich komunikace s řídicí jednotkou. Více informací o skriptovacím jazyce TapHome najdete zde

Hierarchie#

Systém TapHome používá hierarchickou strukturu pro organizaci připojených zařízení. V této struktuře modul slouží jako nadřazené zařízení a může komunikovat se svými podřízenými zařízeními a ovládat je.

Modul#

Rozhraní může obsahovat jeden nebo více modulů, které ve většině případů pokrývají komunikaci s celým fyzickým zařízením. Z konfiguračního hlediska modul definuje:

• IP adresu nebo jméno mDNS zařízení
• Komunikační port
• Zabezpečené spojení: viz sekce Ověření v nastavení služby modulu
• Ignorovat chyby SSL certifikátu

Zařízení#

Představuje konkrétní řídicí prvek nebo senzor v systému TapHome. Musí vždy patřit do jednoho nadřazeného modulu.

Podporovaná zařízení:

• Digitální výstup
• Analogový výstup
• Termostat
• Vícehodnotový spínač
• Teplotní senzor
• Proměnná
• Tlačítko
• Elektroměr
• Stavový kontakt
• Rolety, markýzy, směšovací ventily
• RGB světlo
• Světlo s nastavitelnou bílou barvou

Příklad: Shelly Plug S
Modul obsahuje informace o IP adrese, má skripty pro čtení stavu, nastavení a provádění servisních akcí. Zahrnuje 2 zařízení: digitální výstup (relé) a elektroměr měřící napájené zařízení.

Skripty pro čtení a zápis#

Řídicí jednotka TapHome a připojená zařízení mohou komunikovat prostřednictvím HTTP nebo HTTPS GET / POST požadavků. Odezvy na tyto požadavky lze analyzovat pomocí sady specializovaných funkcí. Například může existovat funkce určená pro parsování XML odpovědí, další funkce pro parsování JSON odpovědí a další pro parsování odpovědí v poli bajtů. Tyto funkce usnadňují interpretaci a využití informací obdržených v odpovědích, což umožňuje efektivnější komunikaci se řídicí jednotkou a připojenými zařízeními.

TapHome definuje více atributů, které může skriptovací jazyk obsahovat:

• Inicializační skript: spouští se při startu zařízení (např. po restartu řídicí jednotky)
• Skript pro čtení: slouží k nastavování hodnot globálních proměnných nebo čtení stavů chyb
• Skript pro čtení hodnoty: skript pro čtení konkrétní hodnoty (veličiny) z připojeného zařízení (např. nastavená teplota na termostatu nebo naměřená teplota na termostatu)
• Skript pro zápis hodnoty: zapíše hodnotu na připojené zařízení
• Listener skript: provede se při přijetí každé zprávy. Více informací v následující sekci

Více informací o skriptovacím jazyce TapHome najdete zde

Definice stavů chyby ze skriptů#

Servisní atributy a akce#

Skripty a pomocné proměnné na modulu#

Skripty a pomocné proměnné na zařízení#

Více informací naleznete na Modbus dokumentační stránce

Podporované protokoly#

• HTTP
• TCP
• UDP
• FTP
• MQTT

HTTP#

SENDHTTPREQUEST#

Odešle požadavek HTTP ve skriptu Packet parser s protokolem HTTP, počká na odpověď a vrátí objekt httpresponse s Content, StatusCode, ReasonPhrase, IsSuccess a Headers. Požadavek s vlastní metodou, tělem a hlavičkami se sestaví přes HTTPREQUEST — parametry a příklady: SENDHTTPREQUEST, HTTPREQUEST.

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

TCP, UDP#

SENDDATA#

Odešle řetězec nebo collection<uint8> přes TCP nebo UDP; odpověď zařízení se zpracuje v listener skriptu — SENDDATA.

COMPLETESERVICEATTRIBUTE#

V listener skriptu dokončí čtení servisního atributu, jehož skript odeslal požadavek přes SENDDATA — COMPLETESERVICEATTRIBUTE.

COMPLETESERVICEACTION#

V listener skriptu dokončí servisní akci, jejíž skript odeslal požadavek přes SENDDATA — COMPLETESERVICEACTION.

FTP#

FTPDOWNLOAD#

Vrátí obsah souboru na serveru FTP jako collection<uint8> — FTPDOWNLOAD.

FTPUPLOAD#

Zapíše nebo připojí data (řetězec nebo collection<uint8>) do souboru na serveru FTP — FTPUPLOAD.

MQTT#

Kromě výše uvedených komunikačních možností umožňuje systém TapHome také komunikaci se zařízeními třetích stran pomocí protokolu MQTT. MQTT, neboli Message Queuing Telemetry Transport, je lehký protokol pro publikování/odebírání zpráv, navržený pro efektivní a spolehlivou komunikaci mezi zařízeními v kontextech stroj–stroj (M2M) a Internetu věcí (IoT).

Chcete-li umožnit komunikaci se zařízeními třetích stran prostřednictvím MQTT, je nutné vytvořit samostatný modul v Nastavení → Hardware → Přidat nové rozhraní → MQTT Broker. Tento modul slouží jako prostředník mezi zařízeními třetích stran a řídicí jednotkou a umožňuje jim komunikovat prostřednictvím protokolu MQTT. MQTT Broker může běžet autonomně na řídicí jednotce, což umožňuje nezávislou a efektivní komunikaci mezi zařízeními třetích stran a systémem TapHome.

MQTTPUBLISH#

Publikuje zprávu do brokeru MQTT ze zařízení Packet parser s protokolem MQTT — MQTTPUBLISH.

Listener skript#

Listener skript je vyvolán při každém přijetí paketu; zejména pro MQTT je listener skript spuštěn, když dorazí jakákoliv zpráva prostřednictvím MQTT, jejíž Topic odpovídá Filtru tématu nastavenému v TapHome; může jich být i stovky za minutu. Dvě věci, které je třeba zmínit, jsou:

• Filtr tématu musí být nastaven co nejvíce restriktivně, aby zprávy s jinou hodnotou Topic vůbec nedorazily a tím se neaktivoval listener skript. Například pokud nás zajímá pouze téma a.b.c.d, filtr by měl být a.b.c.d, ne jen a.b.

• Některá zařízení produkují mnoho různých zpráv se stejným tématem, nebo občas musíme nastavit téma např. na a.b, protože máme zájem o zprávy a.b.c.d, ale také a.b.x.y, což pochopitelně povede k doručení zpráv s tématem a.b.k.l.m, o které nemáme zájem. To není zásadně špatně, ale některá zařízení generují různá oznámení o stavu nebo zprávy, které obsahují popisy polí jiných zpráv (metadata) a tyto mohou být stovky kB dlouhé a doručovány relativně často – každé několik sekund (např. Zigbee2MQTT).

Z výše uvedených důvodů je v MQTT, v listener skriptu, velmi důležité rozhodovat na základě hodnoty Topic, zda jde o relevantní zprávu, a pokud ne, okamžitě ukončit vykonávání skriptu a zbytečně neanalyzovat obsah zprávy. Algoritmus v řídicí jednotce TapHome obsahuje mechanismy, které brání tomu, aby MQTT bylo zahlceno zprávami. Přesto nelze vyloučit, že velmi volně nastavený filtr tématu MQTT a velké množství velkých zpráv způsobí prodloužení doby odezvy řídicí jednotky.

Přijatá zpráva je v RECEIVEDMSG: Payload je blob (text převedete přes TOSTRING), Topic téma MQTT, Protocol protokol a Length velikost. Čtení RECEIVEDMSG.Topic je rychlý způsob, jak rozhodnout, zda je zpráva relevantní, na rozdíl od staršího RECEIVEDBYTES. Všechny vlastnosti a příklady: Listener skripty.

Vylepšení ve verzi 2024.1#

Namísto:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

lze napsat takto:

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

V čem je to lepší – ušetří se jedno volání PARSEJSON při zjišťování hodnoty tématu. Pokud MQTT přijímá mnoho zpráv a jen některé z nich jsou zajímavé, je pohodlnější použít tento nový způsob.

RECEIVEDMSG dále obsahuje MQTT-specifické hodnoty – např. CLIENTID, DUP, CONTENTTYPE, EXPIRY – jejich obsah závisí na tom, co MQTT server odesílá. Starší syntaxe stále funguje a bude fungovat.

RECEIVEDMSG funguje také s TCP a UDP, nejen s MQTT; tam nese Payload, Length a Protocol ("tcp" nebo "udp") — RECEIVEDMSG.

Analýza paketů#

Informace v nastavení služby modulů Packet Parser obsahují statistické údaje o přijatých a odeslaných zprávách – počty za posledních 5 a 30 minut, počet přijatých bajtů, a pro MQTT jsou informace tříděny podle témat MQTT. To by mělo pomoci při ladění skriptů a nastavení nejvhodnějšího filtru témat tak, aby bylo doručeno co nejméně zpráv, které Core nezpracovává.