Skip to main content

Devices

Devices represent physical or virtual hardware controllers in your automation system. Each device uses a driver to communicate with specific equipment like AV receivers, lighting controllers, HVAC systems, and more.

When a command is issued, the server resolves the zone to its device and address, the driver translates it to the device's native protocol, and any feedback flows back as a live attribute update:

Overview​

The Devices page provides comprehensive management of all connected devices, including configuration, testing, zone management, custom scripting, and command execution.

Viewing Devices​

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

  • ID - Unique identifier
  • Name - Internal device name
  • Label - User-friendly display name
  • Driver - Driver used for communication
  • Controller - Parent controller device (if applicable)
  • Address - Network address, serial port, or device identifier
  • Command Set - Associated command set for sending commands
  • Elevated - Whether the device requires an elevated role to command
  • Enabled - Whether the device is currently active

Header Actions​

  • Scan Network - Opens a network discovery modal (ARP sweep with optional TCP port scan). See Scanning the Network below.
  • Device Types - Opens the Device Types page for managing the available device categories. Open Device Types

Grid Actions​

  • Add - Create a new device
  • Edit - Open the device editor
  • Delete - Remove a device (also deletes associated device scripts)
  • Reload - Refresh the grid data
  • Import - Import devices from a JSON file
  • Export - Export devices to a CSV or JSON file (exports selected rows when a multi-selection is active; use JSON when re-importing)

Multi-Select & Bulk Operations​

Select multiple cells in a column to bulk-edit, export, or delete. Click to select, Ctrl+Click to toggle individual cells, or click-and-drag to select a range. See Zones — Multi-Select for full details on selection and bulk operations.

Quick Actions​

  • Connection Dot - Each row shows a live connection indicator: green (connected), red (disconnected), gray (no connection state reported). The state refreshes every 15 seconds while the page is open.
  • Commands Icon (remote icon) - Opens the device editor on its Commands tab. If the device has no command set, a "Device has no command set configured" notice appears instead.

Creating a Device​

To create a new device:

  1. Click the Add button
  2. The device editor opens with the General tab active (the other tabs stay hidden until the device exists)
  3. Fill in the required fields — Name, Driver, Type, and Command Set. Selecting the driver typically fills in Type and Command Set for you (see Driver Hints) and reveals the driver's own connection fields
  4. Click Create Device to save
  5. Once saved, the Attributes, Zones, Script, References, and History tabs appear; Commands appears when the device has a command set, and Web Interface when the device exposes one

Scanning the Network​

The Scan Network header button opens a modal that runs an ARP sweep of the broadcast domain and (optionally) a TCP port-range scan to identify services. Results show vendor (from MAC OUI), open ports, and a top driver suggestion with a confidence score.

  • Hosts already linked to a GEM device are highlighted, show an Already in GEM pill with the device label and ID, and display the configured driver in the Suggested Driver column. Clicking the IP jumps to that device.
  • Click Import on a new host to open the device editor prefilled with the discovered IP, MAC, and a sensible port (443 if open, otherwise 80, otherwise the only open port). Those values are written to the device as readonly attributes (ip, port, mac_address) once the device is saved.

For full scan controls — interface picker, IP range, port range, Quick Scan, and bulk-monitor creation — see Monitoring — Scan Tab. Bulk-monitor creation is hidden in this modal because monitor management lives on the Monitoring page.

info

Network discovery is part of the Network Monitoring module. If your license doesn't include it, the scan returns an error. Adding devices manually is always available. See License.

Driver Hints​

Most drivers pre-fill empty fields the moment you pick them, so you rarely start from a blank form:

  • Type — set to the driver's suggested device type when you haven't chosen one yet.
  • Command Set — set to the driver's command set (named after the driver when it has no specific suggestion). If no command set by that name exists yet, GEM creates an empty one and shows a confirmation toast; the driver fills it with its commands the first time a device using it connects. A brand-new integration is therefore ready to command with no manual command setup.

Hints never overwrite values you've already picked.

Device Editor​

The device editor provides eight tabs for comprehensive device management:

1. General Tab​

