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
  • IP - The device's ip attribute, read live from its attributes rather than stored on the device row
  • Connected - The device's connected attribute: a green dot for connected, red for disconnected, and blank for a device that has never reported a connection state (common for connectionless transports like UDP or IR). Refreshes every 15 seconds while the page is open.

The IP and Connected columns are attribute columns — they sort, filter, and export like any other column, but they are read-only here: double-clicking one never opens an editor, and a bulk edit skips it. Edit them on the Attributes tab, which owns the write. A secure attribute surfaced this way is shown masked and exports masked, so a key is never spread down the grid or into a CSV.

Read-only cells can still be copied: hover one for a copy icon, or focus it and press Ctrl+C — handy for lifting an IP out of the grid, or for grabbing a whole column by dragging down it and copying the selection. See Zones — Copying Values.

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)
  • Change history (row action) - Open that device's Change History in a window, with undo; the grid refreshes after an undo
  • 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​

  • 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.
  • Package Icon (apps icon) - Shown only on a device an application package installed. Hovering names the package and its version; clicking opens it in Applications. Editing or deleting a device a package installed changes what uninstalling that package removes, so the icon is the warning as much as the link. A device you created by hand shows no icon.

/admin/devices?edit_device=<id> opens that device's editor directly, on the General tab. Add &tab=<name> to land on another tab: setup, attributes, zones, script, commands, web, references, history or changes (a tab's slot number also works). A tab the device does not have — Setup without a guided setup panel, Commands without a command set, Web Interface without one — leaves the editor on General and says why. An unknown id shows a "Device not found" notice. ?filter_id=<id> keeps its existing meaning and only scopes the grid to that row.

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, History, and Changes tabs appear; Commands appears when the device has a command set, and Web Interface when the device exposes one
  6. If the driver has a guided setup (see Setup Tab), the editor switches to the Setup tab so you can finish configuring it there

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 closes the scan modal and opens that device straight in this page's editor — the grid's current page, sort, and filters are kept.
  • 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.

Type hints only ever fill an empty field. The command set hint does the same, with one addition: changing the driver also moves the command set, because a command set belongs to a driver — leaving a device on the old driver's set means every command it sends is still formatted with the previous protocol's templates.

  • Still creating the device, so the set on screen is one the hint chose? It follows each driver you try, silently.
  • Editing a saved device, or holding a set you picked yourself? You're asked before anything moves, and declining keeps the set you have.
  • The new driver brings no commands of its own (the generic transports, where you build the commands by hand)? The set is left alone — there would be nothing to move to.

Once a driver change is saved, the device reloads so the new driver goes live and fills its command set. See Changing a device's driver.

Device Editor​

The device editor provides nine tabs for comprehensive device management, plus a Setup tab after General for drivers that have a guided setup:

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). Changing it on a saved device runs the two prompts described under Changing a device's driver.
  • 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.

In the other direction, a driver page opened in Help carries an Open <driver> devices button in its header, which opens this grid filtered to devices using that driver. Help pages for admin screens have the same kind of button, which opens the screen the page describes.

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. When only some of a device's zones are sensitive — an intercom that is also a door strike, a relay board driving both landscape lighting and a gate — flag the individual zone instead so the benign zones stay usable; see Zones.

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.

Two rules govern where a combined command may land:

  • Caller-shaped dispatches are checked per member. When the combiner auto-routes the caller's own command name to a matching member, or broadcasts it, the Elevated flag is evaluated again for each member the command actually reaches. A combiner holding a door lock and a lamp lets an ordinary user drive the lamp, and refuses the lock with not authorized — the caller picked the command, so a combiner can't be used to reach past a member's own elevation setting. On a broadcast, the refusal is reported per member alongside the results rather than dropped. A command-set template route is judged differently: it fixes both the command and the target member in a template only an elevated session can author, so it dispatches as authored even at an elevated member — the admin exposing a curated action, same as a remote key binding (see Elevated devices and macros). Macros, triggers and schedules are unaffected either way.
  • Routing stays inside the member list. A command-set template that routes to a specific device_id only works when that device is one of the Combined Devices; anything else returns target device not found. A member that fails at runtime (offline, bad template) returns its error to the caller — it never falls back to broadcasting the command to every member.

At the bottom, Create Device (or Update Device when editing) saves and Back discards. When editing an existing device, Duplicate, History, Unified 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).

Unified Activity opens Reports with a new Unified Activity report pre-scoped to this device, including commands, access events, alarms, automation runs, and state changes.

Changing a device's driver​

