---
title: "Expressions / Script Language"
description: "TapHome script language reference: contexts in smart rules, notifications, Modbus and Packet parser, the script result, data types, operators and all 104 functions."
url: "https://taphome.com/en/docs/script/"
language: en
lastmod: 2026-11-06
generator: hugo
ai:
  topics: ["scripting-language","expressions","functions","data-types","smart-rules","parsing"]
  questions: ["How do I write multi-line scripts in TapHome?","Where can I use TapHome scripting language?","How to use IF/ELSE statements in TapHome expressions?","How to parse JSON data in TapHome script?","What is the difference between MIN and MINSTRICT functions?","How to work with date and time in TapHome scripts?","How to use LINEAR function for value interpolation?","What value does a TapHome script return?","What may a device read script return?"]
---

# Expressions / Script Language

Last updated: 2026-11-06

![TapHome Icon](https://taphome.com/documentation/script/script-icon.png)

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 for Android, Windows and macOS highlights the syntax in the script editor; the iOS app shows the script without highlighting.

## 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](https://taphome.com/en/docs/script/smart-rules/); the integrations have their own pages, [Modbus functions](https://taphome.com/en/docs/script/modbus/) and [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/).

## Script result

A script is a list of statements. The value of the last evaluated statement is the result of the script. [`RETURN`](https://taphome.com/en/docs/script/basics/#return) ends the script early with the given value.

```taphome
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](https://taphome.com/en/docs/script/data-types/#null-and-nan).

## Reference pages

### Language basics

- [Syntax and control flow](https://taphome.com/en/docs/script/basics/) — Statements, comments, literals, `IF`, `SWITCH`, `WHILE` and `DO` loops, `RETURN`
- [Data types](https://taphome.com/en/docs/script/data-types/) — Numbers, text, structured and enum types, collections, `.Type`, type promotion, `Null` and `NaN`
- [Variables and constants](https://taphome.com/en/docs/script/variables/) — Device variables, group values, module variables, `VAR` and typed declarations, properties, context constants
- [Operators](https://taphome.com/en/docs/script/operators/) — Operator list, precedence, short-circuit evaluation, Excel equivalents

### Rules and diagnostics

- [Smart rules and notifications](https://taphome.com/en/docs/script/smart-rules/) — Equation, Formula, Script, the Formula limiting condition and notifications
- [Logic and diagnostics](https://taphome.com/en/docs/script/logic-and-diagnostics/) — `ISNULL`, `ISNAN`, `EQUALS`, `SLEEP`, `ADDERROR`, `ADDWARNING`, `ADDINFO`, `DEBOUNCE`
- [Errors](https://taphome.com/en/docs/script/errors/) — Parse and run-time error messages and how to fix them

### Numbers and time

- [Statistics and value info](https://taphome.com/en/docs/script/value-info/) — Statistics of a device, Value info with the time of the last change, the previous value and the values of finished periods
- [Mathematical functions](https://taphome.com/en/docs/script/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](https://taphome.com/en/docs/script/rounding-and-random/) — `ROUND`, `CEIL`, `FLOOR`, `RAND`, `RANDINT`
- [Interpolation and thresholds](https://taphome.com/en/docs/script/interpolation-and-thresholds/) — `LINEAR` maps a value from one range to another (for example a dimming curve), `HYSTERESIS`
- [Date and time](https://taphome.com/en/docs/script/date-and-time/) — `NOW`, `DATETIME`, `DATETIMEADD`, `TIMESPAN`, `LOCALTIMEZONE`

### Text, collections and colours

- [Text and collections](https://taphome.com/en/docs/script/text-string-and-byte-array/) — `LENGTH`, `GETAT`, `SETAT`, `APPEND`, `INSERT`, `REMOVEAT`, `COPY`, `INDEXOF`, `REPLACE`, `SPLIT`, `COMPARE`, `BYTECOLLECTION`, `UINT16COLLECTION`, `BOOLCOLLECTION`
- [Sorting](https://taphome.com/en/docs/script/sorting/) — `ORDER`, `ORDERINDEX` and their descending and strict variants
- [Data type conversions](https://taphome.com/en/docs/script/data-type-conversions/) — `TOSTRING`, `TODOUBLE`, `TOBYTES`, `ENCODE`, `DECODE`
- [Colours](https://taphome.com/en/docs/script/colours/) — `HSVTORGB`, `RGBTOHSV`
- [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/) — `PARSETEXT`, `PARSEJSON` (reads a value from JSON by its path), `PARSEXML`

### Binary and security

- [Bit operations](https://taphome.com/en/docs/script/bit-operations/) — `GETBIT`, `GETBITS`, `SETBIT`, `SETBITS`, `GETBYTE`, `SETBYTE`, `TOBCD`, `FROMBCD`
- [Binary data](https://taphome.com/en/docs/script/binary-data/) — `PACKVALUE`, `UNPACKVALUE`
- [Encryption and hashes](https://taphome.com/en/docs/script/encryption-and-hashes/) — `AESENCRYPT`, `AESDECRYPT`, `HASH`, `HMAC`, `RANDBYTES`
- [Byte encodings and checksums](https://taphome.com/en/docs/script/byte-encodings/) — `TOBASE64`, `FROMBASE64`, `TOHEX`, `FROMHEX`, `CRC16`, `CRC32`

### Device integrations

- [Modbus functions](https://taphome.com/en/docs/script/modbus/) — Register types, `MODBUSR`, `MODBUSW`, `MODBUSWNE`, `MODBUSRBLOCK`, `MODBUSWBLOCK`, `MODBUSWBLOCKNE`
- [Modbus scripts](https://taphome.com/en/docs/script/modbus-scripts/) — Which scripts a Modbus module and device have, when they run, prefetch and caching
- [Modbus data types](https://taphome.com/en/docs/script/modbus-data-types/) — Data types of the Modbus functions, byte order variants, 64-bit types, text
- [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/) — `HTTPREQUEST`, `SENDHTTPREQUEST`, `SENDDATA`, `MQTTPUBLISH`, `FTPDOWNLOAD`, `FTPUPLOAD`, `COMPLETESERVICEATTRIBUTE`, `COMPLETESERVICEACTION`
- [Listener scripts](https://taphome.com/en/docs/script/listener-scripts/) — The listener script of a Packet parser module, `RECEIVEDMSG` and `RECEIVEDBYTES`

### Examples and reference

- [Examples](https://taphome.com/en/docs/script/examples/) — Complete scripts from real device templates
- [Version requirements](https://taphome.com/en/docs/script/version-requirements/) — The Core build each function needs
- [Functions A–Z](https://taphome.com/en/docs/script/functions-a-z/) — Every function with one sentence and a link