Lutron

The Lutron page is the workbench for every Lutron processor GEM supports — pairing, project import, zone testing, keypad layouts, scenes and a live protocol monitor, all against one selected processor.

Open Lutron

Licensing

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

Generations

GEM ships four Lutron drivers across two entirely different integration protocols. Which utilities appear on the page depends on which processor is selected.

Hardware	Driver	Protocol	Project comes from
RadioRA 3, HomeWorks QSX	lutron_qsx	LEAP over TLS (8081, pairing on 8083)	The processor itself, after pairing
Caséta Smart Bridge PRO	lutron_caseta	LEAP over TLS	The bridge itself, after pairing
QS, RadioRA 2, HomeWorks QS (Quantum)	lutron_qs	Integration Access Port (telnet, 23)	A Designer XML export
HomeWorks (Illumination / legacy)	lutron_homeworks	Integration Access Port (telnet, 23)	A Designer XML export

The base Caséta Smart Bridge (non-PRO) exposes no integration API at all and cannot be used.

Choosing a processor

The header holds the processor picker, a generation badge, the live connection state, the address, and three actions:

Control	Description
Processor	Every Lutron device on the site, labelled with its generation.
Reload driver	Restarts this driver. Needed after changing connection settings, and after importing zones so they bind.
Refresh	Re-reads the processor's state and tells every tab to reload.
Add processor	Creates a new Lutron device in a modal without leaving the page.

Clicking the processor name opens its device record in the reference modal, so you can check its attributes without losing what is on screen.

With no Lutron device on the site yet, the page shows a card per generation with a matching Add button, so the driver is chosen from the hardware rather than from a driver list.

Overview tab

The processor's present state and the next thing to do about it:

• Connection, Generation, Address, Last sync and a Zones card broken down by control type, with a count of disabled zones (that is where auto-discovered zones land for review).
• The driver's last error, if it recorded one — a wrong integration password shows up here.
• The Pairing panel on LEAP processors (see below).
• Project import actions for LEAP processors: Sync zones and Mirror areas to site spaces, with an option to create a UI per space.
• A collapsible Setup guide read from the driver's own metadata — prerequisites, setup steps, known quirks and troubleshooting, accurate per generation.

Pairing (LEAP generations)

Pairing is the one Lutron step that cannot be done from a desk: the processor issues a certificate only while somebody is physically pressing its button. The pairing panel drives the whole sequence.

It first reports five checks:

Check	Meaning
Processor address	An ip attribute is set on the device.
Pairing port 8083	Something answers on the pairing port. If not, the address, the network path or the hardware model is wrong — not the pairing itself.
Session port 8081	Something answers on the LEAP port.
Certificate	A client certificate has been issued and stored on the device.
LEAP session	The driver currently holds a live session, with the number of zones bound to it.

Below the checks is a plain-language Next line, then Start pairing. Pressing it opens the pairing connection and switches the panel into a countdown telling you to press the button on the processor — the recessed front-panel button on RA3/QSX, the black button on the back of a Caséta Smart Bridge PRO. The panel polls until the certificate lands and then says so; if the window closes without one, it says that instead.

The certificate and key pair are stored encrypted on the device and survive restarts. Pairing again issues a fresh certificate and replaces the stored one.

Troubleshooting:

• Port 8083 does not answer — check the IP, the route between GEM and the processor, and that the hardware is an RA3/QSX processor or a Caséta Smart Bridge PRO.
• The countdown expires — the processor was not in pairing mode. It only grants physical access for about a minute after the button is pressed.
• 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 and pair again.

Once paired, GEM pulls the processor's zones automatically and refreshes them about once an hour.

Zones tab

Every zone bound to the selected processor, with its live level and a way to move it. Levels arrive over the same attribute subscription the control UIs use, so what is on screen is what the processor last reported — not what GEM last sent.

Control	Description
Filter	By name, label or address.
Type	Restrict to one control type.
Show disabled	Auto-discovered zones are created disabled; this is where you review them.
Query levels	Telnet generations only — asks the processor for the present level of every zone on screen, one at a time. LEAP processors push status instead, so there is nothing to poll.

