Lutron

The Lutron page imports zones from Lutron HomeWorks or Lutron QS XML configuration export files. It parses the XML to extract lighting, shade, and fan outputs and creates corresponding GEM zones automatically.

Open Lutron Import

This XML import applies only to the telnet-based HomeWorks and QS processors. RA3, QSX, HomeWorks QSX, and Caséta (Smart Bridge Pro) processors connect over Lutron's LEAP API and never need an XML export — they pair and sync directly, covered in the LEAP section below.

Licensing

Lutron is a premium integration. Adding a Lutron device (lutron_homeworks, lutron_qs, lutron_qsx, or lutron_caseta) — and using this import page — requires the Lutron product in your license. Existing devices keep running if a license later changes. See License.

Prerequisites

Create a Lutron device in System > Devices with the driver set to either lutron_homeworks or lutron_qs. If no matching device exists, the page displays a message directing you to create one first.

Import Configuration

The import section contains the following fields:

Field	Description
Device	Select which Lutron device the imported zones should belong to. Lists all devices with lutron_homeworks or lutron_qs drivers, showing the device name and driver type.
XML File	File upload for the Lutron XML export file. Only .xml files are accepted. After selecting a file, its name and file size are displayed next to the buttons.

Button	Description
Cancel (X icon)	Clears the selected file. Only shown after a file is selected and before import results are displayed.
Import Zones	Starts the import process. Disabled until both a device and file are selected. Changes to "Importing..." during processing. The selected file's name and size (in KB) appear to the right of the buttons.

How the Import Works

The import process parses the Lutron XML file and recursively extracts outputs from nested Area elements. For each output, it:

1. Reads the output's IntegrationID (used as the zone address), Name, and OutputType.
2. Determines the GEM control type based on the Lutron output type (see table below).
3. Assigns the zone to the appropriate GEM subsystem (lights, shades, or fans).
4. Creates a zone name by combining the area name with the output name.
5. Skips the output if a zone with the same address already exists on the device.
6. Appends the address to the name if a zone with the same name already exists.

Output Type Mapping

The following Lutron output types are mapped to GEM control types:

Lutron Output Type	GEM Control Type	Subsystem
CEILING_FAN_TYPE	fan_default	Fans
MLV	light_dimmer	Lights
ELV	light_dimmer	Lights
AUTO_DETECT	light_dimmer	Lights
INC	light_dimmer	Lights
NON_DIM_INC	light_switch	Lights
NON_DIM_FLUORESCENT	light_switch	Lights
EXHAUST_FAN_TYPE	fan_default	Fans
SYSTEM_SHADE	shade_dimmer	Shades

Output types not in this list are skipped with a console warning.

Import Results

After the import completes, a results section appears with two parts:

Summary Cards

Four summary cards are displayed in a row:

Card	Description
Total Zones	Total number of outputs found in the XML file.
Created	Number of zones successfully created (shown in green).
Skipped	Number of zones skipped because a zone with the same address already exists (shown in yellow).
Errors	Number of zones that failed to create due to errors (shown in red).

Details Table

A scrollable table listing every output that was processed:

