Site Modes

Site Modes define operational states that can be applied to the site or to individual site spaces. Modes enable different automation behaviors based on the current state of a space, such as "Occupied", "Away", "Night", "Party", or "Business Hours".

The mental model is four short sentences:

1. A mode is a named state you set on the site or any space; spaces without their own mode inherit from above.
2. Hold pins an assignment — a held space keeps its mode until the hold is released.
3. Modes carry enter/exit actions — simple subsystem-wide commands (or a macro when you need more) applied wherever the mode just took effect.
4. Broader mode changes prune around spaces that have their own direct mode — you never have to opt rooms out one by one.

Overview

Modes are system-wide definitions assignable to the site (site-wide) or to any site space. When the effective mode of a scope changes, the outgoing mode's exit actions and the incoming mode's enter actions run automatically against the spaces that actually transitioned — no hand-built macros or triggers required for the common case.

Viewing Modes

The main grid displays all configured modes with the following columns:

• ID - Unique identifier
• Name - Internal mode name
• Label - Display name
• Description - Purpose description
• Default - Whether this is the fallback mode
• Enter / Exit - Number of configured transition actions
• Sort - Display order
• Enabled - Whether the mode is active

Grid Actions

• Add - Create a new mode
• Edit - Modify an existing mode
• Sort - Drag to reorder modes
• Delete - Remove a mode

Creating a Mode

1. Click Add in the grid toolbar
2. Configure the mode properties (see below)
3. Click Save

Mode Information

Name

• Internal identifier (lowercase_with_underscores)
• Auto-formatted on blur
• Examples: occupied, away, night_mode, business_hours

Label

• Human-readable display name
• Examples: "Occupied", "Away", "Night Mode", "Business Hours"

Description

• Optional text explaining the mode's purpose

Sort Index

• Numeric value controlling display order in selectors and lists

Settings

Default

• Toggle to mark this as the fallback mode
• The default mode is used when no mode is explicitly set anywhere
• Only one mode should be marked as default

Enabled

• Toggle to enable/disable the mode
• Disabled modes are hidden from selectors but their configuration is preserved

Actions

Each mode carries two action lists — On Enter and On Exit — that run automatically whenever the mode takes effect at (or leaves) a scope. Actions always apply to the transitioned spaces: the site or space the mode was set on, plus every descendant space that inherits it. Spaces with their own direct mode are untouched.

An action row is one of two shapes:

Command action — a subsystem-wide command:

• Subsystem — the zones to target (e.g. Lights, Climate, Shades)
• Command — the verb (level, on, off, setpoint, open, close, ...)
• Level — optional numeric value (dimmer %, setpoint, shade position)
• Args — optional JSON for command-specific arguments (e.g. {"mode": "cool"} on a setpoint)

Macro action — a reference to an existing macro. Use this the moment you need delays, conditions, notifications, or ordering — the action list itself stays flat and immediate by design. The macro receives transition context (site_mode, site_mode_id, site_mode_direction, site_mode_scope_space_id).

Example — "Unoccupied" setback

On Enter:

Subsystem	Command	Level	Args
Lights	level	50
Climate	setpoint	78	{"mode": "cool"}
Climate	setpoint	62	{"mode": "heat"}

Set the site to Unoccupied and every inheriting space dims to 50% and sets back. Later, when a single space (say the guard house) leaves its own mode and falls back to Unoccupied, the same actions run again — scoped to just that space. Actions never enumerate zones, so they stay correct as zones are added.

Mode Inheritance

Modes follow a parent-child inheritance model through the site space hierarchy:

1. If a space has a mode directly assigned, that mode is used
2. If no mode is assigned, the space inherits its effective mode from its parent
3. Inheritance walks up the hierarchy until a direct assignment is found (then the site, then the default mode)
4. A mode change at a scope only affects the spaces that resolve through it — descendants with their own direct assignment are pruned, along with their subtrees

Example

Building (mode: business_hours)
  Floor 1 (no mode → inherits business_hours)
    Lobby (no mode → inherits business_hours)
    Server Room (mode: always_on)   ← pruned from Building-level transitions
  Floor 2 (mode: quiet_hours)       ← pruned from Building-level transitions
    Office 201 (no mode → inherits quiet_hours)

Transitions fire on effective mode changes. Clearing a space's direct mode is a real transition too: the space falls back to its inherited (or default) mode, and that mode's enter actions run scoped to the space. Re-asserting a mode that is already in effect fires nothing.

Hold — pinning an assignment

Hold is set per assignment (on the site or on a space), not on the mode itself — from the Mode panel in Site Spaces. A held assignment rejects mode changes and clears at that scope until the hold is released. Holding a space with no direct mode pins it to inheritance (direct assignments are rejected).

Broader transitions already skip spaces with their own direct mode, so a held space is doubly protected: the site can change modes freely around it, and nothing can change the space itself until the hold is released.

The bypass pattern

To take a space "out of automation" (guest privacy, maintenance, commissioning):

1. Create a mode with no enter or exit actions (e.g. bypass, guest_privacy, maintenance)
2. Set it directly on the space
3. Hold the assignment

The space is now pruned out of every broader mode transition, its own mode does nothing, and it can't be changed until the hold is released. For triggers that should also respect it (e.g. motion lighting), gate the trigger on the space's effective_mode attribute.

Attributes

Mode state is mirrored onto attributes so triggers, widgets, and the AI can react to it:

Attribute	Target	Meaning
mode	site / site_space	The direct assignment (empty when inheriting)
effective_mode	site / site_space	The resolved mode — direct, inherited, or default. Use this in triggers that should react to inherited changes.

Database Schema

Column	Type	Description
id	INTEGER	Primary key
name	STRING	Internal name (required)
label	STRING	Display name
description	STRING	Optional description
is_default	BOOLEAN	Fallback mode flag (default: false)
enter_actions	JSON	Action entries run when the mode takes effect
exit_actions	JSON	Action entries run when the mode is left
sort_index	INTEGER	Display order
enabled	BOOLEAN	Active state (default: true)

Hold lives on the assignment: site.mode_hold and site_space.mode_hold.

Action entries are JSON objects in one of two shapes:

{ "subsystems": ["lights"], "command": "level", "level": 50, "args": {} }
{ "macro_id": 42 }

Integration with Automation

Enter/exit actions cover the common case. For everything else:

Triggers

Create triggers on the mode or effective_mode attributes (site or site_space) — e.g. fire when a space's effective_mode becomes away. Prefer effective_mode so inherited changes are seen.

Macros

• The Set Site Mode macro step sets or clears a mode on the site or a space
• A macro referenced from an action list receives the transition context and can branch on it

Observability

Every transition is logged to site_mode_history — including hold, release, and clear events at a scope with no direct mode assigned (those rows record an empty mode) — and every action run is logged to Automation History (artifact type site_mode), including the zone counts dispatched and any errors.

Best Practices

1. Keep it Simple: Start with a small set of modes (occupied, away, night) and add more as needed
2. Prefer actions over hand-built macros: Use the action lists for subsystem-wide changes; reach for a macro action only when you need delays or conditions
3. Use Hold deliberately: Hold pins one assignment — release it when the exception is over
4. One Default: Ensure exactly one mode is marked as default
5. Clear Labels: Use descriptive labels that are obvious to end users
6. Trigger on effective_mode: The mode attribute is empty on inheriting spaces — effective_mode is the one that always resolves

Related Documentation

• Site Spaces - Assigning modes to spaces, holds, inheritance chain
• Triggers - Automating responses to mode changes
• Macros - Automation sequences