The General tab is the device form itself. Four fields are required — Name, Driver, Type, and Command Set — and the editor won't save until all four are filled. The form runs top to bottom through these sections:

Basic Information

  • Name (required) — internal identifier; lowercase letters, numbers, and underscores only (e.g. living_room_receiver). Typed text is normalized to that format when you leave the field.
  • Label — friendly display name shown in UIs (e.g. "Living Room Receiver").

Connection Settings

  • Controller — for a device reached through a gateway, the parent controller. Only devices whose Type is controller appear in this picker.
  • Address — the device's identifier on that controller (matrix output number, relay channel, bus address, etc.). Leave blank for a device that connects directly.

Device Configuration

  • Driver (required) — the communication driver for this equipment. Picking one loads the driver's info panel and attribute fields below (see Driver Hints).
  • Type (required) — the device type used for icons and grouping. The + icon beside it creates a new type on the spot. See Device Types.
  • Sub Type — optional finer category under the chosen type. You can type a new value in directly, or use the + icon beside it to create a subtype under the selected type. Subtypes are also managed on the Subtypes tab of the Device Types page.

Driver info panel — when the selected driver ships descriptive metadata, a panel appears under the driver picker with the manufacturer, a description, a Before you start prerequisites list, numbered Setup steps, Known quirks, and a collapsible Troubleshooting list. This is the integration's own commissioning guidance for the gear you're wiring — read it before continuing. (Drivers that publish only the bare minimum show no panel.)

When a matching per-driver page exists (one of the entries in the Drivers group of Help), the panel also shows a View integration guide toggle. Expanding it renders the full driver documentation — the canonical long-form setup, wiring detail, and tables — inline, without leaving the form. While the guide is open the short quick-start prose hides so you never see the same content twice; collapse it to return to the at-a-glance metadata.

Device Attributes — the connection and configuration fields the chosen driver needs (IP, port, baud rate, username/password, API key, poll interval, and so on) render here, generated from the driver. Required attributes show first; click Show N optional attributes to reveal the rest. Secure fields (password, API key, …) render as masked inputs. If the driver ships sample configurations, Load sample: … buttons fill the fields with a worked example. Leaving an optional field blank applies the driver's declared default on save. The fields differ per driver — there is no universal "Port" or "Polling Interval" field; those appear only when the driver declares them. (You can also manage these later on the Attributes tab.)

Command Configuration

  • Command Set (required) — the set of commands this device can run. The + icon adds or imports a command set. Picking a driver usually fills this in for you (see Driver Hints).
  • Status — the on/off toggle for whether the device is active. New devices default to on (enabled). (The grid column for this is labeled Enabled.) Disabling a device also hides its zones from end-user UIs — a zone with no live device to route commands to would otherwise render as a dead control. Zones that can still dispatch without the device (AV zones, ONVIF camera zones, and zones with <verb>_action overrides pointing at another device or a macro) stay visible, and admin pages always show everything. The zones reappear as soon as the device is re-enabled.
  • Elevated — when on, only users with an elevated role can send commands to this device; commands that target it — directly or through one of its zones — are rejected with not authorized for everyone else. New devices default to off; turn it on for security panels, locks, gates, and other sensitive equipment.

Device Combiner — when the Driver is device_combiner, an extra section lets you pick a Subsystem and a set of Combined Devices. A command sent to the combiner auto-routes to whichever member device defines a matching command name — useful for presenting several physical units as one logical device.

At the bottom, Create Device (or Update Device when editing) saves and Back discards. When editing an existing device, Duplicate, History, Activity, Reload, and Test Connection buttons also appear.

Duplicate deep-copies the device: its attributes (including secure ones) come along, and if the device has zones you can optionally duplicate those with their attributes too. A copy count turns one duplicate into a batch — copy 6 of keypad produces keypad_1 … keypad_6, each with attributes and zones. Zone names are re-derived from the new device name so copies stay distinct; zone addresses are kept since they identify the channel on the (new) device.

Test Connection reloads the device and then watches its connected attribute for up to ten seconds, reporting a green/red verdict inline — a much stronger commissioning signal than the plain Reload toast. "No state reported" means the driver doesn't track connectivity (common for connectionless transports like UDP or IR).

