Routine ownership, execution and results

Routines follow one model: when any trigger happens, only if all conditions hold, do the saved steps in order. The assigned hub owns execution for a home. Manual starts, schedules, sun events, supported state changes, and local conditions all run through that same owner. The platform records definitions and results, forwards cloud-dependent effects, and reports status, but The platform has no routine timer or fallback executor.

Ownership and execution

A routine belongs to one home’s assigned hub. That ownership is persistent, not a temporary lease. A saved routine is executable only after that hub reports the matching installed version.

Manual starts and automatic triggers use the same execution engine. runsIn tells you whether the routine depends on local execution only or on a cloud path for one or more steps. It does not choose a second executor.

• local: every step can be served without cloud services once the routine is installed on the hub.
• cloud: at least one step depends on a provider or cloud relay.

Local functions can keep working during a cloud outage. Cloud-dependent connectors require the provider and network. If a routine includes cloud-dependent steps, those steps are not available when that cloud path is unavailable.

Manual execution has one hard requirement: Manual Run requires the assigned hub to be online. If the hub is offline, the platform does not run the routine on its behalf.

The reverse case is different: if the hub is running and already holds the routine set, stored local schedules continue even without internet access.

Routine model

Triggers in when

A routine can have up to 10 triggers. Any one of them can start the run.

Supported trigger kinds are:

• phrase
• time
• sun
• state
• presence
• button for supported remotes

when may be empty. In that case, the routine runs only by manual start.

Manual start is always an entry point even if the routine is disabled. Older stored rows may still include manual, but you do not add it as a trigger.

Conditions in only

A routine can have up to 10 conditions. All of them must hold together.

Supported condition kinds are:

• time
• days
• sun
• state
• presence

If only is empty, the routine always qualifies.

Steps in do

Ordinary authored steps are 1-255, with ordered execution; compiled fanout and hub capacity add separate gates.

Supported step kinds are:

• room
• thing
• say
• wait
• notify
• routine
• music
• security

Nested routine steps are allowed up to three levels deep.

Manual run and force

If the assigned hub is already running a routine, an ordinary manual or voice run waits in the durable queue for up to ten minutes. It keeps the same run identity, checks that the routine and hub still match, and receives a new short admission deadline on each attempt. An expired request fails with a reason in run history. Screen delegated and AI governed runs do not use this retry. The hub executes one routine at a time; schedule an advance device warm-up as a separate timed routine instead of adding a long wait to a routine that should leave the hub available.

POST /routines/:id/run starts a routine manually. The caller must have property control permission.

The request accepts optional force: true.

With force, a manual run can:

• run a disabled routine
• bypass ordinary conditions

It does not:

• bypass property control permission
• bypass ownership by the assigned hub
• create a server-side fallback executor

The API returns a run receipt immediately. Acceptance is not proof that devices changed or that every step completed.

Execution ordering and barriers

The hub keeps original step order and same-device order authoritative. Some work can overlap, but only inside independent phases.

A routine never moves work across barriers such as:

• wait
• speech
• notifications
• dependent cloud actions
• other explicit barriers

wait steps can be 1 to 3600 seconds. These are real delays, and explicit waits preserve intentional intermediate states.

For lights, the installed plan merges writes between barriers into one final light state per device. Later writes to the same control win. A wait step prevents that merge across the boundary.

Before sending a local write, the hub compares the requested field with a recent reading from that same field. Matching targets may be recorded as already satisfied and skipped. Missing state, stale state older than 90 seconds, or incompatible representations do not suppress a command.

Cloud effects and local effects

Cloud effects are delegated one action at a time. The relay does not plan, schedule, or retry the whole routine.

If a cloud effect is offline, expired, or otherwise not verified, it is reported as unconfirmed while local steps continue where ordering allows. Device completion is separate from dispatch.

For speech actions, scheduled playback is not enough. If playback cannot be verified, the result is playback unconfirmed.

Coffee machine readiness

A coffee power-on thing step may include waitForReady. This field is valid only when the action sets coffee_machine.power = true.

With waitForReady, that step becomes a barrier. Following dependent steps wait until all of these are true:

1. power on is confirmed
2. the machine reports READY
3. the selected-room announcement completes successfully

Without waitForReady, warm-up and announcement remain asynchronous.

The ready announcement can target the machine room by default or explicit selected-room choices through readyRoomIds. Scheduled, voice, and manual runs all use the saved room selection.

