Lutron HomeWorks (Illumination)

Older Lutron HomeWorks Interactive / Illumination processors are controlled over the LAN through Lutron's classic telnet Integration Access Port. One processor becomes one GEM device, and that single device drives every dimmer, switch, and shade on the project and reads keypad button activity back live. Dimmer, switch, and shade outputs become GEM zones, keyed by their dotted Lutron address (for example 01:04:01:01).

Unlike the newer LEAP processors, there is no certificate pairing here — GEM opens a telnet session to the processor, logs in with an integration user, and turns on dimmer-level monitoring (DLMON) and keypad monitoring (KBMON) so physical changes flow back into GEM. You bring zones in either by uploading the processor's XML export or by adding them by hand with their dotted address.

Which Lutron driver do I need?

This page covers the lutron_homeworks telnet driver for the legacy HomeWorks Interactive / Illumination processors. It is not the same as HomeWorks QSX — despite the shared "HomeWorks" name, QSX is a current processor that speaks the secure LEAP protocol and pairs with a certificate. Use the Lutron RA3 / HomeWorks QSX driver for QSX, the Lutron Caséta driver for the Caséta Smart Bridge Pro, and the Lutron QS driver for QS-series / HomeWorks QS / RadioRA 2 repeaters. The deciding factor is the connection: this driver talks telnet on port 23; the LEAP drivers talk TLS on 8081/8083.

What's controlled

• Lights — on / off and set level (dimming) with a fade time on dimmer outputs; on / off on non-dim (switched) outputs.
• Shades — raise (open) / lower (close) and stop a moving shade.
• Keypads — emulate a button press / release on any keypad, and read live keypad button activity back into GEM as a zone attribute you can trigger automations on.

No color tuning on HomeWorks Illumination

The telnet integration protocol carries dim levels only — it has no color or color-temperature control. Color- and white-tunable fixtures dim normally, but hue / saturation / color-temperature tuning is only available on the LEAP processors via the Lutron RA3 / HomeWorks QSX driver.

Prerequisites

• A HomeWorks Interactive / Illumination processor on the same LAN as GEM, with a known IP address. Give it a static IP or a DHCP reservation so its address never moves.
• The telnet Integration Access Port enabled on the processor, and an integration login user (with a login/password) created in the Lutron programming software. This is a separate account from the programming/design PC login, and it must have monitoring privileges so level and keypad events report back.
• Network reachability between GEM and the processor on TCP port 23 (telnet).
• The Lutron product on your GEM license. Adding any Lutron device requires it; existing devices keep running if a license later changes. See License.
• The processor's XML configuration export (from the Lutron programming software) if you want to bulk-import zones rather than add them one at a time.

Setup — add the device, then bring in zones

1. Add the device

1. Open System → Devices, add a device, and choose the Lutron HomeWorks driver (lutron_homeworks).
2. Give it a name and set the Processor IP (ip) to the processor's LAN address.
3. Fill in the integration credentials under the optional attributes:
   • Login (login) — the integration user name. You can use Username (username) instead; they're interchangeable.
   • Password (password) — the integration password. Stored encrypted. Leave blank if the integration user has no password.
   • Telnet Port (port) — defaults to 23; only change it if your processor uses a non-standard port.
   • Default Fade Rate (seconds) (fade_rate) — fade time used for level changes when a command doesn't specify one. Defaults to 3 seconds.
4. Save, enable the device, then reload it so the driver opens the telnet session, logs in, and turns on monitoring. Watch the device's connection state turn online.

