Concepts
Steps and exits, conditions and the otherwise branch, waits and cancel connections, drafts versus published, cooldown, variables and placeholders.
Steps
A flow is a graph of steps joined by connections. Steps come in three kinds, colour-coded in the editor:
| Kind | Role | Examples |
|---|---|---|
| When | starts a run; has no incoming connection | Device changes, Time of day, Sunrise / sunset, Someone arrives, Button pressed, Manual start |
| And | gate: continues on true, or takes the otherwise exit | Device is, Time between, Day of week, Presence, Sensor is |
| Then | acts | Control devices, Send notification, Wait, Speak, Set variable, Call a web API, Stop |
The step reference documents all of them, with their options.
Exits and the otherwise branch
Most steps have one exit. Every And step has two: the default exit (true) and an otherwise exit (false), drawn dashed. Schedule starts / ends has active / inactive exits, and Day parts has one named exit per period plus No period and Away. A step with several outgoing connections from the same exit starts them all in parallel.
Waits and cancel
Wait and Wait until park the run. A connection drawn into a wait step's cancel handle stops whatever is parked there, before the run continues past the cancelling step. Stop waiting does the same from anywhere in the flow. Options on the wait decide what happens when a second run reaches it while one is already waiting: run in parallel, restart the wait, or stop.
How a run proceeds
- A When step fires (or you press the run tab on a step).
- The hub walks the graph: And steps branch, Then steps act. A failing action is logged and the walk continues; a dead end simply ends that path.
- Each step runs at most once per run and a run is capped at a number of steps, so loops end.
- Stop ends the current path or the whole run.
Runs are recorded in Recent runs with the trigger and any Log step messages.
Draft and published
Editing never touches what the hub runs. Save draft keeps a working copy (errors allowed); Publish copies the draft over the published graph, which is what the hub reconciles and runs. A never-published flow has no running graph at all. Discard draft returns to the published version. Publishing a flow aborts its in-flight runs, including pending waits.
Enabled and cooldown
A flow can be switched off without deleting it (list toggle or header toggle). Cooldown (header menu) refuses new starts for a number of seconds after one starts: use it on triggers that fire in bursts. A hub also limits concurrent runs; a start refused for either reason shows as On cooldown / Already running.
States: what you type versus what is stored
A device reports a raw token (on, locked, ARMED_AWAY); the app shows a friendly label
for it that depends on the device (Open for a door sensor, Detected for a motion sensor). The
state pickers in the editor store raw tokens. Where a state arrives as typed text instead — the
AI builder, a JSON import, the Manual start's test values — the
label is accepted in any case or spelling (armed away, Armed-Away) and rewritten to the raw token
when the flow is saved, so the stored flow is the same on every hub. A value that names no state the
device reports gets an unknown state warning in the issues strip rather than a step that silently
never fires. The hub also resolves labels at run time as a safety net.
Variables and placeholders
Set variable stores a value for the flow (or shared across the location's flows). Variable
is reads it back, or reads a path from the triggering event (trigger.state, trigger.name, …).
Comparisons on trigger.state and trigger.friendlyState ignore case and separators, so open
matches Open and armed away matches ARMED_AWAY; every other variable compares exactly.
Text options that accept placeholders expand tokens like {{trigger.name}}, {{var.count}} and
{{flow.name}} at run time; the full list is on Template placeholders.
Limits
Steps and connections per flow, flows per location and the serialised size are capped so a flow stays something a person can read on a canvas and the hub can store. The three size limits block even a draft save. See Limits.