Skip to main content

Data Model

GEM's configuration is a handful of entity types that reference each other. Understanding how they relate makes the admin interface — and the API — much easier to navigate.

The control hierarchy​

Subsystem ──< Zone >── Device
                │         │
            Site Space   Driver
  • Subsystem — a category of equipment: lighting, shades, climate, AV, security. Everything controllable belongs to one.
  • Device — a physical or virtual controller, driven by a driver, reached at an address (IP, serial port, identifier). A device also carries a command set and response set.
  • Zone — the controllable endpoint a user actually operates ("Kitchen Lights"). A zone belongs to a subsystem, is bound to a device, and has an address on that device (the channel/output/zone number the driver uses).
  • Site Space — a hierarchical model of the building (areas → floors → rooms). Zones can be placed in a space, which lets UIs derive their zone list automatically.

Attributes — the universal value carrier​

Every entity carries attributes: named values keyed by (target_type, target_id, name). Both configuration (an IP address) and live state (current brightness) are attributes. This is central enough to have its own page — see Attributes & the Registry.

The AV layer​

AV builds on top of regular zones:

  • AV Zone — extends a zone with AV behavior: on/off macros, a matrix address, a volume device, and an av_type (audio or video).
  • AV Source — a content source bound to a device (for transport control), assigned to one AV zone or marked global to appear in all.

See the AV guides.

Automation entities​

  • Macro — an ordered sequence of steps; the unit of automation and scenes.
  • Trigger — watches an attribute and runs a macro when a condition is met (event-driven).
  • Macro Schedule — runs a macro by clock/cron or relative to sunrise/sunset (time-based).

Presentation entities​

  • UI — a dashboard instance. Its zones come from ui_zone rows (manual) or a linked Site Space (space-linked). It carries UI Controls (navigation), UI Macros (scene buttons), and UI Pages (widget layouts).

Access entities​

  • Role — a set of allow/deny permission rules. User — an account holding one or more roles. See RBAC.
  • Access Control rules link physical credentials (PIN/RFID/REX/call) to actions.

Live state vs stored configuration​

The database holds the configuration of these entities and their history. Their current values live in the server's in-memory collections (gem.devices, gem.zones, gem.subsystems, gem.avZones, …) with attributes merged on. Read current state from memory, not the database — see Architecture.