TapHome

Funcții Packet parser

Funcțiile Packet parser din scripturile TapHome — HTTPREQUEST, SENDHTTPREQUEST, SENDDATA, MQTTPUBLISH, FTPDOWNLOAD, FTPUPLOAD, COMPLETESERVICEATTRIBUTE și COMPLETESERVICEACTION — pentru HTTP, TCP, UDP, MQTT și FTP.

Ultima actualizare:

Funcțiile Packet parser comunică cu dispozitivele prin HTTP, TCP, UDP, MQTT și FTP. Funcționează doar în scripturile unui modul sau dispozitiv Packet parser al cărui protocol corespunde funcției; în rest scriptul se oprește cu PacketParserFunction - PacketParserContext is null. Toate necesită Core 2022.2 sau mai nou. Configurarea unui modul Packet parser este descrisă în Packet parser; mesajele primite se tratează în Scripturi listener, iar dispozitivele Modbus au propriile funcții Modbus.

Protocoale și scripturi

Fiecare protocol are propriile funcții și o împărțire tipică a muncii între scripturi.

ProtocolFuncțiiScripturi tipice
HTTPHTTPREQUEST, SENDHTTPREQUESTScriptul de citire al modulului trimite o singură cerere și stochează răspunsul într-o variabilă a modulului; scripturile de citire ale dispozitivelor îl parsează.
TCP, UDPSENDDATAScripturile de citire sau de scriere trimit o cerere; răspunsul sosește în scriptul listener.
MQTTMQTTPUBLISHScriptul listener prelucrează mesajele primite; scriptul de scriere publică comenzile.
FTPFTPDOWNLOAD, FTPUPLOADScripturile de citire și de scriere transferă fișiere.

Exemplu — o singură cerere HTTP pentru toate dispozitivele unui modul

VAR response := SENDHTTPREQUEST("/status", "GET");
StatusJson := response.Content;
PARSEJSON(StatusJson, "temperature");

Primul script este scriptul de citire al modulului, al doilea un script de citire al unui dispozitiv; StatusJson este o variabilă a modulului.

HTTPREQUEST

HTTPREQUEST construiește o valoare httprequest a cărei cale, metodă, corp și antete se pot modifica înainte de trimiterea ei cu SENDHTTPREQUEST.

1
HTTPREQUEST(path [, method [, body]])

Observații — Metoda implicită este GET. Proprietățile PATH, METHOD, BODY și HEADERS se pot citi și scrie; HEADERS este o colecție de șiruri "Name: value". Funcția doar creează o valoare, așa că funcționează în orice script.

Exemplu

VAR request := HTTPREQUEST("/api/v1/state", "POST", "{\"on\":true}");
request.HEADERS := {"Content-Type: application/json", "Authorization: Bearer " + token};
VAR response := SENDHTTPREQUEST(request);

SENDHTTPREQUEST

SENDHTTPREQUEST trimite o cerere HTTP, așteaptă răspunsul și îl returnează ca valoare httpresponse cu proprietățile Content, StatusCode, ReasonPhrase, IsSuccess și Headers.

1
2
SENDHTTPREQUEST(path [, method [, body [, header1, header2, …]]])
SENDHTTPREQUEST(request)
NumeTipDescriere
pathșir de caractereCalea pe dispozitivul setat în modul, de exemplu "/status".
methodșir de caractere, opționalGET (implicit), POST, PUT, …
bodyșir de caractere, opționalCorpul cererii.
header1 …șir de caractere, opționalPână la 27 de antete în forma "Name: value".
requesthttprequestO cerere construită cu HTTPREQUEST.

Returnează — httpresponse:

ProprietateSemnificație
ContentCorpul răspunsului ca text.
StatusCodeCodul de stare HTTP, de exemplu 200.
ReasonPhraseTextul stării, de exemplu OK.
IsSuccessTRUE pentru codurile de stare 200 – 299.
HeadersAntetele răspunsului ca text JSON — un tablou de {"Key": …, "Value": [ … ]} — care se poate citi cu PARSEJSON.

Observații — Doar pentru un modul cu protocolul HTTP. Răspunsul poate avea cel mult 128 kB.

Exemplu

VAR response := SENDHTTPREQUEST("/status", "GET");   # trimiterea cererii
IF response.IsSuccess
    StatusJson := response.Content;   # la succes salvează corpul răspunsului
ELSE
    ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");   # la eroare raportează codul de stare
END
SENDHTTPREQUEST("/doSomething", "POST", "someData", "header1: value1", "header2: value2");

Erori — Response is too long (Nbytes). Maximum supported length is 128KB; PacketParserFunction - unable to use ‘SENDHTTPREQUEST’ with … (modulul folosește alt protocol).

SENDDATA

SENDDATA trimite un șir de caractere sau o colecție de octeți prin TCP sau UDP și returnează TRUE; răspunsul sosește în scriptul listener.

1
SENDDATA(data)

Observații — Un șir de caractere se trimite ca octeți iso-8859-1. O colecție trebuie să fie collection<uint8>. Datele primite se livrează scriptului listener în fragmente de cel mult 4096 de octeți.

Exemplu

SENDDATA(BYTECOLLECTION("0a dd ef a2"));
SENDDATA("STATUS?\r\n");

MQTTPUBLISH

MQTTPUBLISH publică un mesaj cu topicul dat către brokerul MQTT al modulului și returnează Null.

1
MQTTPUBLISH(topic, data)

Observații — data este un șir de caractere sau o collection<uint8>. O eroare raportată de broker oprește scriptul cu textul ei. Brokerul se configurează în MQTT Broker.

Exemplu

MQTTPUBLISH("shellies/" + plugTopic + "/relay/0/command", IF(St > 0, "on", "off"));

FTPDOWNLOAD

FTPDOWNLOAD descarcă un fișier de pe serverul FTP al modulului și returnează conținutul lui ca o colecție de octeți (collection<uint8>).

1
FTPDOWNLOAD(path)

Exemplu

VAR data := FTPDOWNLOAD("/export/values.csv");
VAR csv := TOSTRING(data, "utf-8");

FTPUPLOAD

FTPUPLOAD scrie date într-un fișier de pe serverul FTP al modulului — înlocuiește fișierul cu "write" (implicit) sau adaugă la sfârșitul lui cu "append".

1
FTPUPLOAD(path, data [, mode])

Observații — data este un șir de caractere sau o collection<uint8>. mode trebuie scris cu litere mici.

Exemplu

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

Erori — FTPUPLOAD - invalid argument, upload mode must be ‘append’ or ‘write’.

COMPLETESERVICEATTRIBUTE

COMPLETESERVICEATTRIBUTE livrează aplicației valoarea unui atribut de service dintr-un script listener TCP sau UDP, după ce scriptul atributului a trimis cererea cu SENDDATA.

1
COMPLETESERVICEATTRIBUTE(name, value [, error])

Observații — name este numele atributului de service. Cu error, atributul afișează textul erorii în loc de o valoare. Returnează Null.

Exemplu

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

COMPLETESERVICEACTION

COMPLETESERVICEACTION raportează aplicației rezultatul unei acțiuni de service dintr-un script listener TCP sau UDP, după ce scriptul acțiunii a trimis cererea cu SENDDATA.

1
COMPLETESERVICEACTION(name, result)

Exemplu

COMPLETESERVICEACTION("Reboot", "Rebooted successfully");

Erori — No service action with name X.

Consultați și — Scripturi listener, Funcții de parsare, Conversii de tipuri de date.