If the machine reaches READY but the announcement does not complete, the barrier fails truthfully and later dependent actions do not start.

State triggers and conditions

State triggers fire when the test becomes true, not on every later report while it remains true. Supported local state edges are evaluated on the hub.

Important limits:

• state triggers are edge-triggered
• state triggers have a 10-second per-routine floor
• unknown readings do not satisfy conditions
• ordered comparisons apply only where the field type supports them

Time and sun evaluation use the property’s address, time zone, and local calendar date.

Installation and hub receipts

The routine set installed on a home is private to that home. It includes full routine definitions plus the home data the hub needs to execute them.

Transfer and admission rules:

Limit	Value
chunk size	1 KiB
protocol 2 maximum	64 KiB
manual run admission deadline	30 seconds
run identity format	32 lowercase hex

An incomplete or incompatible transfer never grants execution.

After parsing, the hub reports:

• CRC/version
• byte count
• executable routine IDs

A saved definition is not executable until the assigned hub reports the matching executable ID and receipt.

Results and run history

Immediately before the existing route table, note that it lists ALYT application API routes, while the Developer gateway separately allowlists operations. Its 293-operation SDK does not expose routine-ID read, update, delete, run, or history routes, and those existing application routes still require their existing household or installer permissions. This release widens no Developer gateway scopes, and App ID/secret credentials are not equivalent to a household owner session.

Use these routes:

Route	Purpose
GET/POST /properties/:id/routines	list or create routines
GET/PATCH/DELETE /routines/:id	read, update, or delete one routine
POST /routines/:id/run	start a manual run
GET /routines/:id/runs	inspect run history
POST /routines/match	match spoken text to a routine or command

Run history records:

• cause
• start and finish times
• per-step detail
• success or failure
• skipped reason when conditions blocked execution

A pending receipt does not prove a physical effect. Queue acceptance is not device success. A sleeping device write can stay unconfirmed while later steps proceed.

When a run fails, the recorded result names failed actions and raises one household failure notification. Confirmed actions are not replayed.

Supported-scope limits

Some stored routine graphs can exist but are not executable by the current owner. In those cases, the platform does not take over execution.

Examples of unsupported execution scope include:

• phone presence evaluation on the hub
• arbitrary cloud state triggers on the hub
• Home Security routine consent where the current evaluator does not admit execution

For nested routines, child conditions are preserved; execution does not flatten away those requirements.

Permissions

Routine read routes require property view permission. Creating, editing, and deleting require property management permission. Manual run requires property control permission.

Household permissions are narrower than staff. If you test with developer credentials, remember that DEV credentials act in the developer sandbox, and LIVE credentials only for their own installed connector.

Routine limits and exclusions

A routine may contain 1–255 authored steps, and TV descriptions carry the full 255. The compiler still applies its separate 255-expanded-action gate after fanout and nested expansion, while actual persistence also requires the assigned hub’s reported bytes and UTF-8-safe chunk count to fit the live admission limit before saving.

Routine writes also support same-home, same-capability excludeThingIds, shown as Leave unchanged in web and phone clients. The compiler resolves current membership, emits only nonexcluded endpoint commands, and sends zero effects when all targets are excluded; clearing an exclusion list must be explicit with excludeThingIds: []. An actual hub byte and chunk admission check runs before persistence, and a 409 rejects a competing routine-definition edit during validation or a missing exclusion list that would silently drop an existing constraint. Remote cells keep their separate 30-step limit, and the frozen-model 30/64 proof budget remains unchanged.

Ordinary Zigbee actions continue while the hub collects status in the background: completing command frames releases the execution slot. Pending evidence uses bounded 72-byte PSRAM records, with at most two extra missing-state reads inside the existing 30-second ordinary or 15-second lock window. Final results wait for evidence; independent commands do not. Physical write and app/model deadlines remain unchanged. Missing confirmation is not proof of physical failure; retain the first actual reason and check the device before retrying. No physical write is replayed.

An actual jam ends the lock job without repeating the motor write. Later routine requests also leave a still-jammed motor alone until actual device state clears it; battery updates and elapsed time cannot clear it. Ordinary lock-only steps retain a quiet history diagnostic, which does not prove the door locked. App/model effects remain unsuccessful, as do mixed requests with unconfirmed fields and mapping or permission failures. Check the door safely and clear the obstruction before deliberate further action. After a reboot, if the lock state is unknown, the hub reads its status before sending a motor command. If there is no reply, no motor command is sent. Independent actions on other devices continue.