Subsystems

Subsystems are logical groupings that represent the major functional areas of your installation — lighting, AV, climate, security, shades, and so on. Every zone belongs to exactly one subsystem, and a subsystem can optionally point at the hardware controller that runs it.

Overview

GEM creates a standard set of subsystems automatically the first time it boots, so on most jobs you never have to create one — you simply file zones under the subsystem that already fits. You add a new subsystem only when you have a functional area the defaults don't cover.

The subsystem's name is not just a label. Three different parts of the system look a subsystem up by name, so the standard names matter:

• Relay interpretation — a relay-driven zone reads a raw open/closed contact, and what that contact means (on/off, open/closed, armed/disarmed) is decided by the zone's subsystem name. See Relay Semantics.
• Driver zone placement — when a device driver creates its zones on connect (a lighting controller, a shade gateway, a sprinkler controller, etc.), it files them under the matching standard subsystem by name. Keep the standard names and those zones land in the right place automatically.
• Built-in control screens — the security arming screen looks up security, the AV screens look up av, the camera viewers look up cameras, the weather tile looks up weather, and so on. Renaming one of these can make the matching screen stop finding its zones.

Open it from Admin → System → Subsystems: Open Subsystems

The default subsystems

On a fresh install GEM creates these 17 subsystems, each enabled, with a label derived from the name. The right-hand column shows how a relay contact is interpreted for zones in that subsystem (assuming a normally-open relay, where a closed contact is the active/energized state); subsystems marked — have no built-in relay mapping.

Name	Typical use	Relay contact (closed →)
av	AV zones, matrix routing, receivers, sources	—
cameras	IP cameras, NVR channels	—
climate	Thermostats, HVAC, dampers	—
doors	Door locks / access points	unlocked
fans	Fans, exhaust	on
fire	Fire / life-safety contacts	on
gallery	Image galleries / screensaver slideshows	—
garages	Garage door openers	open
gates	Driveway / entry gates	open
irrigation	Sprinkler / irrigation valves and controllers	—
lifts	Lifts, elevators, TV lifts	open
lights	Lighting loads, dimmers, contactors	on
power	Energy monitors, PDUs, power control	on
security	Alarm panels, arming	armed
shades	Window shades / blinds	open
water	Pumps, pools / spas, water features (and the fallback for irrigation valves on older sites)	on
weather	Weather display zones / weather data	—

A subsystem whose name isn't one of the relay-mapped rows above (for example climate, cameras, or any custom name you add) passes a relay contact through unchanged — for relay-driven hardware under such a subsystem you supply a per-zone relay_states override, covered in Relay Semantics.

warning

Treat the default subsystems as fixed: add new ones, but avoid renaming or deleting the ones GEM created. Drivers, relay mapping, and built-in control screens resolve these by name, so renaming security, av, lights, etc. can quietly break automatic zone placement and the matching control screen.

Viewing subsystems

The main grid lists every subsystem with these columns:

• ID — Unique identifier (zones reference their subsystem by this ID).
• Name — Internal name (lowercase with underscores).
• Device — Optional associated hardware controller.
• Enabled — Whether the subsystem is marked active.
• Sort Index — Display order in user interfaces.

Grid actions

• Add — Create a new subsystem.
• Edit — Open the subsystem editor.
• Delete — Remove a subsystem. This is blocked while zones, macros, UI zones, or UI macros still reference it (see Deleting subsystems).
• Sort — Reorder subsystems by dragging rows; the new order is stored as the Sort Index.
• Reload — Refresh the grid data.

Creating a subsystem

1. Click Add in the grid toolbar.
2. Under Basic Information, fill in:
   • Name — Internal identifier. It is auto-formatted to lowercase_with_underscores when you click away from the field, and must contain only lowercase letters, numbers, and underscores.
   • Label — User-friendly display name (any text).
3. Under Configuration, set the optional fields:
   • Device — Pick the hardware controller this subsystem maps to, if any (optional).
   • Enabled — Leave on to make the subsystem active.
4. Click Save Subsystem.

Zones filed under a custom subsystem surface through the generic zone-grid control screen (/controls/<name>), and the subsystem's tile on the controls page shows a live N active headline with no extra setup — a zone counts as active when it reports a level above zero or any state that isn't a common at-rest word (off, closed, idle, standby, normal, …), so a custom vocabulary like heating or running lights the tile automatically. See Tile Status Headlines.

Naming convention

• Name: lowercase letters, numbers, and underscores only (e.g. landscape_lighting). If you want a relay-driven custom subsystem to inherit a built-in contact meaning, name it so it contains a standard name — the relay lookup also matches a trailing s, so gate resolves like gates and light like lights.
• Label: any human-readable text (e.g. "Landscape Lighting").

Editing a subsystem

Click Edit next to a subsystem to open the editor, which has three tabs.

Subsystem tab

Edit the basic properties — Name, Label, Device, and Enabled — then click Save Subsystem. The Name field is editable, but renaming one of the default subsystems is discouraged for the reasons in the warning above; rename only subsystems you created yourself.

Attributes tab

Subsystem attributes store extra configuration. Attributes are free-form, but the ones GEM itself reads are:

• relay_states (JSON) — Per-subsystem relay contact → state overrides for relay-driven zones, e.g. {"closed": "open", "open": "closed"}. See Relay Semantics.
• arm_enabled (true/false) — On the security subsystem, enables the arm/disarm controls on the security screen.
• deadband (degrees) — Default climate deadband for the climate subsystem.

See Attributes for how to add and edit attributes.

References tab

Click Find References to list everything that points at this subsystem — Zones, Macros, UI Zones, and UI Macros — grouped by category with counts and View buttons (zones and macros open in a modal editor in place; UI zones/macros navigate to their admin page). Check this before deleting a subsystem to understand its impact.

Deleting subsystems

A subsystem cannot be deleted while anything still references it. Zones, macros, UI zones, and UI macros all hold a link back to their subsystem, and the database rejects the delete (you'll get an error) as long as any of those rows remain. Deleting a subsystem never cascades — it does not remove its zones or reassign them for you.

To remove a subsystem:

1. Open the References tab and click Find References to see what depends on it.
2. Reassign or delete each referencing zone, macro, UI zone, and UI macro (move the zones to another subsystem on the Zones page).
3. Once nothing references the subsystem, the Delete action will succeed.

Tips

• Use the defaults: file zones under the existing standard subsystems wherever they fit — that keeps relay interpretation, driver zone placement, and the built-in control screens working with no extra setup.
• Add, don't rename: create a new subsystem for a genuinely new functional area instead of repurposing a default one.
• Device assignment: set the Device field when the whole subsystem maps to one hardware controller; leave it blank otherwise.
• Enable / disable: the Enabled flag lets you mark a subsystem inactive without deleting its configuration.
• Sort order: the Sort Index sets the display order of subsystems in user interfaces and mobile apps.

Related Documentation

• Zones — Creating control zones inside a subsystem
• Devices — The hardware controllers behind a subsystem
• Attributes — Adding subsystem attributes such as relay_states
• Relay Semantics — How relay contacts map to zone states by subsystem