Skip to main content

UI Macros

UI Macros makes macros accessible from user interfaces. By assigning macros to UIs, you create quick-access buttons for automation sequences like scenes, modes, and complex commands.

Overview​

UI Macros allow users to:

  • Execute automation sequences with one tap
  • Access frequently-used macros quickly
  • Trigger scenes (Good Morning, Movie Time, Good Night)
  • Run complex multi-step operations
  • Pass parameters to macros from UI

Interface Layout​

The UI Macros page uses a three-column layout:

Left Panel - Macro configuration:

  • Macro selector
  • Arguments editor
  • Display name
  • Icon selection

Center - Action buttons:

  • Add ▶ - Add macro to UI
  • ◀ Remove - Remove macro from UI

Right Panel - Current UI macros:

  • List of macros assigned to selected UI
  • Sorted by display order
  • ▲ ▼ buttons to reorder
  • Edit Macro button (or double-click a row) to open the selected macro in a modal over this page

Configuration​

Subsystem Selector​

Select the subsystem to work with:

  • Filters macros to those belonging to the subsystem
  • Limits choices to relevant macros
  • Required before selecting macro

Example: Select "Lighting" to see lighting-related macros

UI Selector​

Select the target UI:

  • Choose which UI to add macros to
  • Shows macros currently assigned to this UI
  • Required for add/remove operations

Example: Select "Kitchen Panel" to manage kitchen panel macros

Adding a Macro to a UI​

  1. Select Subsystem (e.g., Lighting)

  2. Select UI (e.g., Living Room Panel)

  3. In left panel, configure macro:

    Macro - Select from subsystem macros

    • Choose the automation to make available
    • Only macros from selected subsystem appear

    Args - Optional macro arguments (JSON)

    • Provide parameters to macro
    • Format: {"param": "value"}
    • Example: {"scene": "movie", "brightness": 30}

    Name - Display name for UI button

    • What users see on the macro button
    • Can differ from macro name
    • Example: Macro name "activate_movie_scene" → UI Name "Movie Time"

    Icon - Icon filename

    • Icon shown on macro button
    • Located in theme's /icons/ directory
    • Example: movie, bed, sun, moon

  4. Click Add ▶ button

  5. Macro appears in right panel (Current UI Macros)

  6. Macro button now appears in the UI under the subsystem control

Removing a Macro from a UI​

  1. Select Subsystem
  2. Select UI
  3. In right panel, select the macro to remove
  4. Click ◀ Remove button
  5. Confirm removal
  6. Macro no longer appears in that UI

Note: This doesn't delete the macro, only removes it from this UI.

Editing an Assigned Macro​

The right panel lists each entry as Display Name [macro_name], so this page is usually where a wrong or misnamed macro gets noticed. Fix it without leaving:

  1. Select one macro in the right panel
  2. Click Edit Macro — or double-click the row

The macro editor opens in a reference modal over this page, so the Subsystem and UI selections that scope the whole page survive the edit. Close the modal and the assigned list re-reads, so a renamed macro shows its new name immediately.

Selecting more than one row (or none) reports that exactly one must be selected rather than guessing which to open.

The Subsystem, UI, and Macro pickers open their own records the same way — once a value is selected, an Open in editor icon appears beside the picker and loads that subsystem, UI, or macro in the same modal.

Note: This edits the macro itself, so changes apply everywhere it is used — not just on this UI. To change only what this UI shows, edit the Name, Icon, or Args fields in the left panel instead.

Reordering UI Macros​

Macros display in the order specified by sort_index:

  1. In right panel, select a macro
  2. Click ▲ to move up (earlier in list)
  3. Click ▼ to move down (later in list)
  4. Order updates immediately

Display Impact: Macro buttons in the UI appear in this order.

Macro Arguments​

Macros can accept parameters that customize their behavior:

Static Arguments​

Set when assigning macro to UI:

{
  "brightness": 75,
  "color_temp": 2700,
  "scene_name": "evening"
}

Macro steps can reference these arguments:

  • {args.brightness} → 75
  • {args.color_temp} → 2700
  • {args.scene_name} → "evening"

Use Cases​

Scene Variations:

Macro: set_lighting_scene
UI Macro 1: "Bright" - Args: {"level": 100}
UI Macro 2: "Dim" - Args: {"level": 30}
UI Macro 3: "Night" - Args: {"level": 10}

Same macro, different arguments, different buttons

Location-Specific:

Macro: announce_message
UI Macro (Kitchen): Args: {"location": "kitchen"}
UI Macro (Bedroom): Args: {"location": "bedroom"}

Macro announces to appropriate audio zone based on location

Common Workflows​

Adding Scene Buttons to a UI​

To add "Good Morning", "Good Night", and "Movie Time" to living room panel:

  1. Select Subsystem: Lighting (or "Scenes" if you have one)

  2. Select UI: Living Room Panel

  3. For each scene:

    Good Morning:

    Macro: good_morning
    Args: {} (none needed)
    Name: Good Morning
    Icon: sun

    Click Add ▶

    Good Night:

    Macro: good_night
    Args: {} (none needed)
    Name: Good Night
    Icon: moon

    Click Add ▶

    Movie Time:

    Macro: movie_scene
    Args: {} (none needed)
    Name: Movie Time
    Icon: movie

    Click Add ▶

  4. Use ▲ ▼ to arrange in desired order

  5. Macros appear as buttons in living room panel

