Expressions

An expression is a short formula you type into a Simple expression transformer. Use it to compare values, search inside text, pick one of two results, or combine several checks — without writing a full script.

You'll find Simple expression in:

In any of those chains, tap a row to edit it, drag the handle to reorder, and swipe right to left to delete a transformer or action.

Inside an expression you refer to data with plain names and dot paths — for example value, value.temp, ctx.transport.topic. There's no leading $ here; that's only for JSONPath.


Quick reference

Goal Form
Main data / a field value, value.name
Names available to you value (when set), raw, ctx, transformed (tap actions only), env.my_key, vars.my_key, params.key (custom screens only) — see Available names below
Connection error in transformers ctx.error, ctx.error?.message, ctx.error?.kind, ctx.error?.statusCode
MQTT details ctx.transport.topic, ctx.transport.receivedAt, …
HTTP ctx.transport.responseTime, ctx.transport.statusCode, ctx.transport.url, ctx.transport.requestHeaders, ctx.transport.responseHeaders, …
WebSocket ctx.transport.event, ctx.transport.mode, …
Timer tick ctx.transport.reason, ctx.transport.intervalMs, ctx.transport.receivedAt
Extra field on ctx ctx.foo (after Lua or JavaScript wrote it, or a tap HTTP request stored a ctx key)
Item in a list value[0], value[-1]
Safer when data may be missing value?.name, value?.[0]
If empty, use other value?.name ?? "x"
Equal / compare == != < <= > >=
Wildcard text match value ~= "A*BC" or value ~i= "a*bc"
Substring check value ~? "x" or value ~?i "x"
Regex match value ~/pattern/ or value ~/pattern/i
Extract with regex value ~[pattern] or value ~[pattern]i
Find position / presence value ~# "x" >= 0 (or ~#i)
And / or / not && and and · || and or · ! and not
If / else value cond ? a : b
Another data source source_value("Name") · source_raw("Name") — see Reading another data source below
ENV variable env.my_key · {{ env.my_key }} — see ENV variables
Component look (read) comp.visible, components.label1.value — on a data piece or component only; see Lua and JavaScript

Available names: value, raw, ctx, transformed, env

Every expression runs inside a chain — Data transformers pipe, or Tap actions pipe — and each kind makes different names available.

What each name means, when it's available:

Whatever an expression returns becomes the new value for the next transformer or action in the chain — including an empty (null) result.

When a result looks like JSON

