Lutron Caséta (Smart Bridge Pro)

Lutron Caséta is controlled over the LAN through the Smart Bridge Pro, using Lutron's LEAP protocol over a secure (TLS) connection. One bridge becomes one GEM device, and that single device controls every Caséta dimmer, switch, plug-in module, shade, and fan-speed control on the account, plus Pico remotes and Caséta keypads. Lights, shades, and fans become GEM zones; keypad and Pico buttons can be pressed and held, and live state is reflected back into GEM.

Control requires a one-time, on-site pairing in which GEM and the bridge exchange a certificate. Pairing must be authorized by physically pressing the bridge's pairing button — it cannot be triggered from the Lutron app.

caution

You must have the Smart Bridge PRO

This driver only works with the Smart Bridge Pro (model L-BDGPRO2 / L-BDGPRO2-WH). The standard Smart Bridge (L-BDG2) does not expose the LEAP API and cannot be integrated — it has no local control interface. Confirm the model before you start; "Pro" is printed on the unit.

Other Lutron systems use sibling drivers

Lutron's professional processors — RadioRA 3, HomeWorks QSX, and standalone QSX — speak the same LEAP protocol and are handled by the lutron_qsx driver, documented on the Lutron RA3 / QSX (LEAP) page. The older telnet-based HomeWorks and QS processors use the lutron_homeworks / lutron_qs drivers and are configured from the Lutron integration page. This page is only for the Caséta Smart Bridge Pro.

What's controlled

• Lights — on / off and set level (dimming) with a fade time, on Caséta dimmers, switches, and plug-in lamp/dimmer modules.
• Shades — open / close / stop (raise / lower / stop) and set position on Serena and other Caséta-compatible shades.
• Fans — set speed by percentage or by named speed (off / low / medium / high) on the Caséta fan speed control.
• Keypads and Pico remotes — press and press-and-hold any keypad/Pico button, set keypad LED state where the device has LEDs, and reflect live button activity back into GEM.
• Scenes — activate a Lutron scene in any area.
• Project structure — pull the bridge's areas, zones, and devices into GEM as zones.

Prerequisites

• A Caséta Smart Bridge Pro 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 Caséta system already set up and working in the Lutron mobile app — devices paired to the bridge and assigned to rooms. GEM imports what the bridge already knows about; it does not replace Caséta's own device setup.
• Network reachability between GEM and the bridge on two TCP ports:
  • 8081 — ongoing LEAP control (kept open the whole time the device is enabled).
  • 8083 — used once during pairing to exchange the client certificate.
• Physical access to the bridge to press its pairing button.
• The Lutron product on your GEM license. Adding any Lutron device requires it; existing devices keep running if a license later changes. See License.

Both ports must be open

If GEM can reach 8081 but not 8083, the device may appear online yet the pair command will fail. Open both ports between GEM and the bridge before you start.

Setup — add, pair, and sync

1. Add the device

1. Open Devices, add a device, and choose the Lutron Caseta (Smart Bridge Pro) driver.
2. Give it a name and set the Bridge IP (ip) to the bridge's LAN address.
3. Save, enable the device, then reload it so the driver comes online. The device must be running before the pair command will work.

The bridge also advertises itself on the network (mDNS), but you still enter the IP manually for pairing — don't rely on auto-discovery to fill it in.

2. Pair with the bridge

1. At the bridge, press the small black pairing button on the back of the unit to put it into pairing mode. LEAP requires proof of physical access, so this step cannot be done from the Lutron mobile app.
2. While the bridge is still in pairing mode, open the device's Commands tab and run pair. GEM connects on port 8083, exchanges certificates, and stores them encrypted on the device.
3. Once paired, GEM connects over LEAP (port 8081) on its own and reconnects automatically after a reboot or network blip. You only pair again if you replace the bridge or delete the stored credentials.

Pairing fails repeatedly?

The most common cause is the standard Smart Bridge instead of the Pro — only the Pro exposes LEAP. If it is a Pro, press the back pairing button again immediately before running pair, and confirm TCP 8083 is open between GEM and the bridge.

