Skip to main content

UI Zones

UI Zones determines which zones appear in each user interface. By assigning zones to UIs, you control what users can see and control on different panels and devices.

:::info Manual UIs and space-linked overlays UI Zone rows are the primary zone source for manual UIs (UIs without site_space_id). For space-linked UIs, the zone list is derived from the linked Site Space — but ui_zone rows on a space-linked UI are still honored as overlays, layered on top of the inherited set. This is useful for adding zones that don't live in the space (e.g. a shared front-gate camera). See Space-Linked vs Manual UIs. :::

Overview​

The UI Zones page provides three methods for organizing zones:

  1. Zones Tab - Direct zone assignment to UIs
  2. Groups Tab - Create zone groups for easier management
  3. UI Groups Tab - Assign zone groups to UIs

This hierarchical system allows flexible zone organization for complex installations.

Three Tabs Explained​

Zones Tab​

Direct management of individual zone assignments:

  • Assign specific zones to specific UIs
  • Fine-grained control
  • Best for: Simple installations or final adjustments

Groups Tab​

Create logical groupings of zones:

  • Group related zones together
  • Organize by room, function, or area
  • Reusable across multiple UIs
  • Best for: Organizing zones before assignment

UI Groups Tab​

Bulk assignment of zone groups to UIs:

  • Add entire groups to UIs at once
  • Efficient for complex installations
  • Manage group order within UIs
  • Best for: Large installations with many zones

Zones Tab​

Direct zone to UI assignment.

Components​

Subsystem Selector

  • Filter zones by subsystem (lighting, av, shades, etc.)
  • Narrows zone list for easier selection

UI Selector

  • Choose target UI for zone assignment
  • Shows current zone assignments

Zone Assignment Interface

  • Select zones to add/remove from UI
  • Configure zone-specific UI settings
  • Set sort order for zones

Workflow​

  1. Select a Subsystem (e.g., Lighting)
  2. Select a UI (e.g., Kitchen Panel)
  3. Select zones from available zones list
  4. Click Add to UI
  5. Zones now appear in the selected UI
  6. Users can control these zones when using this UI

Groups Tab​

Create and manage zone groups for organizational purposes.

Zone Groups​

Zone groups are named collections of zones within a subsystem:

Example Zone Groups:

Subsystem: Lighting
  - Group: First Floor
    - Entry Hall
    - Living Room
    - Dining Room
    - Kitchen

  - Group: Second Floor
    - Master Bedroom
    - Guest Bedroom 1
    - Guest Bedroom 2

Subsystem: Shades
  - Group: South Facing
    - Living Room Shades
    - Dining Room Shades

  - Group: North Facing
    - Kitchen Shades
    - Bedroom Shades

Creating a Zone Group​

  1. Click Add Group (or similar action)
  2. Configure:
    • Name - Group name (e.g., "First Floor Lights")
    • Subsystem - Parent subsystem
    • Zones - Select zones to include
    • Sort Index - Group display order
  3. Save the group

Editing Zone Groups​

  1. Select a zone group
  2. Add or remove zones
  3. Rename if needed
  4. Save changes

Impact: Changes to zone groups automatically update all UIs using that group.

UI Groups Tab​

Assign zone groups to UIs in bulk.

Interface​

Subsystem Selector

  • Choose subsystem to work with
  • Filters zone groups

UI Selector

  • Choose target UI
  • Shows currently assigned groups

Zone Groups Multi-Selector

  • Left side: Available zone groups for subsystem
  • Right side: Groups assigned to this UI
  • Select groups and they appear in both UI and control

Workflow​

  1. Select Subsystem (e.g., Lighting)
  2. Select UI (e.g., Kitchen Panel)
  3. Zone Groups list populates with lighting groups
  4. Check the groups to assign (e.g., "First Floor Lights", "Kitchen Island")
  5. Groups automatically added to UI when checked
  6. Uncheck to remove groups from UI

Reordering Groups​

Use the ▲ ▼ buttons to change group order:

  1. Select a group from the list
  2. Click ▲ to move up (earlier in navigation)
  3. Click ▼ to move down (later in navigation)
  4. Order affects display in UI control pages

Common Workflows​

Simple Installation - Direct Assignment​

For homes with few zones:

  1. Use Zones Tab
  2. Select subsystem
  3. Select UI
  4. Add individual zones directly
  5. No need for groups

Complex Installation - Group-Based​

For large installations:

  1. Use Groups Tab to organize:

    Create group: "Main Floor Lighting"
    Add zones: Entry, Living, Dining, Kitchen

    Create group: "Upstairs Lighting"
    Add zones: Master, Guest 1, Guest 2, Hallway

  2. Use UI Groups Tab to assign:

    Kitchen Panel:
      - Main Floor Lighting

    Master Bedroom Panel:
      - Upstairs Lighting

Multi-Location Installation​