Activity jumps to the unified activity timeline pre-scoped to this device (commands, automation runs, alarms, and state changes in one feed).

2. Attributes Tab​

Custom attributes store device-specific configuration and runtime state. Common device attributes include:

Network Attributes:

  • ip - Device IP address (drivers read ip, not ip_address)
  • port - Communication port
  • mac_address - Physical MAC address

Authentication:

  • username - Login username
  • password - Secure password (automatically encrypted)
  • api_key - API authentication key (automatically encrypted)

Driver Configuration:

  • baud_rate - Serial communication speed
  • parity - Serial parity setting
  • stop_bits - Serial stop bits
  • delimiter - Command/response delimiter character

Runtime State:

  • power_state - Current power status
  • input - Selected input source
  • volume - Current volume level
  • temperature - Current temperature reading

Attribute names must match exactly what the driver expects (this is why the IP lives under ip, not ip_address). These are the same fields the driver renders as Device Attributes on the General tab — edit them there during setup or here afterward.

A Reload Device button at the bottom of the editor (and the Reload button on the General tab) forces the device to disconnect, reload its configuration, and reconnect — use it after changing attributes.

Secure Attributes​

Attributes with specific names are automatically encrypted:

  • password
  • api_key
  • private_key
  • secret
  • token

Encrypted values are stored using AES-256-GCM encryption and are never displayed in plain text.

3. Zones Tab​

The full Zones management surface, scoped to this device — the same grid and editor as the standalone Zones page, so anything you can do there you can do here without leaving the device. The grid shows:

  • Zone ID, Name, Label
  • Subsystem assignment
  • Zone address (channel, relay number, etc.)
  • Control type
  • Enabled status
  • Sort index

Grid actions match the Zones page: Add, Edit, Sort, Reload, and Delete. The settings icon on a row with a control type opens Zone Control (a live control popup for that zone). New zones are pre-filled with this device; save the device first if it's new.

Edit opens the zone in a tabbed editor in place: General, Attributes, Programming (every macro, trigger, schedule, UI, widget, access rule, and monitor that references the zone, with inline remove/view), and History.

4. Script Tab​

The Script tab lets you transform a device's traffic with custom JavaScript without writing a full driver. It has two syntax-highlighted editors:

  • Command Script — function command(cmd, device, gem) { … return cmd; } runs on every outgoing command. Inspect or rewrite cmd and return the (possibly modified) command to send.
  • Response Script — function response(resp, device, gem) { … return resp; } runs on data coming back from the device. Inspect or rewrite resp and return it for normal parsing.

Both functions receive the device object and a gem handle for system calls. Use them to massage payloads, patch a quirk, or add device-specific parsing on top of the driver — they do not replace the driver's connect/disconnect logic.

An Enabled toggle controls whether the scripts run; leave it off and the device behaves as if no script exists. Click Save to store both scripts (saving is not automatic), then Reload the device for the changes to take effect.

5. Commands Tab​

Available only for devices with an assigned Command Set. This tab provides:

  • The full list of commands in this device's command set
  • Each command's template and arguments
  • A Test runner to fire a command at the device and see the result

See Commands for editing commands and Command Sets for how they're grouped.

6. Web Interface Tab​

Some devices (cameras, DSPs, switches, and other network gear) host their own web configuration page. This tab embeds that page inside GEM, proxied through a short-lived access token so you don't have to leave the admin interface or expose the device directly. The toolbar offers Reload and Open in New Tab.

The tab only appears when GEM can find a web URL for the device — either:

  • a web_interface_url device attribute pointing at the page, or
  • an ip attribute together with a protocol attribute of http or https (GEM then builds the URL from the IP on the default web port).

If the device's page needs a login, set web_username and web_password attributes and GEM passes them through. Some device pages refuse to be shown inside a frame; if the embedded view stays blank, use Open in New Tab.

7. References Tab​

Shows all places in the system that reference this device. Click the Find References button to search. Results are grouped by category (zones, macro steps, AV sources, monitors, etc.) with counts and View buttons. Most categories open the referenced entity's editor in a modal so you keep your place on the current page; a few complex ones (monitors, access control) navigate to the entity's admin page with a filter applied.

