Packet parser functions

Packet parser functions talk to devices over HTTP, TCP, UDP, MQTT and FTP. They work only in the scripts of a Packet parser module or device whose protocol matches the function; elsewhere the script stops with PacketParserFunction - PacketParserContext is null. All of them need Core 2022.2 or newer. Setting up a Packet parser module is described in Packet parser; incoming messages are handled in Listener scripts, and Modbus devices have their own Modbus functions.

Protocols and scripts#

Each protocol has its own functions and a typical split of work between the scripts.

Example — one HTTP request for all devices of a module

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

PARSEJSON(StatusJson, "temperature");

The first script is the module read script, the second a device read script; StatusJson is a module variable.

HTTPREQUEST#

HTTPREQUEST builds an httprequest value whose path, method, body and headers can be changed before it is sent with SENDHTTPREQUEST.

1

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

Remarks — The default method is GET. The properties PATH, METHOD, BODY and HEADERS can be read and written; HEADERS is a collection of "Name: value" strings. The function only creates a value, so it works in every script.

Example

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

SENDHTTPREQUEST#

SENDHTTPREQUEST sends an HTTP request, waits for the answer and returns it as an httpresponse value with the properties Content, StatusCode, ReasonPhrase, IsSuccess and Headers.

1
2

SENDHTTPREQUEST(path [, method [, body [, header1, header2, …]]])
SENDHTTPREQUEST(request)

Returns — httpresponse:

Remarks — Only for a module with the HTTP protocol. The response may have at most 128 kB.

Example

VAR response := SENDHTTPREQUEST("/status", "GET");
IF response.IsSuccess
    StatusJson := response.Content;
ELSE
    ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END

SENDHTTPREQUEST("/doSomething", "POST", "someData", "header1: value1", "header2: value2");

Errors — Response is too long (Nbytes). Maximum supported length is 128KB; PacketParserFunction - unable to use ‘SENDHTTPREQUEST’ with … (the module uses another protocol).

SENDDATA#

SENDDATA sends a string or a byte collection over TCP or UDP and returns TRUE; the answer arrives in the listener script.

1

SENDDATA(data)

Remarks — A string is sent as iso-8859-1 bytes. A collection must be a collection<uint8>. Incoming data is delivered to the listener script in chunks of at most 4096 bytes.

Example

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

MQTTPUBLISH#

MQTTPUBLISH publishes a message with the given topic to the MQTT broker of the module and returns Null.

1

MQTTPUBLISH(topic, data)

Remarks — data is a string or a collection<uint8>. An error reported by the broker stops the script with its text. The broker is set up in MQTT Broker.

Example

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

FTPDOWNLOAD#

FTPDOWNLOAD downloads a file from the FTP server of the module and returns its content as a byte collection (collection<uint8>).

1

FTPDOWNLOAD(path)

Example

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

FTPUPLOAD#

FTPUPLOAD writes data to a file on the FTP server of the module — replacing the file with "write" (default) or adding to its end with "append".

1

FTPUPLOAD(path, data [, mode])

Remarks — data is a string or a collection<uint8>. mode must be lower case.

Example

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

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

COMPLETESERVICEATTRIBUTE#

COMPLETESERVICEATTRIBUTE delivers the value of a service attribute to the app from a TCP or UDP listener script, after the attribute script has sent the request with SENDDATA.

1

COMPLETESERVICEATTRIBUTE(name, value [, error])

Remarks — name is the name of the service attribute. With error the attribute shows the error text instead of a value. Returns Null.

Example

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

COMPLETESERVICEACTION#

COMPLETESERVICEACTION reports the result of a service action to the app from a TCP or UDP listener script, after the action script has sent the request with SENDDATA.

1

COMPLETESERVICEACTION(name, result)

Example

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

Errors — No service action with name X.

See also — Listener scripts, Parsing functions, Data type conversions.