Manuální konfigurace

Implementace v TapHome

V systému TapHome je Packet Parser hardwarové rozhraní ( Nastavení → Hardware → Přidat nové rozhraní → Packet parser ), které se používá pro připojení zařízení třetích stran k řídící jednotce. Tato zařízení mohou komunikovat s řídicí jednotkou buď pomocí WiFi nebo LAN přes protokol TCP/IP.

Packet Parser používá proprietární skriptovací jazyk, který je speciálně navržen pro systém TapHome. Tento jazyk slouží k ovládání a správě připojených zařízení a jejich komunikaci s řídící jednotkou. Kliknutím sem získáte další informace o TapHome skriptovacím jazyce

Hierarchie

Systém TapHome používá hierarchickou strukturu k uspořádání připojených zařízení. V této struktuře modul funguje jako nadřazené zařízení a může komunikovat se svými podřazený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 hlediska konfigurace Modul definuje:

• IP adresu nebo název mDNS zařízení
• komunikační port
• Zabezpečené připojení : Viz oddíl Autentizace v Servisní nastavení Modulu
• Ignorovat chyby certifikátu SSL

Zařízení

Představuje konkrétní ovládací prvek nebo snímač v systému TapHome. Musí být vždy součástí jednoho nadřazeného Modulu.

Podporovaná zařízení:

• Digitální výstup
• Analogový výstup
• Termostat
• Více hodnotový spínač
• Tepelný senzor
• Proměnná
• Tlačítko
• Elektroměr
• Stavový kontakt
• Rolety, markýzy, směšovací ventily
• RGB Světlo
• Tunable white light

Skripty pro čtení a zápis

Řídící jednotka TapHome a připojená zařízení mohou komunikovat pomocí požadavků HTTP nebo HTTPS GET / POST. Odpovědi na tyto požadavky lze analyzovat pomocí souboru specializovaných funkcí. Například může existovat funkce, která je speciálně určena pro rozbor odpovědí XML, další funkce pro rozbor odpovědí JSON a ještě další funkce pro rozbor odpovědí pole bajtů. Tyto funkce usnadňují interpretaci a používání informací přijatých v odpovědích, což umožňuje efektivnější a účinnější komunikaci s řídící jednotkou a připojenými zařízeními.

TapHome definuje více atributů, které mohou obsahovat jazyk skriptu:

• Initialize script: se spustí při spuštění zařízení (např. po restartu řídící jednotky)
• Read skriptu: nastavení hodnot globálních proměnných nebo čtení chybových stavů
• Read value script: 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)
• Write value script: zápis hodnoty do připojeného zařízení
• Listener script: spouští se při přijetí každého packetu. Více info v samostatné sekci níže

Podporované protokoly

• HTTP

• TCP

• UDP

• FTP

• MQTT

HTTP

SENDHTTPREQUEST

Odešle HTTP požadavek se zadanými parametry, počká na odpověď a vrátí odpověď jako řetězec JSON s hodnotami jako Obsah, Hlavičky, Výsledný kód HTTP. Funkce je podporována pouze v Packet parser skriptech s protokolem 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

Odešle zadaná data (řetězec nebo Collection UInt8) pomocí protokolu TCP nebo UDP. Jsou-li data objektem řetězce, jsou implicitně konvertována na bajty pomocí kódování iso-8859-1. Funkce je podporována pouze ve skriptech Packet parseru s protokolem TCP nebo UDP. Přijaté bajty lze zpracovat v Listener skriptu.

SENDDATA( string/Collection<UInt8> )

Examples:

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

COMPLETESERVICEATTRIBUTE

Funkce se používá v Listener skriptech TCP/UDP Packet parseru pro oznámení ukončení požadavku na hodnotu Servisního atributu.
Např. vytvoříte požadavek ve skriptu Servisního atributu pomocí funkce SENDDATA a po přijetí údajů v Listener skriptu dokončíte čtení Servisního atributu.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Examples:

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

COMPLETESERVICEACTION

Funkce se používá v Listener skriptech v Packet parseru s protokolem TCP/UDP pro oznámení dokončení požadavku na Servisní akci. Např. vytvoříte požadavek ve skriptu Servisní akce pomocí funkce SENDDATA a po přijetí údajů v Listener skriptu dokončíte Servisní akci.

COMPLETESERVICEACTION( actionName, result )

Examples:

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

FTP

FTPDOWNLOAD

Vrátí údaje o souboru (jako Collection UInt8) z FTP serveru. Funkce je podporována pouze v Packet parser skriptech s protokolem FTP.