Re-pairing

If you ever swap bridges or move the device to a different unit, clear the stored LEAP Key Pair and LEAP Certificates attributes on the device, then run pair again. Certificates are tied to the specific bridge that issued them.

3. Pull in the zones

After pairing, run sync_zones from the Commands tab. It walks the bridge's areas, zones, and devices and creates a GEM zone for every controllable output (lights, shades, fans), naming each zone after its Lutron room and label. This is the minimum to start controlling things.

GEM also resyncs on its own: when the driver connects it pulls zones if it hasn't synced in the last hour, then keeps resyncing about hourly, and keeps the connection alive with a periodic ping.

Mirroring rooms into site spaces

A second command, sync_areas, is shared from the RA3/QSX engine. In addition to creating zones it mirrors the Lutron area tree into GEM site spaces — creating/linking a space per area and stamping each zone with its space — and, with create_uis=true, generates a UI for any space that doesn't yet have one. It never renames or deletes spaces you already have. The recommended import for Caséta is sync_zones; use sync_areas only if you want GEM's room structure to follow the bridge's areas.

Zones

Each Caséta output becomes a GEM zone. The zone's Address is the numeric Lutron zone id, which sync_zones fills in for you. GEM picks the subsystem and zone control type from the Lutron output type:

Lutron output type	GEM subsystem	Zone control	How you control it
Dimmed	Lights	light_dimmer	on / off / set level with fade
Switched	Lights	light_switch	on / off
Shade	Shades	shade_dimmer	open / close / stop / set position
Fan Speed	Fans	fan_default	set speed (percent or named)

What the standard zone verbs do on a Caséta zone:

• on / off — full on (100%) or off. On a dimmer this is a dim-to-100 / dim-to-0; on a switched load it's a relay on / off.
• level — set brightness 0–100 with a fade time in seconds. If you don't pass a fade, GEM uses the Lights subsystem's default fade rate (or 4 seconds if none is set).
• open / close / stop — raise / lower / stop a shade.

Fan speed

A fan zone accepts either a percentage level (0 = off, 1–33 = low, 34–66 = medium, 67–100 = high) or a named speed — off, low, medium, high. The zone's state reflects the current named speed.

Caséta fixtures are on/off/dim/shade/fan

The Caséta product line does not include color- or white-tunable fixtures, so the color-tuning command (spectrum_level) inherited from the shared LEAP engine has nothing to drive on a Caséta bridge. If you need tunable-white or full-color control, that is an RA3 / HomeWorks QSX feature — see Lutron RA3 / QSX (LEAP).

Keypads, Pico remotes, and buttons

GEM can drive Caséta keypads and Pico remotes:

• press_button / hold_button (argument id, the Lutron button id) — emulate a tap or a press-and-hold on a keypad or Pico button, exactly as if someone pushed it.
• set_led (arguments led, state) — turn a keypad LED on or off (state = on / off), for keypads that have addressable LEDs.
• Live button activity is pushed back to GEM while the device is connected.

To find the button and LED ids, run get_control_stations for a flat list of every keypad on the bridge, or get_control_station (argument control_station_id) for one keypad's full detail — model, serial, its LEDs, and its buttons grouped the way they're laid out on the device.

On-screen keypad widget

The Lutron Keypad widget renders a physical keypad on a GEM UI page — the buttons mirror the real layout, honor press / hold, and light up to match live LED state on keypads that report it. When adding it, pick the Lutron Device (the bridge), then pick the Keypad (the picker is fed by get_control_stations).

Scenes

Run activate_scene with area_id (the Lutron area) and scene_id to recall a Lutron scene. Use the inspection commands below (get_root_area, get_child_areas, get_associated_zones) to discover area ids and the scenes available in each.

Device attributes

Most of these are written by the driver — you normally only set Bridge IP.

