Trigger Reference

The 32 blocks that start a flow when a device reports something. Three rules decide how often they fire: transitions fire on the change, thresholds fire on the crossing, and an unknown previous value seeds instead of firing.

A trigger block has a flow OUT pin and no flow IN pin. The device event dispatcher seeds its out pins and starts the flow from there, the same way a schedule block works.

Every trigger fires only for adopted devices. The single exception is device discovered, whose purpose is to notice devices that are not adopted yet.

Three rules decide how often a trigger fires

Transition triggers fire on the change, not on every report

A motion sensor re-announces occupancy: true every thirty seconds or so while a person is in the room, and a power meter reports every ten seconds whether or not anything changed.

Every binary trigger requires the value to have changed. So presence detected in a hallway with somebody standing in it fires once, on entry.

The exception is a momentary capability: button presses, doorbell rings, access entries, NFC swipes and camera motion. A pulse has no meaningful "unchanged", so every occurrence fires, including an identical repeat.

Threshold triggers fire on the crossing, not on the level

temperature changed with above = 25 fires once, when the room passes 25 °C. It fires again only after the reading has gone back below 25 and crossed up again. The exact test: the new reading is above the threshold, and the previous one was at or below it.

• A first-ever reading above the threshold counts as a crossing. Staying silent until the second reading would mean a node restart swallows an alarm.
• Neither above nor below turns the threshold off: the trigger fires on every changed reading.
• Both fires on either crossing.
• 0 is a legitimate threshold. Leaving a pin empty is what turns it off, not setting it to zero.

An unknown previous value seeds instead of firing

When the node has no previous value for a capability, an incoming reading is recorded without counting as a transition. Nothing fires; the value is simply learned. Otherwise a routine restart would become a burst of "door opened" and "light turned on" for things that did neither.

• Three exceptions fire anyway: smoke, gas and water_leak. A duplicate "smoke detected" is an annoyance; a missed one is the thing the sensor exists to prevent.
• Occupancy, contact and vibration do not. They are what a restart most often finds mid-state, and nothing catastrophic follows from learning about them one report late.
• Momentary capabilities are unaffected: they have no persistent state to seed.

You will rarely see this, because last-known state is restored from Redis before the adapters connect. The rule covers a fresh install, a flushed Redis and a device heard from for the first time. See What Survives a Restart.

Every trigger has the same shape

Two in-pins narrow which devices a trigger listens to, and both are optional.

Out-pins are identical on all of them, and the two access-entry triggers add three more:

Sensors: any binary capability

• "Sensor" means the binary capabilities that describe the world. It excludes power, which has its own light and switch triggers, and tamper and battery_low, which are device health. Folding power in would make every whole-house sensor flow fire on its own lighting changes and livelock.
• A motion sensor clears after its own configured stillness timeout, often 60 to 120 seconds, so sensor deactivated fires when the sensor says clear, not when the room empties.

Presence and contact

Alarms: leaks and smoke

Lights and switches

• These fire for changes RUAL did not make: a physical wall switch, the Hue app, a scene fired by a dimmer. A flow that turns a light on in response to a light turning on is a loop.
• The light and switch split follows the derived device type. A device with on/off but no brightness or colour is a switch, so metering plugs land here even when the vendor announces them as lights.

Buttons and scene controllers

Branch on the value pin to tell single from double from hold. The exact strings are the device's own. Common ones are single, double, hold and release, but a four-button remote sends things like 1_single and a Hue dimmer sends initial_press and long_release. Press the button once with the Zigbee2MQTT frontend open, or read the device state through get device, and use what it actually sends.

Environment readings cross thresholds

Other numeric capabilities have no dedicated trigger. For illuminance, CO₂, power draw or a blind's position, use device state changed and branch on the capability pin, or read the value with get device state inside a flow another trigger started. The threshold-crossing behaviour is specific to these two blocks.

Device health and the fleet

The catch-all: any capability that changes

High volume by design. A house with a dozen sensors produces hundreds of these an hour. Use it for logging, and for capabilities that have no dedicated trigger, then branch on the capability pin. Where a specific trigger exists, use that: it is cheaper and it says what it means on the canvas.

Doors, access control and cameras

These twelve come with the UniFi Access and Protect adapter: when someone rings, when a card is swiped, when the gate opens, when an unknown card is refused at three in the morning.

• The two entry triggers carry three extra out-pins: actor (the user or credential name, empty when the reader could not identify them), method and granted.
• Swiped and granted are different questions. NFC card swiped fires when the card is presented, before and regardless of the decision: "when my gym fob is tapped, turn on the porch light". access granted fires only when somebody is let in. A refused card fires the first and not the second.
• Doorbell, NFC, entry and camera motion events are momentary. Every occurrence fires, including the same card presented twice in a row.
• Lock state is not door position. A door can be unlocked and still shut, or wedged open while the relay says locked. Pick the trigger that asks the question you mean.

Dispatch is in process and capped at 16 runs

• Dispatch is in process, not queued. Every other trigger in RUAL goes through the queue, which buys durability at the cost of a write and a poll interval. Here the light has to come on before you have finished walking through the door. A node restart drops in-flight triggers.
• The trigger index is cached, not searched per event. It is built at startup, before the adapters connect, so the first motion event after a restart is not dropped. It is rebuilt when you save a blueprint, so a studio edit takes effect without a restart.
• Only active trigger blocks in saved blueprints are indexed.
• Concurrent runs are capped at 16. Beyond that, events are dropped with a warning in the log rather than queued: a backlog of stale "turn the light on" commands is worse than none. Hitting the cap usually means a flow is slow.

Next steps