Swapping the driver on a saved device — a TV replaced with a different model, an amp succeeded by a newer one — rewires two things that were written for the old driver, so the editor asks about each before touching it. Neither prompt changes anything until you Save, and picking the original driver again withdraws both.

  1. Attributes. The device's attribute rows (IP, port, model-specific keys, cached state) belong to the old driver. Accept the offer to clear them and the attribute form shows the new driver's defaults with a note that the old rows go on save; decline and the existing values carry over wherever the names match.
  2. Command set. A command set belongs to a driver — its rows are the templates that driver's getCommands() declares. Accept and the Command Set field moves to the new driver's set, creating it if this is the site's first device on that driver; decline and the device keeps the set it has. The prompt is skipped, and the set moves on its own, when the set on screen is only there because a driver hint put it there. It's also skipped when the new driver declares no commands of its own — the generic transports, whose command sets you build by hand — since there would be nothing to move to.

Saving a driver change reloads the device for you. That's what makes the new driver instance live and what fills a newly created command set with the driver's commands, so the Commands tab has rows in it the moment you open it. The toast says so; if the reload fails it says that instead, and you can retry from Reload above.

Setup Tab​

Some devices take more to get working than a list of attributes shows — a keypad needs a zone per key, an action per key, LED colors and a key mode, and the mapping between them is in the manual. For those drivers the editor adds a Setup tab: a guided view built for that device, that shows it live and walks through configuring it.

The Setup tab writes the same attributes, zones and commands you would set by hand. It keeps no settings of its own, so a device set up by hand opens in it correctly, and anything it writes shows up in the Attributes and Zones tabs where you can still edit it directly.

Drivers with a Setup tab today:

DriverWhat the Setup tab does
KanexPro 8-Button IP KeypadLive faceplate (press a key on the wall and it is selected), one-click key and relay zones, key actions, LED test, LEDs that follow a GEM attribute, key mode
Hall Research KeypadKey actions for each keypad macro
Matrix switchers and matrix amps — Kramer, Atlona, Extron, Lightware, RTI Multi-Z AMP, AudioControl, AVPro AC-MAXMatrix Setup: a live crosspoint grid that shows what each output is routed to (and routes on click when you turn that on), port counts, one-click output zones, a routing macro, an AV source per input and an AV zone per output. Global sources are keyed by device, so it refuses a second source on a device that already is one. Assigning an AV zone to an output rewrites only this device's half of the zone's address: a zone whose address is its amp's output (or already uses vr=/ar= addressing) keeps the other half, so the room's volume keeps working — the confirmation shows the address it will get. The picker is offered on every output, so a room can take over an output another zone sits on. Create routing macro refuses if a macro of that name already exists (and says so if it is disabled), and removes the macro it just made if its route step cannot be written; a disabled routing macro is listed but not wired to new sources.
Drivers that can list what they control — UniFi Access, Tuya, OpenSprinkler, Bond BridgeDiscover Zones: asks the device for its doors, devices or stations, shows which already have a zone, and creates zones for the ones you pick with the address, label, subsystem and control filled in. Items whose address the device no longer reports are listed so stale zones are easy to spot. When the driver leaves items out, its reasons are listed under Left out by the device (for example a zone it could not read, or one the hardware reports absent). Addresses match a hand-made zone regardless of case. An item named in a script with no Latin letters is given a zone name from its address instead. The panel tells apart a device that reports nothing (on a Bond Bridge, try Sync from device first), a reply with no list GEM could read, and a refusal — including one from a cloud provider — and it stops rather than creating zones when GEM's own zone list cannot be read.

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
  • command_timeout - Seconds to wait for the driver to answer a command before the caller gets a timeout error (default 120; 0 waits indefinitely). Raise it for devices with long-running commands such as pairing or firmware updates. The command itself is not cancelled — a late reply still reaches the driver.

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), History, and Changes (its change journal, with undo).

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 per-session 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 token is part of the proxied URL (/device_proxy/<device>/<token>/...) rather than a cookie, and GEM rewrites every link, script, stylesheet, image, background request and WebSocket the device page uses so they all carry it. That is what lets the page work inside the sandbox described below: a sandboxed page cannot send cookies, so nothing about the session depends on one. The device's own login cookies are held by GEM for the life of the session and are never handed to the browser. A session lasts four hours and is tied to the admin session that opened it; reopening the tab issues a fresh one.

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).