For multi-building facilities:

  1. Create zone groups per building:

    Group: Building A Lighting
    Group: Building B Lighting

  2. Create UIs per location:

    UI: Building A Panel
    UI: Building B Panel

  3. Assign groups to appropriate UIs:

    Building A Panel → Building A Lighting
    Building B Panel → Building B Lighting

Guest Access​

Create limited guest UI:

  1. Create UI: guest_panel
  2. Create zone group: "Guest Accessible"
  3. Add only guest-appropriate zones:
    • Guest bedroom lights
    • Guest bathroom lights
    • Common area lights
    • Guest room temperature
  4. Assign "Guest Accessible" group to guest_panel
  5. Guest UI shows only permitted zones

Zone Group Benefits​

Organizational Benefits​

  • Clarity: Zones grouped by location or function
  • Reusability: Same group can be used in multiple UIs
  • Maintenance: Update group once, affects all UIs
  • Consistency: Ensures consistent zone sets across UIs

Practical Example​

Scenario: Adding a new zone

Without Groups:

  1. Add zone to kitchen_panel
  2. Add zone to mobile_app
  3. Add zone to main_panel
  4. Add zone to guest_panel (maybe)
  5. Repeat for each UI

With Groups:

  1. Add zone to database
  2. Add zone to appropriate zone group
  3. All UIs using that group automatically include the zone

Zone Assignment vs. Zone Group Assignment​

Direct Zone Assignment (Zones Tab)​

Pros:

  • Simple and direct
  • Full control per zone
  • No intermediate groups needed

Cons:

  • Manual assignment to each UI
  • Difficult to maintain with many UIs
  • Repetitive for common zone sets

Best for:

  • Simple installations (< 20 zones, < 3 UIs)
  • Special cases (unique zones in specific UIs)

Zone Group Assignment (Groups + UI Groups Tabs)​

Pros:

  • Bulk assignment
  • Reusable groups
  • Easy maintenance
  • Consistent across UIs

Cons:

  • More setup initially
  • Additional abstraction layer
  • Overkill for simple installations

Best for:

  • Complex installations (> 20 zones, > 3 UIs)
  • Multi-location systems
  • Frequently changing zone assignments

Zone Group Hierarchy​

Zone groups respect subsystem boundaries:

Subsystem: Lighting
  └─ UI Zone Group: Main Floor
      └─ Zones: Entry, Living, Dining, Kitchen

Subsystem: Shades
  └─ UI Zone Group: Main Floor
      └─ Zones: Living Shades, Dining Shades

Each subsystem has its own groups.

When assigning to UIs, you assign groups per subsystem.

Security Considerations​

Zone Access Control​

Zones assigned to a UI can be controlled by any user who can access that UI.

Combine with Roles:

  • Assign zones to UI
  • Use roles to restrict which users can access the UI
  • Result: Only authorized users can control those zones

Sensitive Zones​

For security-critical zones (locks, gates, alarms):

  1. Create dedicated UI (e.g., security_panel)
  2. Assign sensitive zones only to this UI
  3. Create role that allows access only to security_panel
  4. Assign role only to authorized users
  5. Optional: Require PIN on security UI control

Advanced Topics​

Dynamic Zone Display​

Zones in UIs can be shown/hidden based on:

  • Time of day (via themes)
  • User role
  • System mode
  • Zone availability

This requires custom control components or theme JavaScript.

Zone Filtering​

Control components can filter displayed zones:

  • By subsystem
  • By group
  • By attribute
  • By device status

Check control component documentation for filtering options.

Programmatic Zone Assignment​

Assign zones via API:

// Assign zone to UI
await GemApp.getInstance().insertModel('ui_zone', {
    ui_id: 5,
    zone_id: 123,
    subsystem_id: 2,
    enabled: true
});

// Remove zone from UI
await GemApp.getInstance().deleteModel('ui_zone', {
    ui_id: 5,
    zone_id: 123
});

Troubleshooting​

Zones Not Appearing in UI​

Check:

  1. Zone Assignment: Zone is assigned to UI (via Zones or Groups tab)
  2. Zone Enabled: Zone itself is enabled (System > Zones)
  3. UI Enabled: UI is enabled
  4. Subsystem Enabled: Parent subsystem is enabled
  5. Device Online: Device controlling zone is online
  6. Browser Cache: Clear browser cache and reload

Zone Group Not Showing​

Check:

  1. Group Created: Zone group exists in Groups tab
  2. Zones in Group: Group has zones assigned
  3. Subsystem Match: Group subsystem matches selected subsystem
  4. UI Assignment: Group is assigned to UI in UI Groups tab

Cannot Add Zones to Group​

Check:

  1. Subsystem Match: Zones must be in same subsystem as group
  2. Zone Already Added: Zone may already be in the group
  3. Zone Enabled: Zone must be enabled

Changes Not Reflecting in UI​

Solutions:

  1. Reload the UI (browser refresh)
  2. Use Reload All button in UIs page
  3. Force logout and log back in
  4. Clear browser cache