Save and use routines across your devices
Web, phone, TV, and widgets all use the same saved routine for the selected home. Web and phone edit that saved definition; TV and widgets use the same routine when the server says it is eligible, without creating another copy. The hub stores and executes the routine. That means local actions can keep working during a cloud outage, while cloud-dependent steps still require their provider and network. For client integrations, read the current routine from the authenticated API, preserve fields your client does not edit, respect server-returned permissions and availability, and treat a run request acknowledgment as submission rather than completion.
What is shared across devices
Section titled “What is shared across devices”A routine is one saved definition for one home. Your client should render the canonical saved definition returned for the selected tenant and home.
Important rules:
- Web and phone are the supported editors.
- TV and widgets do not maintain separate routine copies.
- Editing a routine updates the saved definition for that home.
- Run-history updates alone do not mean the definition changed.
- Saving or editing a routine does not require reflashing the hub.
When you update a routine, preserve settings fields your client does not edit. Do not infer supported behavior from brand, model, cached state, or a successful request acknowledgment.
Device-type settings are shared across brands exposing the required capabilities.
Editing behavior and conflict handling
Section titled “Editing behavior and conflict handling”When the saved definition changes elsewhere:
- Refresh an untouched editor.
- If the user has unsaved changes, show a conflict review instead of overwriting the newer definition.
Only definition changes should do this. If only run metadata changes, keep the current editor state.
Do not claim atomic concurrent-save rejection unless the API actually returns a version conflict.
Public clients must not call internal transport endpoints or bypass home authorization.
TV and widget presentation
Section titled “TV and widget presentation”TV and widgets use the same saved routine as other surfaces. They expose use when the server marks the routine eligible.
For TV, if routineDetails is present, show the supplied details directly:
- enabled state as On or Off
- When from the supplied strings; if none are supplied, show
you press Run - Only if from the supplied strings; if none are supplied, explain that no extra conditions are required
- Do from the supplied ordered strings; if none are supplied, show
No steps are saved.
Do not reconstruct actions from a title or template when routineDetails is available. If details are unavailable, say so, and still preserve the server-issued run action and eligibility.
Security and widget eligibility remain server-enforced.
Running a routine
Section titled “Running a routine”If a manual or voice request reaches a busy hub, the request remains queued for up to ten minutes and its run history reports a final refusal or expiry. A pending receipt does not mean the routine has started. The hub still runs one routine at a time.
A manual run still runs the saved routine for that home. Keep actionable notification navigation scoped to the identified device and home.
The hub executes the routine in order. Preserve these execution rules in your UI and client logic:
- Explicit waits and dependencies remain meaningful.
- Protocol scheduling must not reorder those boundaries.
- A coffee-ready announcement can hold following actions until ready.
- That deliberate wait is different from a failed run.
- Voice messages use their selected room and message volume, restoring prior speaker state afterward.
If the user chooses Run, do not report success from the initial acknowledgment alone. Review pending versus confirmed results and the actual failed step rather than assuming a Run now acknowledgment means completion.
Interpreting run results
Section titled “Interpreting run results”Follow correlated operation results and current reported state.
In practice:
- Respect pending versus confirmed results.
- A request acknowledgment is not completion.
- Do not infer a supported action from a successful request acknowledgment.
- If a run fails, show the failed step instead of a generic failure.
This matters for routines with waits, cloud-dependent actions, and coffee-ready barriers, where the run may still be in progress after the initial request succeeds.
Local and cloud behavior
Section titled “Local and cloud behavior”The hub stores and executes the routine. runsIn describes whether every trigger, condition, and action can be served without cloud services, not whether the platform executes the routine.
| Routine dependency | Behavior during outage |
|---|---|
local work | Can continue if the hub and local path are available |
cloud work | Requires the provider and network |
Never claim a cloud connector works when its cloud path is unavailable.
A later step can still be waiting on an earlier barrier even if earlier local work already finished.
Limits and structure to preserve
Section titled “Limits and structure to preserve”Keep these limits aligned with what the server accepts:
| Item | Limit |
|---|---|
Triggers in when | 10 |
Conditions in only | 10 |
Actions in do | 255 |
| Wait minimum | 1 second |
| Wait maximum | 3600 seconds |
| Nested routine depth | 3 levels deep at most |
| Ready-room list size | 1 to 30 rooms |
| Speech text length | 1 to 400 characters |
| Notification title length | 1 to 80 characters |
| Notification body length | 1 to 400 characters |
An empty when means the routine is run manually. In presentation, that reads as you press Run.
Permissions and client responsibilities
Section titled “Permissions and client responsibilities”Use the authenticated API and the capability and settings descriptors for the selected tenant and home.
Your client should:
- respect server-returned permissions, availability, versions, and pending versus confirmed results
- preserve settings fields the client does not edit
- keep actionable navigation scoped to the identified device and home
- reflect server decisions about eligibility and authorization instead of replacing them
Access boundaries matter where they apply:
- household permissions are narrower than staff
- DEV credentials act in the developer sandbox
- LIVE credentials only for their own installed connector
Recommended workflow
Section titled “Recommended workflow”- Load the routine for the selected home through the authenticated API.
- Render the canonical saved definition.
- Allow editing on web and phone.
- Preserve fields your client does not edit.
- If a newer definition arrives, refresh a pristine editor or show conflict review for an editor with unsaved changes.
- On Run, show submission first, not completion.
- Update the UI from pending versus confirmed results and current reported state.
- If the run does not finish, identify the actual failed step.
This keeps routine editing and use consistent across web, phone, TV, and widgets while matching the current execution behavior of the platform.
Routine capacity and exclusions
Section titled “Routine capacity and exclusions”Routines keep the 255 authored step limit and the 255 compiled-action limit. excludeThingIds is limited to current same-home endpoints with the selected capability, and the UI shows excluded devices as Leave unchanged.
Compilation uses current membership and emits only nonexcluded endpoint commands, with no effects for an all-excluded scope. The assigned hub must admit the actual UTF-8 bytes and chunk count before persistence. A competing routine-definition edit returns 409 during validation, and an older writer that would drop an existing exclusion list is also rejected 409. Clearing a list is explicit with excludeThingIds: []. Remote cells stay at 30 steps, frozen-model limits stay 30/64, and TV descriptions may include all 255 steps.