Creating Mode Buttons​

For "Home", "Away", and "Vacation" modes:

  1. Create macros for each mode (see Macros)
  2. Select Subsystem: Security (or System)
  3. Select UI: Main Panel
  4. Add each mode macro with appropriate icons
  5. Users can switch modes with one tap

Adding All-Off Buttons​

For "All Lights Off" per floor:

  1. Create macros:
    • first_floor_lights_off
    • second_floor_lights_off
  2. Select Subsystem: Lighting
  3. Select UI: Main Panel
  4. Add each macro: 
    Name: "First Floor Off"
    Icon: power_off

Macro Display in UIs​

Where Macros Appear​

UI Macros appear in control pages, organized by subsystem:

Example: In Lighting control page:

┌─────────────────────────┐
│     LIGHTING            │
├─────────────────────────┤
│ Zones:                  │
│ ☐ Entry Hall            │
│ ☐ Living Room           │
│ ☐ Kitchen               │
├─────────────────────────┤
│ Macros:                 │
│ [🌅 Good Morning]       │
│ [🌙 Good Night]         │
│ [🎬 Movie Time]         │
│ [⚡ All Off]            │
└─────────────────────────┘

Macro Button Appearance​

Macro buttons typically display:

  • Icon (if specified)
  • Name
  • Loading state when executing
  • Success/failure feedback

Icons​

Macro icons are stored in the active theme's /icons/ directory.

Standard Macro Icons​

Common icons for macros:

  • sun - Morning/day scenes
  • moon - Night scenes
  • movie - Entertainment scenes
  • bed - Bedtime scenes
  • power_off - All off macros
  • home - Arrival scenes
  • away - Departure scenes
  • party - Party modes
  • dinner - Dining scenes

Upload custom icons via UI > UI Themes page.

Best Practices​

  1. Descriptive Names: Use clear names users will understand

    • Good: "Movie Time", "Goodnight", "All Off"
    • Bad: "macro_1", "scene_a", "test"

  2. Logical Grouping: Assign macros to appropriate subsystems

    • Lighting macros → Lighting subsystem
    • Security macros → Security subsystem
    • Multi-subsystem macros → Choose primary subsystem

  3. Limit Quantity: Don't overcrowd UIs with too many macros

    • 3-6 macros per subsystem is reasonable
    • More than 10 becomes cluttered

  4. Icon Consistency: Use consistent icon style from theme

  5. Ordering: Place most-used macros first

  6. Testing: Test macros before adding to UI

  7. Arguments: Document macro arguments in macro description

  8. Naming Conventions: Differentiate macro name from UI display name

    • Macro name: activate_movie_scene (descriptive, technical)
    • UI name: "Movie Time" (user-friendly, concise)

Advanced Topics​

Macro Arguments Object Editor​

The Args field uses the ObjectEditor component:

Simple Key-Value:

{"level": 80}

Complex Objects:

{
  "scene": "evening",
  "zones": [1, 2, 3],
  "settings": {
    "brightness": 50,
    "color": "#FF8800"
  }
}

Arrays:

["zone_1", "zone_2", "zone_3"]

Conditional Macros​

Create UI macros that behave differently based on args:

Macro: set_scene

UI Macro 1: "Bright"

Args: {"scene": "bright", "level": 100}

UI Macro 2: "Reading"

Args: {"scene": "reading", "level": 80, "color_temp": 4000}

UI Macro 3: "Relax"

Args: {"scene": "relax", "level": 30, "color_temp": 2700}

The macro reads args.scene, args.level, etc. and sets zones accordingly.

Macro Templates​

For similar UIs with different macros:

  1. Create standard set of UI macros for template UI
  2. Duplicate UI
  3. Modify macro assignments as needed
  4. Saves time vs. adding macros individually

Troubleshooting​

Macro Button Not Appearing​

Check:

  1. Subsystem Match: Macro subsystem matches control subsystem
  2. UI Assignment: Macro is assigned to correct UI
  3. Macro Enabled: Macro itself is enabled (Automation > Macros)
  4. Control Enabled: UI control for subsystem is enabled
  5. Browser Cache: Clear cache and reload

Macro Button Not Working​

Check:

  1. Macro Valid: Macro executes successfully when run manually
  2. Arguments: Verify JSON arguments are valid
  3. Permissions: User role allows executing macros
  4. Macro Steps: All steps are valid and configured
  5. Logs: Check system logs for errors

Wrong Arguments Passed​

Check:

  1. JSON Format: Args must be valid JSON
  2. Quotes: Use double quotes for JSON (not single)
  3. Syntax: ObjectEditor validates on save
  4. Macro Compatibility: Macro must support the arguments

Cannot Remove Macro​

Check:

  1. UI Selected: Verify UI is selected
  2. Subsystem Selected: Verify subsystem is selected
  3. Macro Selected: Select macro in right panel before clicking Remove
  4. Permissions: User has permission to modify UI macros