doc_tap_packetparser_implementation;

doc_tap_http1;

doc_tap_packetparser_hierarchy;

doc_tap_packetparser_scripts;

doc_tap_packetparser_protocols;

• HTTP

• TCP

• UDP

• FTP

• MQTT

HTTP

SENDHTTPREQUEST

doc_tap_sendhttprequest;

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

doc_tap_senddata;

SENDDATA( string/Collection<UInt8> )

Examples:

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

COMPLETESERVICEATTRIBUTE

doc_tap_completeserviceattribute;

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Examples:

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

COMPLETESERVICEACTION

doc_tap_completeserviceaction;

COMPLETESERVICEACTION( actionName, result )

Examples:

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

FTP

FTPDOWNLOAD

doc_tap_ftpdownload;

FTPDOWNLOAD( pathToFile )

Examples:

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

FTPUPLOAD

doc_tap_ftpupload;

FTPUPLOAD( pathToFile, data, mode )

Examples:

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

MQTT

doc_tap_packetparser_mqtt;

MQTTPUBLISH

doc_tap_mqttpublish;

MQTTPUBLISH( topic, message )

Examples:

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

Listener script

doc_tap_pp_listener_script_description; 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.

doc_tap_pp_listener_script_improvements_heading; Vylepšenia vo verzii 2024.1

doc_tap_pp_listener_script_instead_of; Namiesto:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

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

end

doc_tap_pp_listener_script_new_way; 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.

doc_tap_pp_listener_script_packet_analysis_heading; Analýza packetov

doc_tap_pp_listener_script_packet_analysis_description; Servisné informácie 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.