Expressions / Script Language

TapHome has one script language for smart rules, notifications and device integrations. The syntax and the functions are the same everywhere; only the available variables, constants and functions depend on where the script runs. The app highlights the syntax in the script editor.

Where scripts are used

The same script language runs in smart rules, notifications and the Modbus and Packet parser integrations:

Context	What the script does	Specific to the context
Equation smart rule	One expression over device values. `TRUE` runs the true actions, `FALSE` the false actions.	`LastState`, `TriggerName`
Formula smart rule	Computes a value that is written to every output device.	`LastState`, `TriggerName`
Script smart rule	Reads device values and assigns new ones; each assignment becomes a device action.	Read-write variables, `TriggerName`
Formula limiting condition	Decides whether a smart rule may run.	`TRUE` lets the rule run
Notification title and message	Builds the text of a notification.	Must return text; notification constants
Modbus module read script	Polls the module, typically to raise device errors.	`MODBUS*` functions
Modbus device read and write scripts	Converts registers into a device value and a requested value back into registers.	The read result becomes the device value
Modbus initialize script	Runs once after the module connects.	Typically `MODBUSWNE`
Packet parser read and write scripts	Sends a request or a command over HTTP, FTP, TCP, UDP or MQTT; for HTTP and FTP it also processes the answer.	`SENDHTTPREQUEST`, `SENDDATA`, `MQTTPUBLISH`
Packet parser listener script	Handles every incoming TCP or UDP packet and MQTT message.	`RECEIVEDMSG`
Service attributes and actions (Modbus, Packet parser)	Diagnostic rows and buttons with parameters in the app.	Action parameters by their abbreviation

SLEEP is rejected in smart rules and notifications (the Formula limiting condition is the exception). ADDERROR, ADDWARNING and ADDINFO work only in device scripts. What each smart rule passes to its script is on Scripts in smart rules and notifications; the integrations have their own pages, Modbus functions and Packet parser functions.

Script result

A script is a list of statements. The value of the last evaluated statement is the result of the script. RETURN ends the script early with the given value.

VAR a := 1;
VAR b := 2;
a + b;
# Result: 3

The result of a device read script must fit the device value, otherwise the script fails with Return value 'X' does not match required return type constraint:

Device value	Allowed result
Switch state, reed contact	`TRUE` or `FALSE` (numbers are accepted), `NaN`, `Null`
Multi-value switch state	Number (a whole number selects the state; a decimal value is not rejected), `NaN`, `Null`
Any other value	Number, `NaN`, `Null`

NaN means “the value is unknown”, Null means “there is no value”. How the two behave in expressions is described in Null and NaN.

Pages in this section

The script language reference has four groups of pages: a guide to the language, the functions by area, the integration functions and reference lists.

Guide

Syntax and control flow — statements, comments, literals, IF, SWITCH, WHILE and DO loops, RETURN.
Data types — numbers, text, structured and enum types, collections, .Type, type promotion, Null and NaN.
Variables and constants — device variables, group values, module variables, VAR and typed declarations, properties, context constants.
Statistics and value info — statistics of a device, Value info with the time of the last change, the previous value and the values of finished periods.
Operators — operator list, precedence, short-circuit evaluation, Excel equivalents.
Scripts in smart rules and notifications — Equation, Formula, Script, the Formula limiting condition and notifications.

Functions

Logic and diagnostics — ISNULL, ISNAN, EQUALS, SLEEP, ADDERROR, ADDWARNING, ADDINFO, DEBOUNCE.
Mathematical functions — MIN, MAX, AVG (they skip unknown values, the …STRICT variants do not), ABS, SIGN, SQRT, POWER, MOD, LOG, LN, DEWPOINT.
Rounding and random numbers — ROUND, CEIL, FLOOR, RAND, RANDINT.
Interpolation and thresholds — LINEAR maps a value from one range to another (for example a dimming curve), HYSTERESIS.
Bit operations — GETBIT, GETBITS, SETBIT, SETBITS, GETBYTE, SETBYTE, TOBCD, FROMBCD.
Text and collections — LENGTH, GETAT, SETAT, APPEND, INSERT, REMOVEAT, COPY, INDEXOF, REPLACE, SPLIT, COMPARE, BYTECOLLECTION, UINT16COLLECTION, BOOLCOLLECTION.
Sorting — ORDER, ORDERINDEX and their descending and strict variants.
Date and time — NOW, DATETIME, DATETIMEADD, TIMESPAN, LOCALTIMEZONE.
Data type conversions — TOSTRING, TODOUBLE, TOBYTES, ENCODE, DECODE.
Colours — HSVTORGB, RGBTOHSV.
Parsing functions — PARSETEXT, PARSEJSON (reads a value from JSON by its path), PARSEXML.
Binary data — PACKVALUE, UNPACKVALUE.
Encryption and hashes — AESENCRYPT, AESDECRYPT, HASH, HMAC, RANDBYTES.
Byte encodings and checksums — TOBASE64, FROMBASE64, TOHEX, FROMHEX, CRC16, CRC32.

Integrations

Modbus functions — register types, MODBUSR, MODBUSW, MODBUSWNE, MODBUSRBLOCK, MODBUSWBLOCK, MODBUSWBLOCKNE.
Modbus data types — data types of the Modbus functions, byte order variants, 64-bit types, text.
Modbus scripts and prefetch — which scripts a Modbus module and device have, when they run, prefetch and caching.
Packet parser functions — HTTPREQUEST, SENDHTTPREQUEST, SENDDATA, MQTTPUBLISH, FTPDOWNLOAD, FTPUPLOAD, COMPLETESERVICEATTRIBUTE, COMPLETESERVICEACTION.
Listener scripts — the listener script of a Packet parser module, RECEIVEDMSG and RECEIVEDBYTES.

