Skip to main content

Zones

Zones are the fundamental control units in GEM, representing controllable endpoints like individual lights, displays, thermostats, shades, or audio zones. Each zone is associated with a device and can have custom attributes for state management.

Overview​

The Zones page provides comprehensive management of all control zones in your automation system, including configuration, attribute management, and programming impact analysis.

A single device commonly owns many zones — one hardware controller addresses each endpoint individually. For example, a Lutron processor drives every load and shade wired to it as its own zone:

Each zone carries its own Address (the channel, relay, or integration ID the device uses to reach that specific endpoint), so commands sent to a zone route through the shared device to the correct load.

Viewing Zones​

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

  • ID - Unique identifier
  • Name - Internal zone name
  • Label - User-friendly display name
  • Subsystem - Logical grouping (lighting, AV, HVAC, etc.)
  • Device - Parent hardware device
  • Site Space - Room or area the zone belongs to
  • Address - Device-specific address (channel, relay, etc.)
  • Control - Zone control type
  • Enabled - Whether the zone is active
  • Sort Index - Display order in UIs

Grid Actions​

  • Add - Create a new zone
  • Edit - Open the zone editor
  • Delete - Remove a zone (warning: check programming first!)
  • Sort - Reorder zones by dragging rows
  • Reload - Refresh the grid data
  • Import - Import zones from a JSON file
  • Export - Export zones to a JSON file (exports selected rows when a multi-selection is active)

Inline Zone Control​

Each grid row with a configured Control type shows a gear icon in the toolbox column. Clicking it opens the zone's live control in a popup modal, letting you operate the zone without leaving the Zones page. The popup uses the same control component the zone renders in UIs (climate, dimmer, shade, lock, etc.), so changes are real-time and reflect actual device state. The active UI theme is applied inside the modal so buttons and themed controls render with their normal appearance.

If the zone references a user-defined Svelte widget by name in its Control field, the popup loads that widget instead. Rows with no control configured do not show the icon.

Multi-Select & Bulk Operations​

The grid supports selecting multiple cells in a column for bulk editing, exporting, and deleting:

  • Click a cell to select it
  • Ctrl+Click (Cmd+Click on Mac) to add or remove individual cells from the selection (must be in the same column)
  • Click and drag vertically to select a range of cells in a column
  • Escape to clear the selection (works regardless of where focus is)

When multiple cells are selected, the grid toolbar swaps in a selection summary (e.g. "3 cells in 2 rows") alongside two icon buttons:

  • Delete (trash icon) — Delete all selected rows (with confirmation). Only available when the grid supports row deletion.
  • Clear (close icon) — Deselect all cells

Bulk editing: Edit any selected cell and save — the new value is automatically applied to all other selected cells in the same column.

Export Selected: When rows are selected, the Export button changes to Export Selected and exports only the selected rows.

Dynamic Filters​

Column filter dropdowns are context-aware — each column's filter options show only the values that exist in rows matching all other active filters. This makes it easier to narrow down results when multiple filters are applied.

Pagination​

Grids paginate at 50 rows per page. When results exceed one page, a compact pager («/‹/›/» controls + page indicator) appears in the toolbar above the grid alongside the row count, and a full pager appears below the grid with First/Previous/Next/Last buttons and a "Showing X–Y of Z" counter. Sorting, filtering, and clearing filters reset to page 1.

Creating a Zone​

There are two common workflows for creating zones:

From the Zones Page​

  1. Click Add in the grid toolbar
  2. Configure the zone properties (see General Tab section below)
  3. Click Save to create the zone
  4. Once saved, additional tabs become available

From a Device​

When configuring a device that controls multiple zones:

  1. Navigate to System > Devices
  2. Edit the device
  3. In the device editor, you can create zones directly
  4. The zone inherits the device reference automatically

Zone Editor​

The zone editor provides four tabs for complete zone management:

1. General Tab​

Basic Information:

  • Name - Internal identifier (lowercase_with_underscores)
  • Label - Display name shown in UIs and mobile apps
  • Subsystem - Logical category (lighting, av, hvac, shades, etc.)
  • Enabled - Toggle zone active state

Device Assignment:

  • Device - Parent hardware controller
  • Address - Device-specific zone identifier:
    • Channel number (e.g., "1", "2", "3")
    • Relay number
    • DMX address
    • IP address (for networked zones)
    • Unit code
    • Any device-driver-specific identifier