This is useful before deleting a device to understand its impact across the system.

8. History Tab​

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

Useful for diagnosing intermittent connectivity, reviewing reconnect events, or correlating device drops with other system activity.

Driver Selection​

GEM ships 200+ built-in drivers for common equipment. A representative few are below; every integration also has its own page under Integrations with the full command and attribute reference.

AV Equipment​

  • denon_receiver - Denon AV receivers over the serial-over-IP Telnet API (power, volume, mute, input, status polling)
  • marantz_receiver - Marantz AV receivers and pre-pros (same Sound United protocol as Denon, Marantz-leaning input codes)
  • anthem_mrx - Anthem MRX 540/740/1140 receivers and AVM 70/90 processors over IP (volume in dB and %, listening modes, ARC status, OSD, streaming metadata, zone 2)
  • sony_projector - Sony projectors
  • epson_projector - Epson projectors
  • pjlink - PJLink projectors and displays (open JBMIA standard; Epson, NEC, Panasonic, Sony, Christie, BenQ and most other commercial brands)
  • atlona_atome - Atlona AT-OME / AT-UHD HDMI matrix and presentation switchers (Telnet)
  • biamp_tesira - Biamp Tesira DSP — named level/mute blocks as zones via the Tesira Text Protocol

Lighting​

  • lutron_qsx - Lutron RadioRA 3 / QSX processors via the LEAP protocol over TLS (certificate pairing; lights, shades, fans, keypads, scenes)
  • lutron_caseta - Lutron Caséta via the Smart Bridge Pro LEAP API
  • lutron_homeworks - Lutron HomeWorks (legacy/Illumination) via the Integration Access Port
  • philips_hue - Philips Hue bridge
  • nanoleaf - Nanoleaf Shapes / Canvas / Lines / Elements panels via local OpenAPI
  • tasmota - Tasmota-firmware ESP8266/ESP32 devices (Sonoff, Tuya-flashed plugs/switches/dimmers/bulbs)
  • tuya_cloud - Tuya / Smart Life cloud bridge for any device paired in the Tuya/Smart Life app
  • generic_dmx - DMX base driver via Art-Net (Enttec ODE or compatible nodes)
  • dmx_rgbw - DMX RGBW fixtures (4-channel: R, G, B, W)
  • edidio - Creative Lighting eDIDIO Series 10 DALI/DMX controller (Protobuf-over-TLS, not Art-Net; one controller, per-fixture zones with fixture_mode)

HVAC​

  • ecobee - Ecobee thermostats (cloud REST API; setpoint, system/fan mode, temperature/humidity feedback)
  • carrier_infinity - Carrier Infinity Touch
  • honeywell_tcc - Honeywell Total Connect Comfort thermostats
  • venstar_colortouch - Venstar ColorTouch thermostats (local API)
  • daikin_brp - Daikin BRP-series Wi-Fi adapters

Generic Drivers​

  • generic_tcp - TCP/IP communication
  • generic_http - HTTP/REST APIs
  • generic_serial - RS-232/RS-485
  • generic_ir - Infrared control

Security & Cameras​

  • axis_camera_station - Axis Camera Station Pro NVR (auto-discovers cameras, PTZ presets, snapshots)
  • onvif - ONVIF IP cameras
  • vapix - Axis VAPIX devices (PTZ, relays, privacy masks, audio, events)
  • vapix_ptz - Axis VAPIX PTZ cameras (legacy, uses vapix internally)
  • vapix_relay - Axis VAPIX relay outputs (legacy, uses vapix internally)
  • visca_ip - VISCA over IP PTZ cameras (open Sony standard; PTZOptics, Vaddio, Lumens, Marshall, Sony BRC/SRG, etc.)
  • salto_ks - Salto KS cloud access control (online lock/unlock, lock roster, audit-feed events)

