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:
- Actions / Transformers pipe on an HTTP data source or HTTP destination — after (or between) HTTP requests in that list.
- Data source transformers — MQTT, WebSocket, and Timer: clean up or check incoming data before it's stored.
- Data piece transformers — reshape the root source value for this data piece.
- Component transformers — format a value for display.
- Tap actions — branch logic, build a message to send, or prepare a prompt for the user. Add them on the data piece or on a component.
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.
- Data transformers pipe (on a data source, data piece, or component): you have
value,raw,ctx,env, andvars.transformedis not available here. - Tap actions pipe (when you tap a data piece or component): you typically have
value,raw,ctx,transformed,env, andvars. If the data piece has tap actions turned on, the tap does not reach components. - On a data piece or component (not a data source, HTTP list, or inspector field with
{{ }}):compis this component (comp.bgColorIdon a data piece).components.label1.visibleis another component by ID. You can read these names. To change how a component looks, use Lua or JavaScript. - On a custom screen, both also have
params— the values passed when the screen opened (params.key). envis available in both, and in interpolating fields. See ENV variables. A table of names in every editor is in Expressions in editors.
What each name means, when it's available:
value— the current data. In a multi-action tap chain it changes after each action. In a transformer chain it's the data moving from one transformer to the next.raw— in tap actions, fixed for the whole tap: the data right after the source's own transformers ran. In transformers, the data at the start of that chain, before its first transformer.transformed— tap actions only. Fixed for the whole tap: whatever the component was showing right when you tapped it. Stays the same even if a later action changesvalue.ctx— shared details for the current run. Expressions can read these fields (ctx.foo) but cannot assign them.- In transformers,
ctx.errorholds a connection error, or is empty (null). ctx.transportholds connection details for this run (MQTT topic, HTTP method/url/requestHeaders/status/response time, WebSocket event, Timer tick, …).- Component transformers receive the source's
ctx.errorandctx.transport; extra fields you set in a source Lua or JavaScript transformer do not copy over. - Extra fields that Lua, JavaScript (or a tap HTTP request) stored — for example
ctx.unitorctx.reply— are also here. - In tap chains,
ctxis shared between actions.
- In transformers,
env— app-wide text you stored under ENV variables. Read a key asenv.my_key. If the key is missing, it is empty (null).vars— app-wide runtime values that Lua, JavaScript, orvars_set("my_key", value)stored. Read a key asvars.my_key. They are not saved when the app closes.comp/components— on a data piece or component only. Read how that component (or another, by ID) looks right now. You cannot assign them here — use Lua or JavaScript. You can also read the Data setting ascomp.userData/components.label1.userData.
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.
- A result that's already an object or list is left as-is.
- If it doesn't decode, or doesn't look like JSON, the original text is kept.
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 object with
message,kind, and sometimesstatusCode, when the connection failed; null, after success or once a Lua or JavaScript transformer has handled it.
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):
ctx.transport.topic(text)ctx.transport.payload— the same decoded body asvaluefor that messagectx.transport.qos,ctx.transport.retain,ctx.transport.protocolVersion,ctx.transport.receivedAt(ISO 8601 text, UTC)- On MQTT 5, you may also see
retainAsPublished,contentType,userProperties,responseTopic,correlationData(base64 text),messageExpiryInterval, and similar fields when the broker sends them.
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:
ctx.transport.method,ctx.transport.urlctx.transport.requestHeaders— request headers (lowercase names)ctx.transport.statusCodewhen a response arrivedctx.transport.responseTimein milliseconds (success, HTTP error, or timeout)ctx.transport.contentType,ctx.transport.charsetwhen the response sent themctx.transport.responseHeaders— response headers when a response arrived (lowercase names). A single header with a hyphen in the name is easiest in Lua, JavaScript, or JSONPath, for examplectx.transport.responseHeaders["content-type"]ctx.transport.receivedAt(ISO 8601 text, UTC)
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:
ctx.transport.mode—websocket,sse, orsocket.ioctx.transport.event— Socket.IO or SSE event name; raw WebSocket usesmessagectx.transport.payload— the same decoded body asvaluectx.transport.url,ctx.transport.receivedAt- On SSE,
ctx.transport.idwhen the server sent a last-event id
Timer: ctx.transport
For a Timer data source:
ctx.transport.reason—interval,trigger,defaultValue, orpeerctx.transport.intervalMs,ctx.transport.receivedAt
Reading another data source
You can read any other data source by its display name (not case-sensitive):
source_value("Name")— that source's current value, after its own transformers ran.source_raw("Name")— the last message that source received, before its transformers ran (nullif nothing has arrived yet).
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
value— usually the main data; the editor may also listctx,raw,transformed,env, and any other names available in the current chain.
Nested fields (dot paths)
value.namevalue.device.battery.levelctx.transport.topic
Lists and positions
Use square brackets with a zero-based position (the first item is 0):
value[0]value[2].idvalue[-1]— the last item
Paths can be chained: value[0].tags[1], value.items[0].name.
When something might be missing (optional path)
- Optional field:
value?.profile?.city - Optional index:
value?.[0],value?.[-1]
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 ?
value ~= "Pattern*"—*means "any characters",?means "one character". Case sensitive. The pattern must match the whole text:"Pattern*"matches"Pattern 1"but not"My Pattern". Put*at both ends ("*Pattern*") to find it anywhere.value ~i= "pattern*"— same as~=, but ignores case.
Contains
value ~? "text"— case sensitivevalue ~?i "text"— case insensitive
Regular expression (yes or no) — /pattern/
value ~/start/— true when the pattern between the slashes matches anywhere in the value. Use^…$to match the whole value:value ~/^start$/value ~/^start/i— ignore case
This form only tells you yes or no.
Regular expression (extract text) — ~[ … ]
Searches the value and returns matching text:
value ~[(\d+)]— the pattern goes between[and]value ~[(word)]i— ignore case
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
value ~# "needle"— the zero-based position of the first match, or −1 if it's not foundvalue ~#i "needle"— case insensitive
For a reliable "does this contain X?" check:
value ~# "needle" >= 0
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:
value.age >= 18 && value.status == "active"value.error == null or value.retryCount < 3!(value < 0)
! and not apply to the whole comparison after them: !a == b means !(a == b). Write (!a) == b to negate only a.
(value.code == 1 || value.code == 2) && value.count > 0
Order of evaluation (highest to lowest):
- Literals, paths, and parentheses
- Comparisons and text operators (
==,~=,~/,~[,~#, etc.) !/not&&/and||/or??- 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:
value >= 60 ? "pass" : "fail"value?.name ?? "unknown"
You can nest ternaries: a ? b : (c ? d : e).
What counts as "true"
When the app needs a yes/no answer:
- Empty (null) → no
- true / false → as expected
- Numbers →
0is no; any other number is yes - Text —
true,yes,on,y→ yes;false,no,off,n, or an empty string → no; a numeric string like"0"→ no, other numeric strings → yes; any other non-empty text → usually yes
Extracted text (~[ … ]): empty → no; non-empty → yes.
Invalid expressions and errors
Common mistakes:
- Unbalanced quotes, brackets, or parentheses
- A typo in an operator
- A field read on an empty value (without
?.), such asvalue.a.bwhenais missing, or a bad list index
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.