Skip to main content

Macros

Macros are sequences of commands and actions that automate multi-step operations. They enable complex automation like scenes, modes, and coordinated control across multiple devices and subsystems.

Overview​

The Macros page provides comprehensive macro management:

  • Macro Library: View all macros
  • Macro Editor: Configure macro properties
  • Step Editor: Build action sequences
  • Testing: Run macros to verify behavior
  • Organization: Group by subsystem

Viewing Macros​

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

  • ID - Unique macro identifier
  • Name - Internal macro name
  • Label - Display name shown to users
  • Subsystem - Logical grouping
  • Elevated - Whether the macro requires an elevated role to run
  • Enabled - Whether macro can be executed

Grid Actions​

  • Add - Create a new macro
  • Edit - Open the step editor for the macro (the default row action — editing/clicking a row goes straight to its steps, since that's what you usually want)
  • Delete - Remove a macro
  • Reload - Refresh the grid data

Quick Actions (Toolbox)​

For each macro row:

  • Run Icon - Execute the macro immediately (for testing)
  • Edit Definition Icon (pencil) - Open the macro properties editor (name, label, subsystem, enabled/elevated flags, arguments, expectations)
  • Find References Icon - Show all places in the system that reference this macro (schedules, command macros, AV zones/sources, UI macros, and other macro steps that call it)

The two editors are reciprocal: from the step editor an Edit macro details button opens the properties editor in a modal, and from the properties editor an Edit steps → button opens the step editor in a modal — so you can move between a macro's definition and its steps without losing your place.

Creating a Macro​

To create a new macro:

  1. Click Add in the grid toolbar

  2. Configure the basic macro properties:

    Name: Internal identifier (lowercase_with_underscores)

    • Examples: good_morning, movie_time, all_lights_off

    Label: User-friendly display name

    • Examples: "Good Morning", "Movie Time", "All Lights Off"
    • Shown in UIs and macro selectors

    Subsystem: Logical category

    • Lighting, AV, Security, Climate, etc.
    • Groups related macros
    • Affects where macro appears in UIs

    Enabled: Toggle to enable/disable

    • Disabled macros cannot be executed
    • Configuration preserved

    Elevated: Toggle to restrict execution to elevated roles

    • When on, only users with an elevated role can run the macro (via socket macro, stop_macro, or a command-form macro redirect). Server-side triggers and schedules run regardless of the flag.
    • New macros are created with Elevated = on by default — turn it off for user-triggered scenes, UI macro buttons, and anything intended for non-admin users.
    • Keep it on for macros that arm security, unlock doors, run privileged scripts, or otherwise shouldn't be callable from the user UI.

    Timeout (ms): Maximum execution time in milliseconds

    • Set to limit how long a macro can run
    • Prevents stuck macros from running indefinitely

    Stop on Error: Toggle to halt execution if any step fails

    • When enabled, macro stops at the first step that returns an error
    • When disabled, macro continues to the next step regardless of errors

  3. Click Save

Arguments & Options​

After saving the macro, configure optional arguments:

Arguments: Define parameters the macro can accept when called

  • Add argument names (e.g., level, color, zone_id)
  • Arguments can be referenced in step configurations using {args.name}

Argument Options: Configure default values and constraints for each argument

Expectations​

Expectations define what state the system should be in after the macro runs. They allow GEM to verify that the macro achieved its intended result.

Expectation Fields:

  • System Target: Entity type (zone, device, etc.)
  • Target Object: Specific entity to check
  • Attribute Name: Which attribute to verify
  • Value: Expected value after macro execution
  • Value Type: Data type of the expected value

Editing Macro Steps​

After creating a macro, define what it does:

  1. Edit (or click) the macro row in the grid — the step editor opens directly. (You can also reach it via Edit steps → in the macro properties editor.)
  2. The step editor opens showing current steps
  3. Add, edit, delete, and reorder steps
  4. Click Back when done

Step Editor Interface​

Step List:

  • Shows all steps in execution order
  • Each step displays type and summary
  • Step numbers indicate execution sequence

Actions:

  • + Add Step - Add new step at end
  • Edit - Modify existing step
  • Delete - Remove step
  • ▲▼ - Reorder steps (drag or buttons)
  • Run Macro - Test the entire macro

Common Step Types​

Command Step:

  • Send command to device or zone
  • Configure: Device, Zone, Command, Parameters
  • Example: Turn on living room lights to 75%

Delay Step:

  • Pause execution for specified time
  • Configure: Duration in seconds
  • Example: Wait 2 seconds for device to power on

Macro Step:

  • Execute another macro
  • Configure: Macro ID, Arguments
  • Example: Run "all_lights_off" macro
  • An Edit button next to the macro selector lets you quickly view and edit the referenced macro's steps without leaving the current editor

Notification Step (Web Push):

  • Send web/native push notification to users
  • Configure: Title, Message, Target UIs, Target Users
  • At least one UI or one user must be selected — the step refuses to run with both lists empty (avoids accidental fan-out to every connected client)
  • Example: Send "Good morning" notification

Call Notification Step:

  • Send an incoming call notification to mobile devices
  • Triggers the native incoming call UI (CallKit on iOS, full-screen notification on Android)
  • Configure: Caller Name, Answer URL, Target UIs, Target Users
  • At least one UI or one user must be selected — same fan-out guard as the web push step
  • Override Notification Profile option to send regardless of user notification preferences
  • Only delivered to native mobile app clients — web browsers are skipped
  • Example: Gate intercom rings → call notification with answer URL /controls/gates

Variable Step:

  • Set variable value
  • Configure: Variable name, Value, Type
  • Example: Set "last_macro_run" to current timestamp

Condition Step:

  • Execute sub-steps only if condition met
  • Configure: Condition, True steps, False steps (optional)
  • Example: If home mode, turn on welcome lights

Loop Step:

  • Repeat steps multiple times or for each item
  • Configure: Count or list, Steps to repeat
  • Example: Flash lights 3 times

Script Step:

  • Execute JavaScript code
  • Configure: Code snippet
  • Example: Calculate sunset time and store in variable

Set Site Mode Step:

  • Set or clear the active mode for a Site or Site Space
  • Configure: Mode ID, optional Space ID (defaults to the whole site), or clear=true to drop the mode
  • Example: Goodnight macro sets site mode to night; sunrise macro clears it
  • Honors the mode's hold-enabled flag — a held mode rejects the change

Set Notification Profile Step:

  • Switch a user to a different Notification Profile (e.g., on-call rotation, after-hours quiet mode)
  • Configure: auth_user_id, notification_profile_id
  • Example: A weekly schedule rotates the on-call profile; a vacation macro switches a user to a "muted" profile

Wait For Attribute Step:

  • Pause macro execution until an attribute matches a condition (or a timeout fires)
  • Configure: System target + target ID + attribute name + comparison operator + expected value, plus a max wait
  • Example: After issuing a dim command, wait for the zone's level attribute to reach the target before continuing
  • Returns {matched, aborted} — the next step can branch on success vs. timeout

Camera Snapshot Step:

  • Capture a snapshot from a camera device and store it (e.g. attach to a notification)
  • Configure: Device ID, optional camera identifier
  • Pairs naturally with the notification steps

If Time Step:

  • Conditional branch based on the current time, a date variable (sunrise/sunset/etc.), or a literal time
  • Configure: Comparison expression — e.g. "if before sunset", "if between 22:00 and 06:00"
  • Stops execution when the condition fails (or runs a child macro on each branch)

For Each Step:

  • Loop over a set of zones, devices, subsystems, or a literal list, running a macro per item
  • Configure: source (zones, devices, subsystems, list), optional subsystem filter, target macro, optional max_iterations
  • Example: For each zone in the lights subsystem, run the random_dim macro
  • See Macro context as local variable storage for passing per-iteration state via context
tip

Step types beyond the curated list above (custom or newer drivers) get a generic schema-driven editor automatically — the form is built from each step driver's getMetaData() schema, so any new server-side step type is configurable in the admin without UI work.

Context Simulator​

When editing macro steps, a Context Simulator panel appears above the step editor. It lets you preview how context values (placeholders like [zone_id], [address], etc.) will be resolved at runtime.

Context Types:

  • AV Source Change — Select a zone and source to see AV context values (zone addresses, source device IDs, routing addresses, etc.)
  • Trigger — Select a trigger to load the target entity's current attributes as context
  • Schedule — Select a schedule to load its macro arguments as context
  • Monitor Tag — Select a Monitor Tag and a direction (down / recovery up) to preview the rollup context the engine would emit. Auto-defaults the direction to whichever edge actually references the current macro.

The simulator auto-detects which triggers, schedules, AV sources, and monitor tags reference the current macro and shows counts next to each type.

After selecting a context, click Preview to see the current step's output with all placeholders substituted. The resolved output appears in a green-bordered panel below the context values.

The simulated context is also passed to Test buttons in Email and SMS steps — when you click Test, the message is sent with all context placeholders resolved using the simulated values.

JSON View​

Click View JSON in the step editor to switch between the form-based editor and a raw JSON editor. This is useful for:

  • Copying step data between macros
  • Editing complex step configurations directly
  • Debugging step output

The JSON view applies to the step data only — the action type, timeout, sort index, and enabled fields remain as form controls.

Step Configuration​

Each step has common properties:

Description (optional):

  • Human-readable description of what step does
  • Helps document complex macros

Enabled:

  • Toggle to skip step without deleting
  • Useful for testing and debugging

On Error:

  • Continue: Ignore error and continue to next step
  • Stop: Halt macro execution
  • Retry: Retry step X times before continuing

Running Macros​

Manual Execution​

From Macros Page:

  • Click Run icon in grid
  • An info toast confirms the macro is running
  • On completion, a success or error toast shows the result

From UIs:

  • Macro buttons (if assigned to UI)
  • Macro selector menus
  • Quick access favorites

From API:

await GemApp.getInstance().macro(macroId);

Automated Execution​

Macros run automatically via:

  • Schedules: Time-based (see Schedules)
  • Triggers: Event-based (see Triggers)
  • Access Control: Physical access events
  • Other Macros: Nested macro calls
  • AV Zones: On/off macros
  • Monitor Tags: Down / recovery macros that fire on rollup state transitions (see Monitoring — Tags Tab). Receives monitor_tag_id, previous_state, new_state, trigger_monitor_id/name/ip, rollup_reason, and (on recovery) outage_duration_ms in context.

Execution Monitoring​

Track macro execution:

  1. Navigate to Insights > Activity or Insights > Logging
  2. Filter by macro name
  3. Review execution times, results, errors
  4. Debug failed steps

Run History (in-editor)​

The macro editor has a Run History panel below the steps that lists recent runs of the open macro. Each row shows started-at, status (success / failed / aborted / skipped / running), duration, optional reason, and the cause that started the chain (the upstream trigger, schedule, or user). Clicking a row opens the Cause Chain modal, which walks the chain in both directions:

  • What caused this — the upstream trigger / schedule / auth_user that started the run, with click-through to re-anchor on that record
  • What this caused — any downstream macros, triggers, or schedule fires the run kicked off

Retention is governed by the Automation History settings under Data Retention.

Macro Arguments​

Macros can accept parameters for flexibility:

Defining Arguments​

In macro configuration:

{
  "args": ["level", "color"],
  "arg_types": {
    "level": "int",
    "color": "string"
  }
}

Using Arguments in Steps​

Reference arguments in step configuration:

Command Step:

Zone: living_room_lights
Command: set_level
Level: {args.level}
Color: {args.color}

Calling with Arguments​

From UI macros:

{
  "level": 80,
  "color": "#FF8800"
}

From API:

await GemApp.getInstance().macro(macroId, {level: 80, color: "#FF8800"});

From other macros:

Step: Macro
Macro: set_lighting_scene
Args: {"level": 80, "color": "#FF8800"}

Common Macro Examples​

Good Morning​

Step 1: Delay until 5 minutes before alarm time (from variable)
Step 2: Gradually raise bedroom lights (0% → 30% over 10 minutes)
Step 3: At alarm time: Set lights to 75%
Step 4: Turn on bathroom heat
Step 5: Start coffee maker
Step 6: Turn on morning news (if weekday)
Step 7: Send notification "Good morning!"

Movie Time​

Step 1: Close all shades in theater
Step 2: Dim all lights to 5%
Step 3: Turn on projector
Step 4: Turn on AV receiver
Step 5: Select Blu-ray input
Step 6: Set volume to 50%
Step 7: Delay 5 seconds (equipment warm-up)
Step 8: Play Blu-ray
Step 9: Fade lights to off over 30 seconds

Goodnight​

Step 1: Turn off all first floor lights
Step 2: Turn off all second floor lights (except bedrooms)
Step 3: Delay 30 seconds
Step 4: Turn off bedroom lights
Step 5: Set bedroom lights to 1% (night light)
Step 6: Lock all doors
Step 7: Arm security system (night mode)
Step 8: Set HVAC to sleep mode
Step 9: Close all shades

All Off​

Step 1: Turn off all lights (subsystem: lighting)
Step 2: Turn off all AV zones (subsystem: av)
Step 3: Turn off all fans (subsystem: climate)

Vacation Mode​

Step 1: Lock all doors
Step 2: Arm security (away mode)
Step 3: Set HVAC to vacation mode (minimal heating/cooling)
Step 4: Turn off water heater
Step 5: Close all shades
Step 6: Enable random lighting (vacation mode)
Step 7: Send notification "Vacation mode activated"

Best Practices​

  1. Naming Conventions:

    • Name: Technical, descriptive (good_morning_weekday)
    • Label: User-friendly (Good Morning - Weekday)

  2. Organization:

    • Group macros by subsystem
    • Use consistent naming prefixes
    • Document complex macros

  3. Error Handling:

    • Set appropriate "on error" behavior
    • Add retry logic for critical steps
    • Test error conditions

  4. Timing:

    • Include appropriate delays for device warm-up
    • Don't make delays too long (user experience)
    • Consider async operations when possible

  5. Feedback:

    • Include notification steps for important macros
    • Provide user feedback in UIs
    • Log execution for debugging

  6. Testing:

    • Test macros before assigning to schedules/triggers
    • Test error cases (device offline, etc.)
    • Verify timing of delays

  7. Modularity:

    • Create reusable sub-macros
    • Call sub-macros from parent macros
    • Avoid duplicating logic

Advanced Topics​

Conditional Execution​

Use condition steps for branching logic:

Step 1: Check if home mode
Step 2: If true:
  Step 2a: Turn on welcome lights
  Step 2b: Set HVAC to home temp
Step 3: If false:
  Step 3a: Activate security

Looping​

Repeat steps multiple times:

Step 1: Loop 3 times:
  Step 1a: Turn on light
  Step 1b: Delay 1 second
  Step 1c: Turn off light
  Step 1d: Delay 1 second
(Result: Light flashes 3 times)

Dynamic Values​

Macro step parameters support dynamic value expressions that resolve at runtime. These can reference system variables, other entity attributes, and apply arithmetic.

[level]              → local attribute value
[$sunset]+30         → 30 minutes after sunset variable
[zone.5.level]*2     → double zone 5's level
[device.12.temperature]-5:60:80  → device temp minus 5, clamped 60-80

Use the Dynamic Value Builder (settings icon next to dynamic parameters) to construct expressions visually. See Attributes — Dynamic Attribute Values for full syntax reference.

Parallel Execution​

Execute multiple steps simultaneously:

Not directly supported, but can simulate:

Step 1: Start macro A (non-blocking)
Step 2: Start macro B (non-blocking)
Step 3: Start macro C (non-blocking)
Step 4: Wait for all to complete

Requires custom implementation.

Troubleshooting​

Macro Not Executing​

Check:

  1. Enabled: Macro is enabled
  2. Permissions: User/system has permission to run macro
  3. Trigger: If scheduled/triggered, verify trigger is working
  4. Logs: Check system logs for errors

Macro Runs But Steps Fail​

Check:

  1. Device Online: All devices in steps are online
  2. Step Config: Each step properly configured
  3. Commands: Commands exist and are valid
  4. Timing: Delays may be too short
  5. Order: Steps may need reordering
  6. Script Step Errors: Script step errors in the system log include the macro name, macro ID, step ID, and a stack trace — making it easy to identify which macro and step failed without searching through every macro

Macro Runs Slowly​

Causes:

  • Too many delays
  • Synchronous device operations
  • Network latency

Solutions:

  • Reduce unnecessary delays
  • Use parallel macros for independent operations
  • Optimize device communication

Cannot Edit Steps​

Check:

  1. Macro Exists: Macro saved successfully
  2. Permissions: User can edit macros
  3. Browser: Try different browser
  4. Cache: Clear browser cache
  • Schedules - Time-based macro execution
  • Triggers - Event-based macro execution
  • Devices - Device commands in macros
  • Zones - Zone control in macros