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.

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.

Inherited zones in the Zones tab

When you select a space-linked UI in the Zones Tab, the inherited site-space zones appear in the UI Zones list greyed out — they can't be reordered or removed here. Manage them by moving zones in or out of the linked Site Space. Only the explicit overlay rows you add on this page can be reordered or removed. An inherited zone can be made the UI's Default: select it on its own and press Default (see Setting the default zone).

Overview​

The UI Zones page provides four 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
  4. Grid Tab - Spreadsheet editing of the assignments the Zones tab creates

This hierarchical system allows flexible zone organization for complex installations.

Four 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

Grid Tab​

Spreadsheet editing of the assignments themselves:

  • Regroup, reorder and toggle many assignments at once
  • Column filters, multi-cell edit, undo, export
  • Save Sort rewrites the display order from whatever order the grid is sorted in
  • Best for: Bulk cleanup, or reordering by something other than one row at a time

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

Zones already on the selected UI are marked with a ✓ in the left-hand list, so you can see what is left to add without cross-referencing the two lists. Adding one again is a no-op rather than an error, whichever working group is selected: a zone already on the UI under a different group is skipped too, with a message saying how many were.

On a manual UI the UI Zones list also shows the zones assigned to the all UI (UI 0) — every manual UI displays those. They are marked shared with all UIs, greyed out, and can't be selected, reordered or removed here; pick the all UI to edit them. (Space-linked UIs don't read UI 0 rows, so they never appear there.)

Below the UI picker, View all zones for this UI opens the UI's own editor on its Zones tab: every zone across all subsystems, with where each one comes from. On a space-linked UI the banner names the linked site space and links to it — the link opens Site Spaces with that space selected.

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

Working group​

The Working group picker below the zone lists does two things at once, and both are deliberate:

  • it filters the UI Zones list to that group, and
  • it is where Add puts new zones — the Add button names the group it will use.

Leave it empty to see every zone on the UI and add them ungrouped. Set it when you are building out one card, so everything you add lands in the right place.

Ordering zones​

Zone order in the list is the order they appear on the UI. Drag a row to move it; the whole new order is saved in one write when you drop. The ▲ ▼ buttons move a single selected zone one place and are the touch and keyboard path.

Ctrl-click (Cmd-click on a Mac) toggles individual rows, and Shift-click selects a range — useful before Remove.

On a space-linked UI, inherited zones are shown greyed out and cannot be dragged; reordering moves the explicit overlay rows among themselves and leaves the inherited zones where the site space put them.

Setting the default zone​

Default marks the selected zone as the one a control page pre-selects when it opens on this UI — the climate zone the top bar reads its indoor temperature from, the AV zone the media bar starts on, and so on. Select exactly one zone in the UI Zones list and press Default; pressing it again clears the flag. A default zone is shown in green. The flag is stored on the ui_zone row as is_default; pages that read it fall back to the first zone in sort order when no zone on the UI carries it.

On a space-linked UI an inherited zone can be the default too. Inherited zones select one at a time (a plain click; Ctrl-click clears the pick) and only for Default — the reorder and remove buttons ignore them. Because an inherited zone has no ui_zone row of its own, setting Default on one creates a row whose only job is to carry the flag, and clearing it removes that row again. Such a row never adds the zone to the UI a second time, and its group and sort index are not read while the zone is inherited: the site space still decides where the zone appears. The row shows on the Grid tab like any other overlay, so Default can be ticked or cleared there as well.

Removing a zone from every UI​

Remove from all UIs (the red button between the lists) deletes every assignment the selected zones have, on every UI at once — not just the UI picked above. Select the zones in either list: the left list is the subsystem's whole zone set, so a zone can be cleared without first finding a UI it is on. A confirmation names each zone and the UIs it will leave before anything is deleted.

Only explicit assignments go. A zone a space-linked UI inherits from its site space has no assignment row, so it stays on that UI until it is moved out of the space. The Auto add and remove UI controls option applies to the selected UI only, as it does for Remove.