On connect the driver sends PROMPTOFF (suppresses the processor's command prompt), then DLMON and KBMON to start dimmer-level and keypad monitoring — this is what makes physical changes report back. If the integration user lacks monitoring privileges, the device still connects but no level or keypad events arrive.

2. Bring in the zones

Each controllable output (dimmer, switch, shade) becomes a GEM zone whose Address is the output's dotted Lutron address — for example 01:04:01:01. Enter it without the surrounding brackets; the processor reports addresses bracketed ([01:04:01:01]) and GEM strips the brackets when matching. You have two ways to create zones.

Option A — XML import (bulk). Export the project's XML from the Lutron programming software, then:

1. Open the Lutron page (admin Integrations → Lutron) and select this processor in the header picker.
2. Go to the Project Import tab and choose the .xml export.
3. Review the preview table — every load, thermostat and keypad found in the file, with its Lutron address and output type, and editable GEM control and Subsystem columns. Rows whose address already exists on this device are marked and unchecked, so re-running the same file after adding outputs in Lutron is safe.
4. Uncheck what you don't want, correct any control type or subsystem, then Import.

Nothing is written until you press Import. The preview also lets you bulk-apply one control type to everything currently filtered, prefix zone names with the area, and create the zones disabled for review. Thermostats and keypads are found but left unchecked, because they need a subsystem chosen first. Zone names come from the Lutron area plus the output name (for example kitchen_island) and are made unique against the zones already on the device.

Default control type per Lutron output type — override any of them per row in the preview:

Lutron output type	Zone 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

An output type outside this list is listed with no control type and cannot be imported until you pick one.

Imported zones bind to the driver on its next reload — use Reload driver in the page header afterwards.

Verify the imported address matches what the processor reports

The importer uses each output's IntegrationID from your XML export as the zone Address. This driver controls and reads outputs by the dotted address the processor uses on the telnet wire (for example 01:04:01:01), so the two must match. After importing, test one zone — change a light at a keypad and confirm the zone's level updates in GEM. If it doesn't, the zone's Address doesn't match what the processor reports; edit the zone's Address to the dotted HomeWorks address shown in your Lutron programming.

Option B — add zones by hand. On Zones, add a zone, set its Device to the HomeWorks processor, set the Address to the output's dotted Lutron address (no brackets, e.g. 01:04:01:01), and pick the control type (light_dimmer, light_switch, or shade_dimmer). This is the most reliable path on a legacy Illumination project, because you enter exactly the address the processor reports.

Unknown addresses are ignored, not auto-created

If the processor reports activity for an address that has no GEM zone, the driver logs it and moves on — it does not create a placeholder zone. Every output you want to control or monitor must be created first (import or by hand). The dotted address in the processor's log line (brackets stripped) is the value to enter as the zone Address.

Zones

Each Lutron output is one GEM zone; its Address is the dotted Lutron address. What the standard zone verbs do:

• on / off — full on (100%) or off, sent instantly (no fade). On a dimmer this is dim-to-100 / dim-to-0; on a switched load it's a relay on / off.
• level — set a dimmer 0–100 with a fade time in seconds. If you don't pass a fade, GEM uses the device's Default Fade Rate (3 seconds unless you changed it).
• open / close — for a shade zone, raise to 100% / lower to 0%.
• stop — halt a shade that is moving (HomeWorks supports a true stop, unlike the QS driver).

Live feedback and monitoring

GEM reflects physical changes by watching the events the processor pushes on the telnet session once monitoring is on:

• A dimmer level report (DL) updates the zone's level attribute (0–100). On a switched (light_switch) zone it also sets state to on / off.
• A keypad press / release (KBP / KBR) updates the keypad zone's keypress attribute (see below).

Whenever the driver connects — and at most once an hour — it also re-queries every zone's current level so GEM resynchronizes after a reboot or network blip. Commands are throttled (about two per second) to avoid flooding the processor, so a large initial sync can take a minute.

Keypads and buttons

To capture keypad activity, add a zone whose Address is the keypad's dotted Lutron address (for example 01:06:05) and bind it to the HomeWorks device. When the processor reports a button event, the driver writes a keypress attribute on that zone holding the action, the button number, and a timestamp — for example { "action": "press", "button": "2", "timestamp": 1718600000000 }. Because the timestamp changes on every event, the attribute updates on each press, and an attribute trigger on keypress fires every time that keypad is used; inside the macro, read the keypress value to see which button and whether it was a press or release.

To drive a keypad button from a macro (emulate someone pushing it):

• keypad_press / keypad_release — arguments address (the keypad's dotted address) and button_number. These send Lutron's legacy KBP / KBR commands and are the simplest way to tap a keypad button on a HomeWorks Illumination processor. When run against a keypad zone, the address is filled in from the zone automatically.
• device — sends a raw #DEVICE integration command (arguments component_number, action_number, parameters) for processors/firmware that expect the integration-protocol syntax. Lutron's standard component actions are 3 (press), 4 (release), 5 (hold), 6 (double-tap), and 32 (hold-release).

Device attributes

You normally only set the connection fields; the rest are written by the driver.

Attribute	Set by	Purpose
ip (Processor IP)	You	LAN IP of the processor.
port (Telnet Port)	You (optional)	Telnet port, default 23.
login (Login) / username (Username)	You	Integration user name. Either attribute works.
password (Password)	You	Integration password, stored encrypted.
fade_rate (Default Fade Rate (seconds))	You (optional)	Fade used for level when no fade is passed. Default 3.
last_sync	Driver	Timestamp of the last full level re-query, used to decide when to resync.

Two optional advanced overrides are read if present on the device: ping_interval (telnet keep-alive interval, default 30 seconds — the driver sends a periodic RST keepalive and reconnects if the link goes quiet) and command_throttle (minimum spacing between outbound commands, default 500 ms to protect the processor). Leave them unset unless you have a specific reason to change the cadence.

Zone attributes

On lighting and shade zones the driver maintains live state you can read or trigger on:

Attribute	Meaning
level	Current dimmer level / shade position (0–100), updated from the processor's dimmer-level (DL) reports.
state	on / off, maintained on switched (light_switch) zones.
keypress	On a keypad zone, a JSON object { action, button, timestamp } for the most recent button event (action = press / release).

Command reference

The integrator interacts with these from the device's Commands tab or from macros. For zone verbs the address is filled in automatically from the zone you run the command against.

Command	Arguments	Action
on / off	address	Set the output fully on (100%) / off, instantly — #OUTPUT,<addr>,1,100,0 / #OUTPUT,<addr>,1,0,0.
level	address, level, fade_rate	Set a dimmer 0–100 over a fade time in seconds (defaults to the device fade rate) — #OUTPUT,<addr>,1,<level>,<fade>.
open / close	address	Raise (100%) / lower (0%) a shade — FADEDIM,100,0,0,<addr> / FADEDIM,0,0,0,<addr>.
stop	address	Halt a moving shade — STOPDIM,<addr>.
keypad_press / keypad_release	address, button_number	Emulate a keypad button press / release — KBP,<addr>,<button> / KBR,<addr>,<button>.
device	address, component_number, action_number, parameters	Send a raw #DEVICE integration action to a keypad/device component.
query_level	address	Ask the processor for an output's current level — ?OUTPUT,<addr>,1.
query_output	address, action_number	Query an output's status for a given action number — ?OUTPUT,<addr>,<action>.
passthrough	command	Send a raw HomeWorks integration line verbatim (the terminator is added). Elevated callers only.
get_traffic	since, limit	The last 400 frames the driver sent and received. since=<seq> returns only newer frames, for incremental polling.
clear_traffic	—	Empty the protocol trace buffer.

The protocol trace is memory-only and is never persisted. The login exchange is written straight to the socket and bypasses the traced path, so the integration password never enters the buffer. The Lutron page renders it as a live monitor, and derives its keypress feed from the KBP/KBR frames in it.

Troubleshooting

Symptom	Check
Device won't connect	Confirm the telnet Integration Access Port is enabled, TCP 23 is reachable, and the IP is correct. The driver auto-reconnects, so a flapping device usually means a wrong IP/port or a closed LAN path.
Connects but nothing reports back	The integration user needs monitoring privileges — DLMON / KBMON are sent on login but only work if the account is allowed to monitor. Re-check the user in the Lutron programming, then reload the device.
Changes at a keypad or load don't show in GEM	The zone's Address doesn't match the dotted address the processor reports. Compare it to the processor's log/programming and correct the zone Address (no brackets).
A light won't dim / only switches	The output is a non-dim (switched) load — it should be a light_switch zone and only supports on / off.
level always fades in 3 seconds	No fade was passed and the device's Default Fade Rate is 3. Pass a fade_rate argument, or change the device's Default Fade Rate.
Imported zones don't control anything	The XML export's IntegrationID isn't the dotted address this driver uses. Edit the affected zones' Address to the dotted HomeWorks address (see the import warning above).
Initial sync is slow	Expected — commands are throttled to protect the processor; a large project can take up to a minute to re-query all levels.

See also

• Lutron — the Integrations page: XML import, the zone commissioning bench, the live keypress feed and the protocol monitor.
• Lutron QS — the telnet driver for QS-series / HomeWorks QS / RadioRA 2 repeaters.
• Lutron RA3 / HomeWorks QSX — the LEAP driver for current processors (including HomeWorks QSX).
• Lutron Caséta — the LEAP driver for the Caséta Smart Bridge Pro.
• Zones — how zones, addresses, and control types work.
• Subsystems — the Lights / Shades groupings outputs land in.
• Triggers — firing macros from keypad button activity.
• Commands — running and scripting device commands.
• Devices — adding and configuring devices.
• License — enabling the Lutron product.