Skip to main content

Commission a Device

Goal: add a new piece of hardware to GEM, bring its driver online, confirm GEM can actually talk to it, and get its zones in place.

This is the deeper version of step 2 of the Quick Start. A device is the physical controller plus the driver that speaks its protocol; zones are the controllable endpoints that live on it — see Next: zones.

Before you start​

  • You're logged in as an administrator.
  • You know how GEM reaches the hardware: IP address and port, serial port, cloud account, or — for gear hanging off another controller — its address on that controller.
  • Any credentials the equipment needs (web password, API key, integration user) are in hand.
  • The subsystem the equipment belongs to exists (lighting, shades, climate, AV, security). Auto-created zones land in a subsystem the driver picks by name, so a missing subsystem is why zones silently fail to appear.

Open the editor​

Open Devices and click Add in the grid toolbar. The device editor opens on the General tab; the other tabs stay hidden until the device is saved.

Open Devices

The General tab is a single form in four sections, top to bottom: Basic Information, Connection Settings, Device Configuration, and Command Configuration. Fields marked with a red asterisk are required.

1. Basic Information​

  • Name — the internal name. Lowercase letters, numbers and underscores only; it reformats itself when you tab out of the field. This is what you'll reference elsewhere in the system, so keep it short and stable (kitchen_amp, not amp_2_new_final).
  • Label — the display name people see (Kitchen Amplifier).

2. Device Configuration — pick the driver first​

Skip past Connection Settings for a moment and choose the Driver. This is the most important choice on the page: it determines how GEM connects, which commands exist, and which settings the form asks you for.

Selecting a driver immediately does three things:

  • Type is auto-filled from the driver's own hint (controller, media_player, thermostat, …) if you haven't already picked one. Sub Type is optional; the + icons beside either field create a new one on the spot, and Sub Type needs a Type selected first.
  • A blue driver information panel appears, showing the manufacturer, the category, and — for the drivers that publish them — Before you start, Setup steps, Known quirks, and a collapsible Troubleshooting list. Read these before wiring anything; they carry the model-specific gotchas. Drivers written in-house on the User Drivers page often publish nothing, in which case no panel appears.
  • If a full integration page exists for that driver, a View integration guide link appears in the panel. Expanding it renders the complete driver page — wiring, protocol detail, per-command reference — inline in the editor, so you don't have to leave the form.
Zero-touch command sets

