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 class 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
  • Response Set - Associated response set for parsing feedback
  • 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 management page for categorizing devices

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 JSON file (exports selected rows when a multi-selection is active)

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​

  • Commands Icon (remote icon) - Jump directly to the device's command set

Creating a Device​

To create a new device:

  1. Click the Add button
  2. The device editor opens with the General tab active
  3. Configure the basic device settings (see General Tab section below)
  4. Click Save to create the device
  5. Once saved, additional tabs become available for further configuration

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.

Driver Hints​

Selecting a Driver that publishes hints (via getMetaData) pre-fills empty fields in the editor:

  • Device Type — auto-selected from the driver's device_type_hints if no type is chosen yet.
  • Command Set — auto-selected from the driver's command_set_hint, or from the driver name when no explicit hint is set. If a matching command set doesn't exist yet, GEM creates an empty one with that name and shows a confirmation toast. The driver populates it with commands the first time a device using it loads, so any driver that ships a getCommands() table gets zero-touch onboarding.

Hints never overwrite values you've already picked.

Device Editor​

The device editor provides eight tabs for comprehensive device management:

1. General Tab​

Basic Information:

  • Name - Internal identifier (lowercase_with_underscores)
  • Label - Display name shown in UIs
  • Driver - Select from available device drivers
  • Enabled - Toggle device active state
  • Elevated - When on, only users with an elevated role can send commands to this device. Commands that target the device — directly or via a zone — are rejected with not authorized for non-elevated users. New devices default to Elevated = off; turn it on for security panels, locks, gates, and other sensitive equipment.

Network/Connection:

  • Controller - Parent device (for devices connected through a gateway)
  • Address - IP address, serial port, or device-specific identifier
  • Port - Network port for IP-connected devices

Communication:

  • Command Set - Pre-defined commands this device can execute
  • Response Set - Patterns for parsing device feedback
  • Polling Interval - How often to query device status (milliseconds)

Advanced:

  • Device Type - Categorization for UI icons and grouping
  • Connection Timeout - Max time to wait for responses
  • Reconnect Delay - Time between connection retry attempts

2. Attributes Tab​

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

Network Attributes:

  • ip_address - Device 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

The Attributes tab includes a Reload button to force the device to reload its configuration and reconnect.

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​

Lists all zones controlled by this device. The grid shows:

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

Click Edit on any zone to open the Zone Creator in a modal, pre-loaded with that zone — edits save in place without leaving the device editor.

Add Zone in the grid header opens a Zone Creator modal pre-filled with this device — handy for adding zones to a device without leaving the editor. Save the device first if it's new.

4. Script Tab​

The Script tab provides a JavaScript code editor for custom device logic. Device scripts can:

  • Override driver methods (connect(), disconnect(), command(), response())
  • Implement custom communication protocols
  • Add device-specific parsing logic
  • Handle special state management

Key Features:

  • Syntax-highlighted code editor
  • Real-time code execution
  • Access to driver base class methods
  • Debugging console output

Changes are saved automatically, but the device must be reloaded for scripts to take effect.

5. Commands Tab​

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

  • List of all available commands for this device
  • Command parameters and templates
  • Quick command execution for testing
  • Command history

See Commands for detailed information on managing commands.

6. Web Interface Tab​

Some devices (like cameras, DSPs, and network-attached equipment) provide web-based configuration interfaces. When available, this tab:

  • Embeds the device's web interface in an iframe
  • Generates a secure access token
  • Provides toolbar buttons to reload or open in a new tab
  • Sandboxes the interface for security

Requirements:

  • Device driver must implement getWebInterface() method
  • Device must have web_interface_url attribute configured
  • Web interface must allow iframe embedding

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 navigation links.

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 includes 100+ built-in drivers for common equipment:

AV Equipment​

  • denon_avr - Denon/Marantz receivers
  • 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_matrix - Atlona video matrices
  • atlona_atome - Atlona AT-OME / AT-UHD HDMI matrix and presentation switchers (Telnet)
  • kramer_matrix - Kramer switchers
  • biamp_tesira - Biamp Tesira DSP — named level/mute blocks as zones via the Tesira Text Protocol

Lighting​

  • lutron_homeworks - Lutron HomeWorks
  • lutron_ra2 - Lutron RadioRA 2
  • 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
  • nest - Nest thermostats
  • carrier_infinity - Carrier Infinity touch

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_device - MQTT integration
  • modbus_device - Modbus RTU/TCP
  • bacnet_device - BACnet integration

See the Technical Reference for a complete driver list.

Device Types​

Device types categorize devices for UI presentation:

  1. Controller - System controllers and gateways
  2. AV Receiver - Audio/video receivers
  3. Display - TVs, projectors, monitors
  4. Matrix - Video/audio switchers
  5. Processor - Audio processors, DSPs
  6. Camera - IP cameras and NVRs
  7. Thermostat - HVAC controls
  8. Lighting Controller - Lighting gateways
  9. Shade Controller - Window treatment controllers
  10. Lock - Door locks and access control
  11. Sensor - Environmental sensors
  12. Relay - Contact closure devices

Testing and Troubleshooting​

Reloading a Device​

Click the Reload button in the Attributes tab to:

  • Disconnect the device
  • Reload configuration from the database
  • 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: Set polling intervals 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. Documentation: Use the description field to document special configuration notes

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.

Device Scripts​

Advanced users can write custom device scripts in JavaScript. Scripts have access to:

  • this.device - The device object
  • this.attributes - Device attributes
  • this.zones - Associated zones
  • this.log() - Logging functions
  • Base driver methods via inheritance

Dynamic Device Discovery​

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

  • Subsystems - Organizing devices into subsystems
  • Zones - Creating control zones for devices
  • Commands - Managing device commands
  • Drivers - Creating custom drivers
  • Attributes - Understanding device attributes