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.

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	Starts the import process. Disabled until both a device and file are selected. Changes to "Importing..." during processing.

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 label of the Lutron output.
Address	The Lutron IntegrationID.
Details	For created zones: the generated zone name. 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 QSX / RA3 / HomeWorks QSX

The lutron_qsx driver talks to the processor over its LEAP API (no XML export needed). Once paired, GEM can mirror the Lutron area tree directly into site spaces, zones, and (optionally) UIs.

Pairing

Add a lutron_qsx device with the processor's IP address, then open the device and follow the on-screen pairing prompt to authorize this controller from the Lutron app or processor web UI. Pairing usually takes under a minute and persists across restarts.

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:

• Creates or relinks GEM site spaces by lutron_area_href (existing space names are preserved).
• Creates any missing zones for outputs in each area and sets site_space_id on matched zones.
• Writes each area's first control station id to lutron_control_station_id on every UI linked to that space (additional stations go to lutron_control_station_id_2, _3, …) so the Lutron Keypad widget resolves automatically.
• Never deletes orphaned spaces or zones — review the returned orphaned_site_spaces list manually.

The result includes spaces_created, spaces_relinked, zones_created, zones_relinked, uis_created, uis_updated, orphaned_site_spaces, and errors.

Setup integration

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

• Displays live pairing state (polled every 4 s).
• Offers a Mirror Lutron rooms & keypads checkbox (default on). Toggling it persists the operator's intent in the device's pending_area_sync attribute.
• Once the processor pairs, Setup auto-runs sync_areas with create_uis=true. The driver also re-runs the deferred sync on its next reconnect if pairing completes after the page closes, then clears pending_area_sync.
• Spaces seeded by the sync pre-populate the next step's room grid and are badged (imported).

Related Documentation

• Devices - Creating Lutron devices
• Zones - Zone configuration