Control Configuration:

  • Control - Zone control type:
    • on_off - Simple binary control (lights, relays)
    • dimmer - Variable level control (dimmers, volume)
    • shade - Position control (shades, blinds)
    • rgb - Color control (RGB lighting)
    • rgbw - Color + white control
    • temperature - Temperature control (thermostats)
    • fan - Fan speed control
    • lock - Lock/unlock control
    • custom - Device-specific control

Advanced Settings:

  • Icon - UI icon name
  • Color - Theme color for UI elements
  • Sort Index - Display order

2. Attributes Tab​

Zone attributes store state and configuration. Common zone attributes include:

State Attributes:

  • power - Current power state ("on" or "off")
  • level - Brightness/volume/position (0-100)
  • input - Selected input source
  • mute - Mute state (boolean)
  • temperature - Current temperature
  • setpoint - Target temperature
  • mode - Operating mode (heat, cool, auto, etc.)

Color Attributes (RGB/RGBW zones):

  • color - RGB hex color (e.g., "#FF0000")
  • hue - Hue value (0-360)
  • saturation - Saturation percentage (0-100)
  • brightness - Brightness percentage (0-100)
  • color_temp - Color temperature in Kelvin

Configuration Attributes:

  • min_level - Minimum allowed level
  • max_level - Maximum allowed level
  • default_level - Default on level
  • ramp_rate - Fade/ramp time in seconds
  • normally_closed - Relay state inversion (boolean). The default assumes a normally-open relay (relay closed = gate/zone open); normally_closed=true inverts it (relay closed = gate/zone closed)
  • relay_states - Custom relay state mapping (JSON)
  • on_action, off_action, open_action, close_action, stop_action - Per-verb command overrides (see Command Overrides below)

Display Attributes:

  • icon - Custom icon name
  • color - UI theme color
  • label_override - Alternative display name

See the Attributes documentation for detailed information on managing attributes.

3. Programming Tab​

The Programming tab provides powerful impact analysis, showing everywhere a zone is used in your system programming.

Search Programming​

The Programming tab automatically searches for references when opened. The search examines:

  • Macros - Macro steps that control this zone (direct and indirect)
  • Triggers - Attribute triggers that act on this zone
  • UI Zones - User interfaces that display this zone
  • Widgets - Dashboard widgets showing this zone
  • Access Control - Rules that control this zone
  • Monitors - Monitors that reference this zone

The search displays results grouped by category with counts:

Found 15 total reference(s): 4 macro(s), 2 trigger(s), 6 UI(s), 2 widget(s), 1 access rule(s), 0 monitor(s)

Schedule Timeline​

When macros that control this zone have enabled schedules, a Schedule Timeline section appears showing upcoming execution times. The timeline includes schedules for both direct macros and indirect parent macros. Each entry displays:

  • Schedule Name — The schedule's name
  • Macro Name — Which macro will run (indirect macros show a chain indicator, e.g., "parent_macro → child_macro")
  • Rule — The cron pattern or variable reference
  • Upcoming Occurrences — Next 5 execution times (for cron-based schedules)

Variable-based schedules (e.g., [$sunset]) are indicated with a "Variable-based schedule" badge since their exact times change daily. Schedules with no upcoming occurrences within their date range show "No upcoming occurrences".

This helps you understand when automation will affect the zone before making changes or deleting it.

Results Display​

Each category shows:

  • ID - Reference ID for navigation
  • Name - Descriptive name of the referencing item
  • Details - Additional context (enabled status, etc.)
  • View Button - Open the referenced macro or trigger in an editor modal so you can inspect or edit it without leaving the zone editor. Saves refresh the programming list.
  • Remove Button - Remove zone from this reference

Macro References:

Direct macro references show the macro name, step number, and step type. If the step includes a command, it is displayed in a code badge:

[45] Macro: good_night - Step 3: command    [off: zone_id=12]

Indirect macro references are parent macros that call a direct macro via a run_macro step. These are discovered recursively up to 5 levels deep and shown with a chain indicator:

[78] Macro: bedtime_routine → good_night - Step 1: run_macro
note

Indirect macro references do not have a Remove button since the zone is not directly referenced in those macros.

Trigger References:

Trigger references indicate whether the zone is used in the trigger's Action, Condition, or both:

[12] motion_lights_on - Action - Enabled: Yes
[15] occupancy_check - Condition - Enabled: Yes
[18] combo_trigger - Action & Condition - Enabled: Yes

UI Zone References:

[88] UI: kitchen_panel - Kitchen Panel - Enabled: Yes

Widget References:

[23] living_room_lights - light_control - Title: Living Room

Access Control References:

[5] front_door_unlock - unlock - Enabled: Yes

Monitor References:

[7] display_power_monitor - Power Zone - Enabled: Yes

Removing References​

Click the Remove button next to any reference to remove the zone from that programming element:

  • Macros: Removes the zone_id from the step data
  • Triggers: Removes the zone_id from trigger actions (not available for condition-only references)
  • UI Zones: Deletes the UI zone binding
  • Widgets: Removes zone_id from widget configuration
  • Access Control: Removes zone_id from control configuration
  • Monitors: Clears the power_zone_id reference

Important: Removing a zone from programming does NOT delete the programming element itself, it only removes the zone reference. For example, removing a zone from a macro step leaves the step intact but without a target zone.

4. History Tab​

Charts the zone's state attribute over time, using the same controls as the Attribute History page. The System Target and Target Object are preset to this zone — pick any history-enabled attribute and a date range to view the chart.

Useful for reviewing how a zone's level, power, or other state has changed, diagnosing unexpected behavior, or correlating zone activity with automation events.

Zone Control Types​

The control type determines how the zone behaves and what commands it accepts:

on_off​

Simple binary control:

  • Commands: on, off, toggle
  • Attributes: power
  • Use for: Lights, relays, switches

dimmer​

Variable level control:

  • Commands: on, off, set_level, raise, lower
  • Attributes: power, level (0-100)
  • Use for: Dimmable lights, volume control

shade​

Position control:

  • Commands: open, close, stop, set_position
  • Attributes: power, position (0-100)
  • Use for: Shades, blinds, drapes, screens

rgb / rgbw​

Color control:

  • Commands: on, off, set_color, set_brightness, set_hue
  • Attributes: power, color, hue, saturation, brightness
  • Use for: RGB/RGBW LED lighting

temperature​

Climate control:

  • Commands: heat, cool, auto, off, set_temp
  • Attributes: power, temperature, setpoint, mode
  • Use for: Thermostats, HVAC zones

fan​

Fan speed control:

  • Commands: on, off, set_speed
  • Attributes: power, speed (low/medium/high or 0-100)
  • Use for: Fans, ventilation

lock​

Security control:

  • Commands: lock, unlock
  • Attributes: locked (boolean)
  • Use for: Door locks, gates

dmx_rgbw​

DMX RGBW color control:

  • Commands: on, off, level, color, white, rgbw
  • Attributes: state, level (0-100), color (hex), red, green, blue, white (0-255)
  • Optional zone attributes: default_white (0-255, default level for "on"); fixture_mode (dimmer / rgb / rgbw / dali, default rgbw)
  • Use for: 4-channel DMX RGBW LED fixtures (also drives eDIDIO fixtures)
  • The control reads fixture_mode and only renders the white slider when it is rgbw; dimmer / rgb / dali fixtures show level and color only

custom​

Device-specific control:

  • Commands: Driver-defined
  • Attributes: Driver-defined
  • Use for: Specialized equipment with unique control requirements

Addressing Zones​

The Address field maps the zone to a specific control point on the device. Format varies by device type:

Channel Numbers​

Most multi-zone devices use simple channel numbers:

1, 2, 3, 4, ...

Relay Addresses​

Relay controllers may use module.relay format:

1.1, 1.2, 2.1, 2.2

DMX Addresses​

DMX fixtures use the starting channel number. The driver automatically maps consecutive channels from that address:

1      (RGBW fixture occupies channels 1, 2, 3, 4)
10     (RGBW fixture occupies channels 10, 11, 12, 13)

Valid DMX start addresses range from 1 to 509 (for 4-channel RGBW fixtures).

IP Addresses​

Networked zones may use IP:port format:

192.168.1.100:8080

Unit Codes​

Some protocols use hexadecimal unit codes:

A1, A2, B1, B2

Integration IDs​

Integration drivers often use unique identifiers:

zone_living_room      (Lutron)
hue_light_5           (Philips Hue)
nest_thermostat_1     (Nest)

Consult the specific device driver documentation for addressing requirements.

Relay State Mapping​

GEM automatically handles relay state translation for different device types. Some devices operate with inverted logic where "relay closed" means different things:

Default Mappings​

Inverted Logic (closed = active):

  • Gates/Garages: closed → open
  • Doors/Locks: closed → unlocked
  • Lifts: closed → open

Direct Logic (closed = active):

  • Lights/Fans/Power: closed → on
  • Shades: closed → closed
  • Security: closed → armed

Custom Mapping​

Override default behavior using the relay_states attribute (JSON):

