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

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.

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