Attribute	Set by	Purpose
ip (Bridge IP)	You	LAN IP of the Smart Bridge Pro.
keypair (LEAP Key Pair)	pair	Generated key pair, stored encrypted. Do not edit.
certificates (LEAP Certificates)	pair	Client/CA certificates issued during pairing, stored encrypted.
subscriptions	Driver	Internal map of live LEAP subscription URLs.
button_subscriptions	Driver	Keypad/Pico device ids GEM is subscribed to for live button events.
last_sync	Driver	Timestamp of the last zone sync, used to decide when to resync.

Two optional advanced overrides are read if present on the device: ping_interval (keep-alive interval, default 30 seconds) and sync_interval (auto-resync interval, default 1 hour). Leave them unset unless you have a specific reason to change the cadence.

Zone attributes

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

Attribute	Meaning
level	Current brightness / shade position (0–100).
state	Current named state (e.g. fan speed off / low / medium / high).

Command reference

The Caséta driver shares its command set with the RA3 / QSX driver. The commands you'll use on a Caséta bridge are:

Command	Arguments	Action
pair	—	Exchange certificates with the bridge (bridge must be in pairing mode).
sync_zones	—	Create GEM zones for all lights/shades/fans on the bridge.
sync_areas	create_uis	Sync zones and mirror the Lutron area tree into site spaces (and UIs if create_uis=true).
on / off	address	Turn a zone fully on / off.
level	address, level, fade_rate	Set a dimmer level (0–100) over a fade time in seconds.
set_fan	address, level	Set a fan speed by percent or name.
open / close / stop	address	Raise / lower / stop a shade.
press_button / hold_button	id	Tap or press-and-hold a keypad/Pico button.
set_led	led, state	Turn a keypad LED on / off.
activate_scene	area_id, scene_id	Recall a Lutron scene in an area.
get_root_area	—	Read the top of the Lutron area tree.
get_child_areas	area_id, include_components	List child areas, control stations, and devices. Pass include_components=true to also enumerate buttons + LEDs (slower).
get_associated_zones	area_id	List child areas with their zone details.
get_control_stations	—	Flat list of all keypads on the bridge.
get_control_station	control_station_id	Full detail (model, serial, LEDs, buttons) for one keypad.
spectrum_level	address, level, vibrancy, hue, saturation, fade_rate	Set color/level on a spectrum-tunable fixture (no Caséta hardware uses this — see note above).
subscribe	url	Subscribe to a LEAP status URL for live events.
read_request	url	Read any LEAP resource by URL (diagnostic).

Troubleshooting

Symptom	Check
pair command fails	Confirm it is a Smart Bridge Pro, not the standard Smart Bridge — only the Pro exposes LEAP. Press the back pairing button again, then run pair. Confirm TCP 8083 is open between GEM and the bridge.
Pairs but no events / nothing controls	The stored certificates may belong to a different bridge. Clear the LEAP Key Pair and LEAP Certificates attributes and re-pair. Confirm TCP 8081 is open.
No zones appear after pairing	Run sync_zones from the Commands tab. Make sure the Caséta devices are set up and assigned to rooms in the Lutron app first.
A zone won't dim / only switches	The Lutron output is a Switched (relay) load, not a dimmer — it imports as a switched zone and only supports on / off.
Color commands do nothing	Caséta hardware is not color-tunable; spectrum_level has no effect on a Caséta bridge.
Device drops offline periodically	Confirm the bridge has a static IP/reservation and that nothing is closing the LAN path on port 8081.

See also

• Lutron RA3 / QSX (LEAP) — the sibling driver for RadioRA 3 and HomeWorks QSX processors, with the full LEAP keypad/color-tuning reference.
• Lutron — the Integrations page: the broader LEAP pairing/sync overview and XML import for the older HomeWorks/QS processors.
• Zones — how zones, addresses, and control types work.
• Site Spaces — how sync_areas mirrors the Lutron area tree.
• Widgets — adding the Lutron Keypad widget to a UI page.
• Commands — running and scripting device commands.
• Devices — adding and configuring devices.
• License — enabling the Lutron product.