Skip to main content

Commission a Device

Goal: add a new piece of hardware to GEM, bring its driver online, and confirm GEM can control it.

This is the deeper version of step 2 of the Quick Start. A device is the controller plus the driver that speaks its protocol; zones are the controllable endpoints that live on it (see Add a Zone).

Before you start​

  • You're logged in as an administrator.
  • You know how GEM reaches the hardware: its IP address (network devices), serial port, or device identifier.
  • The subsystem the equipment belongs to exists (lighting, AV, climate, …).

Steps​

  1. Open Devices and click Add. The device editor opens on the General tab.

    Open Devices

  2. Choose the driver. This is the most important choice — it determines how GEM connects and which commands exist. Selecting a driver that publishes hints will pre-fill related fields for you:

    • The Device Type is auto-selected from the driver's hints.
    • A Command Set is auto-selected (or created empty using the driver name) so the device is ready to receive commands. The driver populates that command set the first time a device using it loads.

    :::tip Zero-touch command sets Any driver that ships a command table gets its commands filled in automatically on first load — you don't hand-author them. See Command Sets in the Admin Reference for the details. :::

  3. Enter the address and label. Give the device a clear Label (what people see) and set its Address (IP, serial port, or identifier). Internal Name is auto-formatted to lowercase_with_underscores.

  4. Set driver-specific attributes. The editor surfaces the settings the chosen driver needs (host, port, credentials, model). Secure fields like passwords and API keys are encrypted automatically — see Concepts → Secure Attributes.

  5. Save. Once saved, the remaining editor tabs (zones, scripting, commands) become available, and GEM brings the driver online.

Verify the connection​

  • Check the device's online/connection state in the grid — a healthy driver reports connected.
  • Use the device's Commands quick action to send a test command and confirm the hardware responds.

If it won't connect, see Troubleshoot a Device.

Next: add zones​

A device on its own controls nothing the user sees — add zones bound to it:

  1. Open Zones, click Add, and place the zone in the right subsystem.
  2. Bind it to this device and set its address on the device (the channel, output, or zone number the driver uses).

Open Zones

Some drivers expose the per-zone address as a labeled picker rather than a raw number — pick from the list when offered.