If an expression returns text that looks like JSON — it starts with { or [ once leading and trailing spaces are removed — the app tries to turn it into an object or list, as long as it's valid JSON. The next transformer or action then sees structured data, so a path like value.title works, or a JSONPath transformer can query fields.

Numbers, booleans, and ordinary text are unaffected.

See also JSONPath, Lua, and JavaScript — they expose the same names with different syntax.

On tap, HTTP request, MQTT send, WebSocket send, destination fields (including Text to send), Open URL, Apply value, User input: Text, and User input: Range can embed the same expressions as {{ value?.field }} or {{ env.my_key }}; see Tap actions.

Leave the send field empty to send the current value, including a file or image. You can also put only {{ value }} or {{ value.binary }} (or {{ source_value("Name") }}). Mixing a file or image with other text fails. URLs, headers, topics, and events are text only. For HTTP, set the content type yourself when you send a file or image.

On a data source, MQTT Topic filters (subscribe), WebSocket Rooms and Message events, and Default value can include {{ source_value("Name") }} or {{ env.my_key }}. Names there are value and raw for that source, plus source_value("Name"), source_raw("Name"), and env — not tap transformed or ctx.

HTTP action URL / headers / parameters / body also see ctx, including ctx.transport from the previous HTTP request in the same list. MQTT and WebSocket connection fields (host, URL, credentials, headers, …) can include {{ env.my_key }} the same way.

If an expression can't be evaluated, that MQTT/WebSocket subscribe, connect, or tick is skipped; MQTT and WebSocket keep the last successful subscribe, and the source shows an error. An empty or invalid HTTP action URL, or an expression that can't be evaluated there, stops the rest of that HTTP list. See Data sources and ENV variables.

Connection errors: ctx.error

In source, data piece, and component transformer expressions, ctx.error is:

An expression can read this and choose a result:

ctx.error ? 0 : 1

To read a field safely when it might be empty, use ?., for example ctx.error?.message. Writing ctx.error.message without the ? fails when there's no error, and stops the rest of the transformer chain.

An expression can't clear ctx.error — use a Lua or JavaScript transformer when the chain should mark the error as handled. Mistakes in an expression itself (typos, bad paths) are separate from ctx.error; they also stop the rest of the current transformer chain.

MQTT: ctx.transport

For an MQTT data source, when ctx.transport is present, it describes the most recently received message (the message body itself is still value):

HTTP: ctx.transport

For an HTTP data source or destination, and for a tap HTTP request, ctx.transport describes the last HTTP request in that list:

Use ctx.transport.responseTime ?? 0 to show how long the request took.

WebSocket: ctx.transport

For a WebSocket data source, when ctx.transport is present:

Timer: ctx.transport

For a Timer data source:


Reading another data source

You can read any other data source by its display name (not case-sensitive):

An unknown or empty name fails with an error.

While a transformer on source X is running, value is the live data moving through that chain; source_value("X") still returns the previous stored value until the chain finishes.


Reading values

Simple names

Nested fields (dot paths)

Lists and positions

Use square brackets with a zero-based position (the first item is 0):

Paths can be chained: value[0].tags[1], value.items[0].name.

When something might be missing (optional path)

If any ?. part is missing, the whole path is treated as empty (null) instead of causing an error.

If empty, use another value — ??

left ?? right uses right only when left is empty (null). 0 and blank text are kept.

Use it when a field may be missing:

value.name ?? "unknown"

A missing field is empty (null), so you get the fallback. If value itself can be empty, write value?.name ?? "unknown". This is shorter than value.name != null ? value.name : "unknown".


Literals (fixed values you type)

Kind Examples
Numbers 42, 3.14, -7
true / false true, false
Empty null
Text "hello" or 'hello'

Inside a quoted string, a backslash \ before a character includes that next character as-is.


Comparing values

Operator Meaning
== equal
!= not equal
< <= > >= less / less-or-equal / greater / greater-or-equal

Numbers: numbers and number-like text (such as "25" from a payload) are compared as numbers, so "25" < "100" is true. == also treats a number and number-like text as numbers: "5.0" == 5 is true. Two texts are equal only when they are the same text ("01" == "1" is false).

Otherwise: values are compared as text.

Empty (null): null only matches == null, and != to anything that isn't null. < <= > >= are always false when either side is null.


Text and pattern matching

The value on the left is turned into text before matching.

Each operator must be immediately followed by the quoted text it needs.

Wildcard match — * and ?

Contains

Regular expression (yes or no) — /pattern/

This form only tells you yes or no.

Regular expression (extract text) — ~[ … ]

Searches the value and returns matching text:

If the pattern has a capturing group, the first group is returned. If there's no group, the whole match is returned. If nothing matches, the result is empty.

Substring position — ~# and ~#i

For a reliable "does this contain X?" check:

The result of ~# (or any comparison) can be compared again; operators on the same level run left to right.

Or use ~? / ~?i for a plain contains check.


Combining conditions

Operator Meaning Alternative word
&& both must be true and
|| at least one true or
! … not not …

Examples:

! and not apply to the whole comparison after them: !a == b means !(a == b). Write (!a) == b to negate only a.

Order of evaluation (highest to lowest):

  1. Literals, paths, and parentheses
  2. Comparisons and text operators (==, ~=, ~/, ~[, ~#, etc.)
  3. ! / not
  4. && / and
  5. || / or
  6. ??
  7. Ternary ? :

Comparisons come before ??, so vars.wifi ?? "1" == "1" means vars.wifi ?? ("1" == "1"). Add parentheses: (vars.wifi ?? "1") == "1" ? "On" : "Off".


Ternary: choose one of two results

condition ? ifTrue : ifFalse

Examples:

You can nest ternaries: a ? b : (c ? d : e).


What counts as "true"

When the app needs a yes/no answer:

Extracted text (~[ … ]): empty → no; non-empty → yes.


Invalid expressions and errors

Common mistakes:

Fix the spelling, add ?. after a value that may be empty (value.a?.b), or check the path against your actual data. A missing field is not an error: it is empty (null). If a field stays empty, check its spelling.

On a component or data piece setting, a failed expression shows the start of the error in red, on one line under the row. The component shows a red #error above its top-right corner in the editor, and text that comes from that expression stays empty. A failed script or expression in its actions shows the same mark.

Tap the row (or, on a combined row such as Border, the line of that part) to open the editor. The full error is above the field: you can select it, scroll it, or copy it with the copy button.

See also Expressions in editors, Lua, JavaScript, JSONPath, and ENV variables.