FTPDOWNLOAD( pathToFile )

Examples:

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

FTPUPLOAD

Nahraje data (Collection UInt8 nebo string) do souboru 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

Kromě výše uvedených možností komunikace 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 snadný protokol publikování/odběru zpráv, který je navržen pro efektivní a spolehlivou komunikaci mezi zařízeními v kontextu Machine-to-machine (M2M) a internetu věcí (IoT).

Pro umožnění komunikace se zařízeními třetích stran pomocí MQTT je třeba vytvořit samostatný modul v Nastavení → Hardware → Přidat nové rozhraní → MQTT Broker. com/support/2331377665). Tento modul funguje jako zprostředkovatel mezi zařízeními třetích stran a řídící jednotkou a umožňuje jim komunikovat pomocí protokolu MQTT. Modul MQTT Broker může být spuštěn autonomně na řídící jednotce, což umožňuje nezávislou a efektivní komunikaci mezi zařízeními třetích stran a systémem TapHome.

MQTTPUBLISH

Funkce se používá v zařízeních PacketParser s protokolem MQTT pro publikování zprávy zprostředkovateli MQTT.

MQTTPUBLISH( topic, message )

Examples:

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

Listener script

Listener script se spustí při přijetí každého paketu, konkrétně u MQTT se zavolá listener skript tehdy, pokud přes MQTT přijde jakákoliv zpráva, které Topic odpovídá Topic-filtru nastaveného v TapHome; těch zpráv mohou být i stovky za minutu. Zde je důležité zmínit dvě věci:

• Topic filtr je třeba nastavit co nejrestriktivněji, aby zprávy s jinou hodnotou Topic vůbec nepřicházely a tím se neaktivoval listener skript. Např. pokud nás zajímá pouze topic a.b.c.d, filtr má být a.b.c.d, ne pouze a.b.
• Některá zařízení produkují mnoho různých zpráv, které mají stejný topic, resp. někdy musíme nastavit topic například. na a.b protože nás zajímají zprávy a.b.c.d ale také a.b.x.y, což se samozřejmě způsobí, že dorazí i zprávy s topic a.b.k.l.m, které nás nezajímají. To není v zásadě špatné, ale některá zařízení generují různé aktualizace statusu nebo zprávy, které obsahují popisy polí jiných zpráv (metadata) a ty mohou mít i stovky KB a mohou přicházet relativně často – každých pár sekund (např. Zigbee2MQTT).

Kvůli výše zmíněným důvodem je u MQTT, v listener skriptu, velmi důležité na základě hodnoty Topic rozhodnout, zda se jedná o relevantní zprávu a ne-li, okamžitě ukončit provádění skriptu a neanalyzovat tehdy zbytečně obsah zprávy. Algoritmus v TapHome řídicí jednotce obsahuje mechanismy, jak zabránit zahlcení MQTT zprávami. Přesto nelze vyloučit, že velmi volně nastavený MQTT topic filtr a velké množství velkých zpráv nezpůsobí zvýšení doby odezvy řídící jednotky.

Přijatý paket se nachází v proměnné (struktuře) RECEIVEDMSG. Přijatá data lze přečíst v proměnné RECEIVEDMSG.Payload. Payload má datový typ BLOB (large binary object), není to string ani pole bytů. Pokud je payload typu string, je třeba použít funkci TOSTRING, ale obecně payload může být cokoli. RECEIVEDMSG také obsahuje údaje specifické pro protokol, například. RECEIVEDMSG.Topic při MQTT. Použití RECEIVEDMSG.TOPIC je velmi rychlá a efektivní možnost jak zjistit hodnotu topic na rozdíl od starého způsobu kdy se používalo RECEIVEDBYTES.

Vylepšení ve verzi 2024.1

Namísto:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

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

end

se to dá 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 ke zjištění, jaká je hodnota topic. V případě, že přichází velmi mnoho mqtt zpráv a zajímavé jsou jen některé, je výhodnější použít tento nový způsob.

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

RECEIVEDMSG funguje také s TCP a UDP, nejen MQTT. Tehdy poskytuje pouze vlastnosti PAYLOAD a LENGTH.

Analýza packetů

Informace v Servisních Nastaveních 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 rozděleny podle MQTT-topic. To by mělo pomoci při ladění skriptů a nastavení nejvhodnějšího topic filtru, aby se na Core doručovalo co nejméně zpráv, které vůbec nezpracovává.