Reference

Script examples — complete scripts from real device templates.
Script errors and troubleshooting — parse and run-time error messages and how to fix them.
Script version requirements — the Core build each function needs.
Script functions A–Z — every function with one sentence and a link.

Syntax and control flow

Syntax of the TapHome script language: statements and semicolons, comments, literals, IF in function and block form, SWITCH, WHILE and DO loops, BREAK, CONTINUE and RETURN.

Data types

Data types of the TapHome script language: numbers, text, structured and enum types, collections, the .Type property, type promotion in arithmetic, and how Null and NaN behave.

Variables and constants

Variables in TapHome scripts: device values by abbreviation, group values, module and device variables, VAR and typed declarations, assignment, properties and context constants.

Statistics and value info

Statistics and Value info in TapHome scripts: the value of a statistic, the time of the last change, the previous and last known value, and the values of finished periods.

Operators

Operators of the TapHome script language: arithmetic, comparison, bitwise and logical operators, their 10 precedence levels, the a & 1 > 0 trap, short-circuit evaluation and Excel equivalents.

Scripts in smart rules and notifications

What the Equation, Formula and Script smart rules, the Formula limiting condition and notification scripts pass to a script and do with its result: LastState, TriggerName, outputs, errors and SLEEP.

Logic and diagnostics

TapHome script functions for unknown values and device diagnostics: ISNULL, ISNAN, EQUALS, SLEEP, ADDERROR, ADDWARNING, ADDINFO and DEBOUNCE.

Mathematical functions

TapHome script mathematical functions — MIN, MAX, AVG and their STRICT variants, ABS, SIGN, SQRT, POWER, MOD, LOG, LN and DEWPOINT.

Rounding and random numbers

TapHome script functions for rounding and random numbers — ROUND, CEIL and FLOOR with significance, RAND and RANDINT.

Interpolation and thresholds

LINEAR linear interpolation and HYSTERESIS threshold switching for mapping values, dimming lights and controlling heating in TapHome scripts.

Bit operations

TapHome script bit and byte manipulation — GETBIT, GETBITS, SETBIT, SETBITS, GETBYTE, SETBYTE, TOBCD, FROMBCD, bit width by type and bitwise operators with Excel equivalents.

Text and collections

TapHome script functions for strings, collections and byte arrays — LENGTH, GETAT, SETAT, APPEND, INSERT, REMOVEAT, COPY, INDEXOF, REPLACE, SPLIT, COMPARE, BYTECOLLECTION, UINT16COLLECTION, BOOLCOLLECTION.

Sorting

TapHome script sorting functions — ORDER, ORDERINDEX and their STRICT and descending variants for sorting values or returning sort-order indexes.

Date and time

TapHome script date and time functions — NOW, DATETIME, DATETIMEADD, TIMESPAN and LOCALTIMEZONE — and the properties of datetime and timespan values.

Data type conversions

TapHome script conversion functions — TOSTRING with number and date format strings, TODOUBLE, TOBYTES, and ENCODE / DECODE for XML escaping and Base64.

Colours

TapHome script colour functions — HSVTORGB and RGBTOHSV — and the rgbcolor and hsvcolor value types used to control RGB lights from Packet parser and Modbus scripts.

Parsing functions

TapHome script parsing functions — PARSETEXT for text between patterns, PARSEJSON with JSONPath and PARSEXML with XPath — for reading values from device responses.

Binary data

TapHome script functions PACKVALUE and UNPACKVALUE — read and write typed values in register and byte collections, with big-endian, little-endian and byte-swap order.

Encryption and hashes

TapHome script functions for encrypted and signed device protocols: AESENCRYPT and AESDECRYPT, HASH and HMAC with MD5 and SHA, RANDBYTES, and a Bosch KM200 example.

Byte encodings and checksums

TapHome script functions TOBASE64 and FROMBASE64 (also base64url), TOHEX and FROMHEX, CRC16 and CRC32 — bytes as text and back, and checksums of frames.

Modbus functions

TapHome script Modbus functions — MODBUSR, MODBUSW, MODBUSWNE and the block functions MODBUSRBLOCK, MODBUSWBLOCK, MODBUSWBLOCKNE — and the Modbus register types C, D, H and A.

Modbus scripts and prefetch

The scripts of a TapHome Modbus module and device — initialize, read, read value, write value, service attributes and service actions — and how prefetch and the register cache affect them.

Modbus data types

Modbus data types in TapHome scripts — Int16, Uint16, Int32, UInt32, Float, Bool, String and the 64-bit Int64, UInt64 and Double — with big-endian, little-endian and byte-swap variants.

Packet parser functions

TapHome script Packet parser functions — HTTPREQUEST, SENDHTTPREQUEST, SENDDATA, MQTTPUBLISH, FTPDOWNLOAD, FTPUPLOAD, COMPLETESERVICEATTRIBUTE and COMPLETESERVICEACTION — for HTTP, TCP, UDP, MQTT and FTP.

Listener scripts

TapHome Packet parser listener scripts — process incoming TCP, UDP and MQTT messages with RECEIVEDMSG (topic, payload, protocol) and the older RECEIVEDBYTES byte collection.

Script examples

Complete TapHome scripts: safe division, 0 instead of an unknown value, dimming with LINEAR, Modbus alarms and service attributes, HTTP and JSON, MQTT listener and Wake on LAN.

Script errors and troubleshooting

TapHome script error messages quoted verbatim — Division by zero, parse errors, run-time errors and context or version errors — with the cause and the fix of each.

Script version requirements

Which TapHome Core build each script function and feature needs, in the Official and Next channels, and what the Available notes on function entries mean.

Script functions A–Z

Every TapHome script function in alphabetical order with a one-line summary and a link to its full reference entry.