Column	Description
Status	Badge showing Created, Skipped, or Error.
Zone Name	The Lutron area name combined with the output name (the zone's label).
Address	The Lutron IntegrationID.
Details	For created zones: the generated zone name (a slugified version of the label). For skipped/error zones: the reason.

Import Another File

Click the Import Another File button to reset the form and import a different XML file.

tip

You can safely re-run the import on the same XML file. Zones whose addresses already exist on the device will be skipped, so only new outputs will be created.

Lutron RA3 / QSX / HomeWorks QSX / Caséta (LEAP)

The lutron_qsx driver talks to RadioRA 3, HomeWorks QSX, and QSX processors over Lutron's LEAP API — no XML export needed. The lutron_caseta driver (Caséta Smart Bridge Pro; the standard Smart Bridge does not expose LEAP) is built on the same driver and uses the identical pairing and sync flow described below. Once paired, GEM pulls the processor's zones automatically and can mirror the full Lutron area tree into site spaces, zones, and — optionally — UIs.

Pairing

Add a lutron_qsx (or lutron_caseta) device with the processor's IP address and enable it. GEM reaches the processor over TCP 8081 for ongoing control (LEAP) and TCP 8083 once during pairing, to exchange a client certificate — make sure both ports are open between GEM and the processor on the LAN.

Pairing is a one-time client-certificate exchange, and the order matters:

1. After adding and enabling the device, save and reload it — the driver instance has to reload before it will accept the pair command.
2. Put the processor into pairing mode: on an RA3/QSX processor, press the front-panel pairing button until the ring/LED flashes. LEAP requires verification of physical access, so this can't be triggered from the Lutron app.
3. While the processor is still in pairing mode, run the pair command on the device (Commands tab). GEM exchanges the certificate over TCP 8083 and completes the handshake.

Pairing usually takes under a minute, and the issued certificate is stored encrypted on the device, so it persists across restarts.

Troubleshooting:

• Pair fails — the processor is almost always not in pairing mode. Re-enter pairing mode (hold the front-panel button until the ring flashes) and retry.
• Connects, but no zone or keypad events arrive — the stored certificate may belong to a different processor. Clear the device's LEAP Key Pair and LEAP Certificates attributes, then pair again.

Once paired, GEM automatically pulls the processor's zones and refreshes them about once an hour — you don't import anything by hand. Run sync_areas (below) only when you additionally want GEM to build the matching site spaces, room UIs, and keypad assignments.

sync_areas command

Run from the device's command page (or via a macro) to mirror the area tree:

Argument	Description
create_uis	When true, materialize a UI for any space that does not yet have one. UIs are named from a slugified area name and assigned site_space_id with include_child_spaces enabled. Defaults to false.

What it does:

• Maps the root Lutron project area to your GEM root site space — the single top-level space auto-managed from your This Server site — and records the pairing on that site. Each Lutron area below the root becomes a child site space parented under that root, or an existing space is re-parented to match the current area tree. GEM permits only one root space, so top-level Lutron areas are never created as separate roots. Existing space names and labels are preserved; only the parent relationship is updated.
• Creates any missing zones for the outputs in each area and sets each matched zone's site space (re-linking a zone whose space changed).
• Writes each area's first keypad/control-station id to the lutron_control_station_id attribute on every UI linked to that space. If an area has more than one keypad, the second id goes to lutron_control_station_2_id, the third to lutron_control_station_3_id, and so on. The Lutron Keypad widget reads lutron_control_station_id from the UI it sits on, so dropping the widget onto a synced room's UI resolves that room's keypad automatically; point any extra keypad widgets at the higher-numbered attributes. The Lights control page also reads these attributes — a synced UI gains a Keypad view showing every station in the area, with no further configuration (see UI Controls).
• Never deletes spaces or zones. A space whose Lutron area has disappeared from the processor is reported in orphaned_site_spaces for you to review and remove manually.

The command returns a summary you can read on the device's command page: counts of spaces_created, spaces_updated, and spaces_existing; zones_created, zones_relinked, and zones_existing; uis_created and uis_updated; plus orphaned_site_spaces and any errors.

Setup integration

The Setup page detects when you add a lutron_qsx processor on the Step 3: Discover Devices step and shows a Lutron Sync card per processor:

• Shows a live Paired / Not paired indicator, refreshed every 4 seconds.
• Offers a Mirror Lutron rooms & keypads checkbox (checked by default; the label reads "…when paired" until the processor pairs, then "…now").
• Once the processor pairs with the box checked, Setup automatically mirrors the area tree (running sync_areas with UI creation on). If you'd rather trigger it by hand, a Sync Now button appears on the card after pairing. If pairing finishes after you've left the page, the processor re-runs the deferred sync the next time it reconnects.
• Rooms created by the sync pre-populate the next step's room grid, where they're pre-checked and badged (imported).

Related Documentation

• Devices - Creating Lutron devices
• Zones - Zone configuration