A Command Set is auto-selected in the Command Configuration section below, or created for you named after the driver if none exists yet (you'll see a created command set toast). It starts empty. The driver fills it in with its full command list the first time a device using it loads — you never hand-author those rows. See Command Sets.

3. Device Attributes — the driver's own settings​

Once a driver is selected, a Device Attributes section renders the settings that driver actually needs — IP address, port, credentials, model, protocol options. This is where the connection details go, not in the Address field.

  • Only required attributes show at first. A Show N optional attributes toggle underneath reveals the rest. Optional settings you leave alone still get their documented defaults when you save, so collapsing them never changes the resulting configuration.
  • Password and API-key fields render masked and are stored encrypted — see Concepts → Secure Attributes.
  • Fields with a fixed set of choices render as drop-downs, on/off settings as switches, and numeric settings enforce the driver's own minimum and maximum.
  • If the driver ships example configurations, Load sample: … buttons appear beside the section title. Clicking one fills the attribute fields with a working shape you then edit — the fastest way to see what a driver expects.
note
The IP lives in ip

Drivers read the IP address from an attribute named ip (not ip_address) and the port from port. If you later add attributes by hand on the Attributes tab, the names have to match exactly what the driver expects or the driver won't see them.

4. Connection Settings — Controller and Address​

These two fields are for hardware that hangs off another GEM device rather than connecting on its own.

  • Controller — the parent controller device, if this equipment lives behind one (a keypad on a lighting processor, a relay channel on a relay board, an output on a matrix).
  • Address — this device's identifier on that controller: matrix output number, relay channel, bus or integration address. Leave both blank for anything that connects directly over the network or a serial port.
A shortcut that cleans up after itself

For TCP and HTTP drivers you can type 192.168.1.50:4999 into Address instead of filling the IP and Port attributes. On the first connect GEM moves those values into the ip and port attributes and clears the Address field. If you come back and find Address empty, that's what happened — the values are on the Attributes tab.

5. Command Configuration​

  • Command Set — required. Normally already filled in by the driver (see above). The + icon beside the label opens a dialog to add or import a set by hand.
  • Status — the enable switch, on by default. A disabled device is never loaded and never connects.
  • Elevated — leave off for ordinary equipment. Turn it on for security panels, locks, gates, and other sensitive hardware: only elevated roles can then send commands to it.

Click Create Device. (Back abandons the form.)

6. Bring it online​

Saving writes the device — it does not connect it. A brand-new device sits idle until you load it.

  1. Click Reload in the editor's button row. GEM instantiates the driver with the saved configuration and, if Status is on, connects it.
  2. Or click Test Connection, which does the same reload and then watches for up to ten seconds for the driver to report in, giving you a verdict instead of a fire-and-forget toast:
    • ● Connected — the transport opened.
    • ● Disconnected — recheck address, port, and credentials.
    • ● No state reported — the driver doesn't track connectivity. Not a failure; verify by sending a command instead.

Once saved, the rest of the editor unlocks: Attributes, Zones, Script, Commands, Web Interface, References, and History. (Commands only appears when the device has a command set.)

7. Verify it responds​

  • Back in the Devices grid, each row carries a small status dot — green connected, red disconnected, grey no state reported. Hover for the wording. It refreshes on its own every fifteen seconds.
  • Click the remote icon on the device's row to jump straight to its Commands tab, then fire a known-safe command (power_on, get_status) and watch the hardware react. If the device has no command set yet, you'll be told so instead.
  • The History tab plots the device's connection state over time — useful for catching gear that connects and then drops.

If it won't come up, work through Troubleshoot a Device.

Next: zones​

A device on its own controls nothing anyone sees. Zones are the controllable endpoints.

Check the Zones tab before you create any by hand. Many drivers enumerate the hardware on first connect and create their own zones — thermostat groups, amplifier outputs, fan controllers, camera channels — already bound to the device and addressed correctly. If they're there, you're done; just relabel them for the site.

Disable unwanted auto-zones, don't delete them

A driver that creates its own zones re-creates any it can't find on the next connect, so a deleted zone comes straight back. Turn the zone's Status switch off instead (it's the Enabled column in the grid) — drivers skip disabled addresses and won't recreate them.

If the driver doesn't create zones, add them yourself from the device's Zones tab (or the main Zones page):

  1. Click Add, then give the zone a Name and Label.
  2. Under Zone Configuration, set the Subsystem it belongs to. Control picks the on-screen control the zone renders with — a dimmer slider, a shade control, a thermostat. There's no automatic fallback, so a zone left without one shows nothing when it's placed on a UI page; set it now unless you're deliberately leaving the zone off the interface.
  3. Under Device Assignment, confirm the Device and type the Address — the channel, output, relay, or zone number the driver uses for that endpoint. The hint under the field changes to the selected driver's own description of what belongs there; read it, because the format is driver-specific. Leave it blank only when the driver's hint says an address isn't used.
  4. Some drivers also declare per-zone settings, which appear as their own attribute section on the zone form with the same required/optional split as the device form.

Open Zones

Commissioning several identical units​

For keypad farms, amplifier racks, or a row of matching thermostats, build and test one device completely, then use Duplicate in its button row. You're asked for a new name and a number of copies (up to 64), and — if the device has zones — whether to copy those too.

Each copy carries the original's attributes, including the encrypted ones, so credentials come along. Copy 6 of keypad produces keypad_1 through keypad_6. Zone addresses are preserved, since they identify the channel on each new device; only the addresses that differ per unit (usually the IP) need editing afterward.