Power & Electrical​

  • span_panel - SPAN smart electrical panel via local REST API (auto-discovers circuits and creates zones)
  • unifi_switch - Ubiquiti UniFi managed switches via the UniFi Network Controller (per-port PoE enable/disable/power-cycle, port enable/disable, live PoE power and link state)
  • cyberpower - CyberPower UPS (battery/runtime/line telemetry, self test, output control) and switched PDU (per-outlet on/off/reboot) over SNMP

Irrigation​

  • rainbird - Rain Bird controllers via the LNK WiFi module (local API, zone run/stop, rain sensor feedback, program start)
  • hydrawise - Hunter Hydrawise v2 GraphQL cloud API (email/password login, zone run/stop/suspend/resume, controller-wide actions; no API key required)

Integration Drivers​

  • mqtt - Generic MQTT client (declarative publications bind attribute changes to topics; subscriptions run scripts on incoming messages)
  • modbus - Modbus master for both Modbus/TCP and Modbus/RTU (coils, discrete inputs, input and holding registers)
  • bacnet_ip - BACnet/IP building-automation integration (objects, COV, alarms, trending)

See the Integrations section for the full per-driver reference.

Device Types​

A device's Type drives its icon and how it groups in lists. A fresh install seeds these default types (you'll see them in the Type picker):

controller, tv, audio_receiver, media_player, camera, projector, thermostat, dvr, cable_receiver, satellite_receiver, plc, light, audio_matrix, lock, pump, transceiver, video_matrix, security_system, intercom, and power_controller.

The list is not fixed — add your own with the + icon beside the Type field, or manage the full set on the Device Types page (Open Device Types). The controller type is special: only devices of that type appear in another device's Controller picker, so give your gateways and processors that type first.

Testing and Troubleshooting​

Reloading a Device​

Click Reload (on the General tab) or Reload Device (at the bottom of the Attributes tab) to:

  • Disconnect the device
  • Reload configuration from storage
  • Re-establish the connection
  • Reinitialize the driver

This is useful after changing attributes or scripts.

Viewing Logs​

Device communication is logged in the system logs. To view:

  1. Navigate to Insights > Logging
  2. Filter by device name or driver
  3. Review connection events, commands, and responses

Testing Commands​

Use the Commands tab to send test commands and verify device responses.

Best Practices​

  1. Naming: Use descriptive names that identify the device's location and type (e.g., living_room_receiver)
  2. Labels: Use friendly names for end users (e.g., "Living Room Receiver")
  3. Polling: when the driver exposes a poll-interval attribute (often status_interval, in milliseconds) in the Device Attributes section, set it appropriately:
    • Fast changing state (displays, receivers): 2000-5000ms
    • Slow changing state (thermostats): 10000-30000ms
    • Static devices: 0 (disabled) or 60000ms
  4. Attributes: Store all configuration in attributes rather than hardcoding in scripts
  5. Error Handling: Implement robust error handling in device scripts
  6. Testing: Always test devices thoroughly before putting into production
  7. Notes: a device has no free-text description field — if you need to record commissioning notes, add them as a device attribute so they stay with the device

Advanced Topics​

Parent/Child Device Relationships​

Some devices communicate through a parent controller:

  • Lutron integration devices parent to the Lutron processor
  • Relay modules parent to the main relay controller
  • Zones in a matrix switcher parent to the matrix device

Set the Controller field to establish these relationships. Only devices whose Type is controller appear in the Controller picker, so give your gateways and processors that type first.

A child device has no network connection of its own — the controller owns the physical link. The child's online/offline state therefore mirrors its parent controller: when the controller connects or drops, every device parented to it follows, and that state shows in the device list, the connected attribute, and Device Health history. Because the controller's link is the real failure point, only the controller raises the Device Offline and connection-flapping alarms — its children go quiet with it without producing a duplicate alarm per device.

Device Scripts​

The Script tab lets you hook a device's traffic without authoring a full driver. The Command Script function command(cmd, device, gem) runs on each outgoing command and the Response Script function response(resp, device, gem) runs on each incoming message; each receives the device object and a gem handle and returns the value to use. Turn on the Enabled toggle and reload the device to apply.

Dynamic Device Discovery​

Some integration drivers (MQTT, ONVIF, BACnet) support automatic device discovery. Check the integration-specific documentation for details.