Auto add and remove UI controls looks at every zone the UI has in the subsystem, not just the working group shown, so emptying one group never removes the subsystem's control while other groups still have zones.

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

Cross-references​

Once a UI is chosen, the tab names it under the selectors — Assigning groups to — and that name opens the UI itself in a panel over this page, so you can check what it already shows without losing the assignment list. The hint at the top of the tab links to the Groups tab for creating or renaming the groups themselves; it switches tabs rather than navigating, so the selection you have made is kept.

Zone groups can be installed by an application package. Where any of the groups in scope were, the tab lists them under the selector as Installed by a package, each naming the package it came from and opening it in Applications. Unticking such a group only takes it off this UI; the group itself belongs to the package, so renaming or deleting it on the Groups tab changes what an uninstall of that package removes.

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

Grid Tab​

The Zones tab moves one assignment at a time. The Grid tab opens the same rows in a data grid, for the passes where that is the wrong shape — moving thirty zones into a new group, reordering a panel alphabetically, or auditing which assignments were ever given a sort order.

Scoping​

Pick a Subsystem and a UI. Both are required, and the grid does not load until it has them. That pair is the scope the system orders a UI's zones in, so it is also the scope every reorder here applies to. Clearing either selector unloads the grid rather than leaving the previous UI's rows on screen.

Selecting the All UI (id 0) shows the assignments shared by every UI, which are ordered as their own slice.

Once both are chosen the grid is labelled Overlay rows for , and that name opens the UI in a panel over this page. It opens in place deliberately: a grid can be holding a sort you have not saved yet, and leaving the page would discard it.

Columns​

ColumnEditableNotes
IDnoThe ui_zone row id
ZonenoThe assigned zone. Add and remove zones on the Zones tab
Zone LabelnoThe zone's human-readable label, for scanning the list
Zone GroupyesWhich group card the zone appears under. The picker lists only groups in the selected subsystem
Sort IndexyesDisplay order within the UI and subsystem
DefaultyesThe zone a control page pre-selects when it opens on this UI
EnabledyesUnchecking hides the assignment without deleting it

Double-click a cell to edit it. Drag down a column to select a run of cells and set them all at once — the fastest way to move a block of zones into a new group. Undo in the toolbar reverses the last edit or bulk edit.

Save Sort​

Save Sort writes Sort Index 1…N over exactly the rows shown, in the order shown. Sort the grid by any column first — click Zone Label to order a panel alphabetically, then save, and the UI follows.

The rows shown is the operative phrase. A column filter narrows what gets renumbered, so filtering to one zone group and saving renumbers only that group's rows. That is usually what you want when tidying a single card, and is worth knowing before you filter for some other reason and then save.

Space-linked UIs​

A UI linked to a Site Space derives most of its zones from that space, and those zones have no ui_zone row at all. The grid shows only the explicit overlay rows, so a Save Sort here reorders the overlays among themselves and leaves the inherited zones where the space put them. The page says so above the grid when a space-linked UI is selected.

A row for a zone the UI already inherits contributes only its Default flag — that is how an inherited zone becomes the UI's default (the Zones tab writes such a row for you). Its Zone Group and Sort Index are not read while the zone is inherited.

Arriving from a zone​

The View button beside a UI Zone on a zone's usage list (Zones) opens this page straight onto the Grid tab, scoped to the UI and subsystem that row belongs to. Filter the ID column to isolate the row itself.

?subsystem_id= and ?ui_id= are honoured too, on both the Zones and Grid tabs.

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

The assignment is enforced server-side, not just visually. For a non-elevated user whose every allowed UI carries a zone scope, a command sent over the socket or the REST API is refused when its target is on none of their UIs — and voice commands are confined further, to the single panel they were spoken at. A UI with no zone scope at all (no rows here and no linked Site Space) leaves its users unrestricted, so sites that never scoped their UIs behave as before. See UI scope for commands.

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