{
  "on": "closed",
  "off": "open"
}

Or use the normally_closed boolean to invert the default mapping. The default assumes a normally-open relay — relay closed → gate open, relay open → gate closed. Setting normally_closed=true flips it so relay closed → gate closed, relay open → gate open.

Command Overrides​

For exotic hardware that doesn't respond to a subsystem's standard verb (e.g. a shade wired to a relay that needs a momentary pulse instead of an open), set a <verb>_action JSON attribute on the zone. When present, the override is dispatched instead of the generic verb.

Supported attributes: on_action, off_action, open_action, close_action, stop_action.

The value can target a device command:

{
  "command": "pulse",
  "device_id": 7,
  "args": {"address": "1:4", "delay": 500}
}

Or a macro:

{
  "macro_id": 42,
  "args": {}
}

Any caller of the standard verb — UI buttons, macros, triggers, the AI assistant — flows through the override automatically. Only the matching verb is replaced; other commands on the zone behave normally.

:::tip Use sparingly Prefer the right driver and a correct relay-state mapping when possible. Reach for *_action only when the hardware genuinely requires a different command shape than the subsystem's defaults. :::

Best Practices​

  1. Naming Conventions: Use clear, hierarchical names:

    living_room_main_lights
    kitchen_island_pendant
    master_bedroom_ceiling_fan

  2. Labels: Use user-friendly names:

    Living Room Main Lights
    Kitchen Island Pendant
    Master Bedroom Ceiling Fan

  3. Subsystem Assignment: Always assign zones to appropriate subsystems for organization

  4. Sort Index: Order zones logically:

    • By room
    • By function
    • By physical location

  5. Enabled State: Disable zones during:

    • Commissioning
    • Troubleshooting
    • Temporary removal of equipment

  6. Attribute Organization: Store all configuration in attributes rather than hardcoding

  7. Programming Review: Before deleting a zone, use the Programming tab to find and remove all references

  8. Testing: Test zone commands thoroughly before adding to UIs or automation

  9. Documentation: Use the description attribute to document:

    • Physical location
    • Circuit information
    • Special notes
    • Commissioning date

  10. Address Validation: Verify addresses match the physical device configuration

Common Workflows​

Adding Multiple Zones for a Device​

When adding a multi-zone device (like an 8-channel dimmer):

  1. Create the device first
  2. For each channel:
    • Create a new zone
    • Select the device
    • Set address to channel number
    • Configure control type and subsystem
    • Save

Or use the Import feature to bulk-create zones from a JSON file, and multi-select to bulk-edit properties across multiple zones.

Replacing a Device​

When replacing hardware:

  1. Edit each zone
  2. Change the device assignment
  3. Update addresses if different
  4. Test all zones
  5. Disable or delete the old device

Reorganizing Zones​

To change zone order in UIs:

  1. Drag zones into the desired order
  2. Click the Save Sort Order button (swap-sort icon) in the grid toolbar — it appears whenever the grid includes a sort_index column
  3. Confirm the prompt — sort_index is renumbered across all rows currently in view

Advanced Topics​

Virtual Zones​

Zones don't always map to physical devices. Create virtual zones for:

  • Computed states (average temperature)
  • Integration endpoints (voice assistant controls)
  • Macro triggers
  • UI feedback

Assign these to a "virtual" or "system" device.

Multi-Device Zones​

Some zones control multiple devices:

  • All lights in a room
  • Multi-way switching
  • Synchronized AV zones

Use macros to coordinate multiple zones rather than creating dependencies.

Zone Groups​

Group related zones using:

  • Shared subsystem
  • Shared device
  • Custom grouping attributes
  • UI groupings

State Synchronization​

When multiple controls affect the same zone:

  1. Enable attribute history
  2. Use triggers to detect conflicts
  3. Implement priority logic
  4. Subscribe to zone state changes

Troubleshooting​

Zone Not Responding​

  1. Check Enabled: Verify zone and device are enabled
  2. Verify Address: Confirm address matches device configuration
  3. Test Device: Send commands directly to device
  4. Review Logs: Check for communication errors
  5. Check Attributes: Verify required attributes are set

State Not Updating​

  1. Check Response Set: Verify device has response set configured
  2. Enable Logging: View raw device feedback
  3. Test Polling: Verify device polling is working
  4. Review Triggers: Check for conflicting triggers

Programming Not Found​

If Programming search returns no results but you know references exist:

  1. Search was added recently - older programming may not be indexed
  2. Reference may be in a different format (check manually)
  3. Database may need rebuilding (contact support)