A device that answers on that URL by redirecting to another scheme or port on itself (typically http:// → https://, as cameras and network gear do) is followed there; GEM keeps every later request for that page on the scheme and port the device named.

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.

GEM reads the device's replies with its own forgiving HTTP reader rather than a strict parser, because the web servers built into older AV gear, amplifiers and controllers often bend the rules: a page with no status line, header lines without a colon, a length header sent twice, a chunked reply that ends when the connection closes, or a connection the device keeps open after the page is complete. Each of those is delivered as the page it is. When a device hangs up part way through, the part that arrived is shown and a warning is logged, so a truncated page points at the device rather than a "Proxy Error" screen. A reply that names no content type is treated as a page when it looks like one, so its links still route through GEM.

Sandboxing — proxy_sandbox​

Proxied device pages are sandboxed by default: GEM serves them into an opaque origin so the device's own scripts cannot read anything belonging to the GEM app that is hosting them. This matters because the proxy puts a third party's markup on GEM's address — without it, any camera, door controller or BMS gateway whose firmware has been tampered with would be running code alongside the admin session that opened it.

Because the session token travels in the URL and GEM keeps the device's cookies itself, the sandbox does not interfere with a device's login or its background requests. A device page that still misbehaves under it (one that inspects its own origin, or embeds a further frame that GEM cannot rewrite) is the exception.

When that happens, set the proxy_sandbox attribute to false on that one device. Every other device stays sandboxed. There is also a site-wide device_proxy_sandbox setting in gem.json, but prefer the per-device attribute — turning it off site-wide to fix one stubborn gateway silently removes the protection from every camera as well. The attribute overrides the site-wide setting in both directions, so proxy_sandbox: true re-arms a single device on a site where the global switch is off.

This tab is admin-only

Because GEM injects the stored web_username / web_password on every proxied request, opening this tab is equivalent to handing out the device's own administrator login. Both the URL lookup and the "does this device have a web interface" check require an elevated session, so the tab never appears for a wall panel or guest account. The session token in the proxied URL is valid for that one device only, and treat that URL as you would the device's password while the session lasts: anyone who has it can reach the device through GEM until it expires or you sign out.

Every proxied request — including the page's own background requests and any WebSocket it opens — is checked against the live session as it goes through, not just when the tab was opened. Signing out closes the tunnel at once rather than leaving it usable for the rest of the session window, and a session that loses elevation loses the tunnel with it.

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.

9. Changes Tab​

Lists every admin edit made to this device and its attributes — who changed what, when, and the values before and after — from the Change History. Click a row to see the field-by-field diff; Undo reverses that change. After an undo the grid, the General form and the Attributes tab reload; if the undo removed the device itself, the editor closes. Open in Change History opens the full page filtered to this device.

This is configuration history. For the device's connection state over time, use the History tab.

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
  • bose_controlspace - Bose ControlSpace ESP/EX processors, PowerMatch and PowerShare amplifiers — Gain and Source Selector modules, physical channels, Groups and Parameter Sets over the ASCII protocol on TCP 10055
  • yamaha_mtx - Yamaha MTX3 / MTX5-D / MRX7-D installation DSP and XMV amplifiers over the remote control protocol on TCP 49280 (level, mute and source parameters addressed from the MTX-MRX Editor project, plus raw parameter get/set)
  • zoom_rooms - Zoom Rooms for Windows/macOS via the ZR-CSAPI control interface on TCP 2244 (join/leave meetings, mic and camera mute, speaker volume, call status as an automation input)

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
  • philips_dynalite - Philips / Signify Dynalite over DyNet 1, through a PDEG / PDEB / PDDEG-S Ethernet gateway (area presets, channel levels, passive state tracking from the broadcast bus)
  • 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)
  • evernvr - EverNVR recorder (auto-discovers cameras, live MJPEG, recorded snapshots, PTZ, button rules, event polling)
  • 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_network - Ubiquiti UniFi Network controller: internet / WAN status (online, active WAN, failover, ISP, latency) and UniFi managed switch control (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.

Command queue and coalescing​

TCP devices don't write to the socket the moment a command is issued. Each device holds its own outgoing queue and releases one command every command_throttle milliseconds (an optional device attribute; 200 by default, and drivers set their own — 50 on an AudioControl amp, 400 on a BenQ projector). The spacing exists because most control protocols drop or mis-parse commands that arrive back to back.

That makes the queue a backlog whenever something issues commands faster than the device drains them — a slider dragged at pointer rate, a macro loop, a group action across many zones on one amplifier. The device keeps executing the backlog after the user has stopped, arriving somewhere they didn't ask for.

Absolute setters coalesce. A command that names a destination rather than a step — currently volume and set_volume — replaces a pending command for the same output instead of queueing behind it. Queue depth per output stays at one and the newest value wins, so an intermediate level on the way to the final one is dropped rather than played back late. The replaced command keeps its place in line, so it goes out when it was already scheduled to.

Everything else queues strictly in order, including volume_up / volume_down. Those are relative steps whose effects accumulate: dropping one changes where the device ends up, so they are never coalesced. The same reasoning rules out pulses, stepping presets and channel digits.

Coalescing keys on the output, not the device, because one amplifier is many rooms — a group volume change still delivers a command to every zone.

note

This applies to commands dispatched from a command set (the normal path — the driver declares volume in getCommands() and GEM fills the template). A driver that builds its own wire frames and sends raw text is invisible to the rule, because a raw frame carries no command name to judge. Such drivers opt in explicitly, and the ones that do are noted on their own driver page.

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.