Per row: the address, the control type, the live level or state, and test buttons appropriate to the control — On / 50% / 10% / Off / Identify for dimmers, Open / Close / Stop / 50% for shades, temperature and setpoint queries for thermostats on QS. Identify blinks the load twice and then restores the level it had, which is how you find out which fixture address 47 really is.

Enable / Disable flips the zone and reloads it so the change takes effect immediately.

Live updates are subscribed for the first 400 zones on a processor; the page says so when a project is larger than that.

Keypads tab

LEAP processors

The left pane lists every control station the processor reports, with its area and station id. Selecting one shows each gang: its model and serial, and every button with its number, engraving, live LED state and whether Lutron considers it programmed. Unprogrammed buttons (a raise/lower pair that was never assigned) are dimmed, because pressing them does nothing.

Press and Hold fire the button through the processor exactly as the physical button would. The LED row below each gang forces an LED on or off for wiring checks.

Copy id copies the control station id — the one value the Lutron Keypad widget needs, and previously not visible anywhere in the admin.

A Caséta Smart Bridge PRO does not publish a control-station tree, so this list can come back empty on an otherwise working bridge — its Pico remotes appear as devices instead.

Telnet processors

There is no keypad catalog on a telnet processor, so this tab reads the wire instead.

• Live keypress feed — every KBP/KBR (HomeWorks) or ~DEVICE (QS) frame the processor reports, decoded into address, button and action. It works for keypads GEM has never been told about, which is exactly the situation when you are trying to identify one. Clicking a row loads its address into the tester.
• Keypad tester — sends a press, release or hold at an address, as though somebody had pressed the physical button.

If nothing appears in the feed, monitoring may be switched off at the processor. The Monitor tab can switch it back on for QS.

Areas & Scenes tab (LEAP generations)

Load area tree walks the processor's project and renders it as a collapsible tree, with a count of control stations per area. Selecting an area shows:

• Scenes — every scene programmed for that area, each with an Activate button, plus the area id and scene id needed to call activate_scene from a macro. This is the only place in GEM those ids are visible.
• Keypads — the control stations in the area; open one on the Keypads tab for its buttons.
• Loads — the zones the area contains, read-only. Each row names the load as the project names it, then what it is in GEM: the zone it was imported as — click it to open that zone in place, without losing the tree, the selected area or the scene list — or not in GEM when no zone carries that load's address. A zone that exists but is disabled is marked, since the driver does not bind it.

Import this area's zones into GEM creates any zone in that area GEM does not already have and reads its present level — so a project can be commissioned one room at a time instead of all at once. Browsing never creates anything; only that button does.

Project Import tab (telnet generations)

Imports zones from a Lutron Designer XML export. Unlike the previous version of this page, nothing is written until you have looked at it.

Selecting a file parses it and shows what was found: the project name, the processor named in the export, and counts of loads, thermostats, keypads, rows that already exist on this device, and rows whose Lutron output type has no mapping.

The preview table lists every row with a checkbox, its Lutron address and output type, and editable GEM control and subsystem columns. Rows already on the device are marked and unchecked; thermostats and keypads are found but left unchecked, because they need a subsystem chosen first.

Control	Description
Filter / Everything	Narrow the table by text or by kind (loads, thermostats, keypads).
Select shown / Clear shown	Bulk-check what is currently filtered.
Set type for shown	Apply one GEM control to every filtered row — the usual case being a run of NON_DIM outputs that are switches, not dimmers.
Prefix names with area	Whether the generated zone name includes the area (kitchen_pendants versus pendants). On by default.
Create disabled	Import everything disabled for review before it goes live.

A zone cannot be created without both a control type and a subsystem — subsystem_id is part of a zone's primary key — so selected rows missing either are highlighted and counted, and the import button reports how many are still blocked.

Names are slugified from the label and made unique against both the rest of the import and the zones already on the device; a collision gets the Lutron address appended.

Re-running the same file is safe: anything already present is marked and unchecked.

Imported zones bind to the driver on its next reload — use Reload driver in the header, then check them on the Zones tab.

