Manual configuration

Implementation in TapHome#

In TapHome, the Packet Parser is a hardware interface (Settings → Hardware → Add new interface → Packet parser) that is used to connect third-party devices to the controller. These devices can communicate with the control unit using either WiFi or LAN via TCP/IP protocol.

The Packet Parser uses a proprietary scripting language that is specifically designed for the TapHome system. This language is used to control and manage the connected devices and their communication with the controller. Click here for more information on the TapHome scripting language

Hierarchy#

TapHome system uses a hierarchical structure for organizing the connected devices. In this structure, a Module acts as a parent device and can communicate with and control its child devices.

Module#

An interface can contain one or more modules, which in most cases cover communication with the entire physical device. From a configuration point of view, the Module defines:

• IP address or mDNS name of a device
• Communication port
• Secure connection: See section Authentication in Service settings of a Module
• Ignore SSL certificate errors

Device#

Represents a specific control element or sensor in the TapHome system. It must always be part of one parent Module.

Supported devices:

• Digital output
• Analog output
• Thermostat
• Multi-Value Switch
• Temperature sensor
• Variable
• Push button
• Electric meter
• Reed Contact
• Shutters, awnings, mix valves
• RGB Light
• Tunable white light

Example: Shelly Plug S The module contains information about the IP address, it has scripts for reading the status, settings, and performing service actions. It covers 2 devices: a digital output (relay) and an electricity meter measuring the supplied devices.

Scripts for reading and writing#

TapHome control unit and the connected devices can communicate using HTTP or HTTPS GET / POST requests. The responses to these requests can be parsed using a set of specialized functions. For example, there may be a function that is specifically designed to parse XML responses, another function for parsing JSON responses, and yet another function for parsing byte array responses. These functions make it easier to interpret and use the information received in the responses, allowing for more efficient and effective communication with the control unit and connected devices.

TapHome defines multiple attributes that can contain script language:

• Initialize script: is run when the device starts (e.g. after the control unit is restarted)
• Read script: setting values of global variables or reading error states
• Read Value script: script for reading a specific value (quantity) from a connected device (e.g. set temperature on the thermostat or measured temperature on the thermostat)
• Write Value script: write the value to the connected device
• Listener script: is executed when each packet is received. More info in a separate section below

Click here for more information on the TapHome scripting language

Definition of error states from scripts#

Service attributes and actions#

Scripts and auxiliary variables on the module#

Scripts and helper variables on the device#

See more info on Modbus documentation page

Supported protocols#

• HTTP
• TCP
• UDP
• FTP
• MQTT

HTTP#

SENDHTTPREQUEST#

Sends an HTTP request in a Packet parser script with the HTTP protocol, waits for the answer and returns an httpresponse object with Content, StatusCode, ReasonPhrase, IsSuccess and Headers. A request with its own method, body and headers is built with HTTPREQUEST — parameters and examples: SENDHTTPREQUEST, HTTPREQUEST.

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

TCP, UDP#

SENDDATA#

Sends a string or a collection<uint8> over TCP or UDP; the device’s answer is processed in the listener script — SENDDATA.

COMPLETESERVICEATTRIBUTE#

In the listener script, completes the read of a service attribute whose script sent the request with SENDDATA — COMPLETESERVICEATTRIBUTE.

COMPLETESERVICEACTION#

In the listener script, completes a service action whose script sent the request with SENDDATA — COMPLETESERVICEACTION.

FTP#

FTPDOWNLOAD#

Returns the content of a file on the FTP server as a collection<uint8> — FTPDOWNLOAD.

FTPUPLOAD#

Writes or appends data (a string or a collection<uint8>) to a file on the FTP server — FTPUPLOAD.

MQTT#

In addition to the communication options mentioned above, the TapHome system also allows for communication with third-party devices using the MQTT protocol. MQTT, or Message Queuing Telemetry Transport, is a lightweight publish/subscribe messaging protocol that is designed for efficient and reliable communication between devices in machine-to-machine (M2M) and Internet of Things (IoT) contexts.

To enable communication with third-party devices using MQTT, it is necessary to create a separate module in Settings → Hardware → Add new interface → MQTT Broker. This module acts as an intermediary between the third-party devices and the control unit, allowing them to communicate using the MQTT protocol. The MQTT Broker can be run autonomously on the control unit, allowing for independent and efficient communication between the third-party devices and the TapHome system.

MQTTPUBLISH#

Publishes a message to the MQTT broker from a Packet parser device with the MQTT protocol — MQTTPUBLISH.

Listener script#

The listener script is invoked when each packet is received, specifically for MQTT the listener script is invoked when any message arrives via MQTT whose Topic matches the Topic-filter set in TapHome; there can be hundreds of these messages per minute. Two things are important to mention here:

• The Topic filter needs to be set as restrictive as possible, so that messages with a different Topic value do not arrive at all and thus do not activate the listener script. For example, if we are only interested in topic a.b.c.d, the filter should be a.b.c.d, not just a.b.

• Some devices produce many different messages that have the same topic, or sometimes we have to set the topic e.g. to a.b because we are interested in messages a.b.c.d but also a.b.x.y, which of course will cause messages with topic a.b.k.l.m that we are not interested in to arrive as well. This is not bad in principle, but some devices generate various status updates or messages that contain field descriptions of other messages (metadata), and these can be hundreds of KB long and arrive relatively frequently - every few seconds (e.g., Zigbee2MQTT).

Because of the reasons mentioned above, in MQTT, in a listener script, it is very important to decide based on the Topic value whether it is a relevant message and if not, to stop the script execution immediately and not to analyze the message content unnecessarily at that time. The algorithm in the TapHome controller contains mechanisms to prevent MQTT from being overwhelmed by messages. Nevertheless, it cannot be ruled out that a very loosely set MQTT topic filter and a large number of large messages will cause an increase in the response time of the controller.

The received message is in RECEIVEDMSG: Payload is a blob (convert text with TOSTRING), Topic the MQTT topic, Protocol the protocol and Length the size. Reading RECEIVEDMSG.Topic is a fast way to decide whether a message is relevant, unlike the older RECEIVEDBYTES. All properties and examples: Listener scripts.

Improvements in version 2024.1#

Instead of:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

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

it can be written like this:

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

How is this better - it saves one call to PARSEJSON to find out what the value of the topic is. If there are a lot of mqtt messages coming in and only some of them are interesting, it is more convenient to use this new method.

RECEIVEDMSG further contains mqtt specific values - e.g. CLIENTID, DUP, CONTENTTYPE, EXPIRY - their content depends on what the mqtt server is sending. The old syntax still works and will work.

RECEIVEDMSG also works with TCP and UDP, not just MQTT; there it carries Payload, Length and Protocol ("tcp" or "udp") — RECEIVEDMSG.

Packet analysis#

The information in the Service Settings of Packet Parser modules contains statistical data about received and sent messages - counts for the last 5 and 30 minutes, the number of received bytes, and for MQTT, the information is sorted by MQTT topics. This should help in debugging scripts and setting the most suitable topic filter to ensure that as few messages as possible that are not processed by Core are delivered.