Output type mapping

Defaults applied to each Lutron output type. Any of these can be overridden per row in the preview.

Lutron output type	GEM control
AUTO_DETECT, INC, MLV, ELV, ELV_PLUS, FLUORESCENT_DB, ECO_SYSTEM_FLUORESCENT, ZERO_TO_TEN, DALI	light_dimmer
NON_DIM, NON_DIM_INC, NON_DIM_ELV, NON_DIM_FLUORESCENT, MOTOR, CCO_PULSED, CCO_MAINTAINED	light_switch
CEILING_FAN_TYPE, EXHAUST_FAN_TYPE	fan_default
SYSTEM_SHADE, MOTOR_JOG, SYSTEM_SHEER_BLIND, VENETIAN_BLIND	shade_dimmer
HVAC	climate_default

Shade groups (#SHADEGRP) are deliberately not imported: a normal zone drives #OUTPUT, which is not what a shade group answers to. Use the driver's shade_group_level command, or a per-zone action override, for those.

Monitor tab

A live view of the frames on the wire, in both directions, for every generation. The driver holds the only connection to the processor, so without this there is no way to watch Lutron traffic from a browser — and on the LEAP generations, no way to watch it at all.

Each Lutron driver keeps the last 400 frames it sent or received in memory. The monitor polls that buffer, and pauses itself while the browser tab is hidden.

Control	Description
Pause / Resume	Stop and restart polling.
Clear	Empty the driver's buffer and the view.
Filter	Substring match on the frame text.
Both directions	Show only what GEM sent, or only what the processor said.
Follow	Keep the newest frame in view.

The buffer is memory-only and is never persisted. Credentials never reach it: the telnet login exchange is written straight to the socket, bypassing the traced path, and the LEAP pairing exchange runs on a separate connection.

If the view says frames were dropped, the processor produced more than 400 frames between two polls — the beginning of that burst is gone.

Sending

• Telnet generations — a raw integration line, sent verbatim with the terminator added. The reply appears in the trace rather than as a return value, because telnet commands resolve as soon as they are written.
• LEAP generations — a LEAP ReadRequest against any URL, with a picker of the common endpoints and the JSON response rendered below. Read-only.

Processor monitoring (QS)

QS processors need #MONITORING switched on for each category of report. The chips at the bottom of the tab switch output, device, button, HVAC, shade group, occupancy, event and diagnostic monitoring on or off.

The processor does not report its monitoring state, so these are write-only — switch one on and watch the trace to confirm the frames start arriving. Monitoring resets when the processor reboots.

sync_areas command

Run from the Overview tab, the device's command page, or a macro, to mirror the LEAP 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. Only stations that actually contain a keypad-type device count — a "device location" whose only ganged device is a load module (say, a J-box relay driving a fountain) or a sensor is skipped, and reported in stations_skipped, so it can never claim a UI's keypad slot. 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). The end-user floor plan reads them too: on the Lighting, Shades and generic maps, a room whose UI carries stations shows a keypad glyph beside the room name that opens that room's keypad in a modal (see Site Spaces). Generated RTI remote programs read them too — a mirrored UI carrying a station gets the keypad's own engraved buttons on its lighting page instead of GEM's light scenes.
• 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: counts of spaces_created, spaces_updated, and spaces_existing; zones_created, zones_relinked, and zones_existing; uis_created and uis_updated; plus stations_skipped (device locations with no keypad-type device), orphaned_site_spaces, and any errors.

Diagnostic commands

These are available from the device's Commands tab as well as from this page, so they can also be used from macros and scripts.

Command	Generations	Description
get_traffic	all	Returns the recorded frames. since=<seq> returns only frames newer than a sequence number; limit caps the count.
clear_traffic	all	Empties the trace buffer.
pair_status	LEAP	Certificate/key-pair presence, LEAP session state, port reachability and a suggested next step. Never returns the key material itself.
passthrough	telnet	Sends a raw integration line. Elevated callers only.

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
• Lutron QSX / RA3 driver
• Lutron Caséta driver
• Lutron QS driver
• Lutron HomeWorks driver