pylutron-caseta

A Python API to control Lutron Caséta devices.

Getting started

If you don't know the IP address of the bridge, the leap-scan tool (requires the cli extra, pip install pylutron_caseta[cli]) will search for LEAP devices on the local network and display their address and LEAP port number.

Authentication

In order to communicate with the bridge device, you must complete the pairing process. This generates certificate files for authentication. pylutron_caseta can do this two ways.

lap-pair

If pylutron_caseta is installed with the cli extra (pip install pylutron_caseta[cli]), the lap-pair tool can be used to generate the certificate files. Simply running lap-pair <BRIDGE HOST> (note the LEAP port number should not be included) will begin the pairing process. The certificate files will be saved in $XDG_CONFIG_HOME/pylutron_caseta (normally ~/.config/pylutron_caseta) in the files [BRIDGE HOST]-bridge.crt, [BRIDGE HOST].crt, [BRIDGE HOST].key. Check lap-pair --help if you want to use different files.

The pairing module

If pylutron_caseta is being integrated into a larger application, the pairing functionality can be reused to allow pairing from within that application.

async def pair(host: str):
    def _ready():
        print("Press the small black button on the back of the bridge.")

    data = await async_pair(host, _ready)
    with open("caseta-bridge.crt", "w") as cacert:
        cacert.write(data["ca"])
    with open("caseta.crt", "w") as cert:
        cert.write(data["cert"])
    with open("caseta.key", "w") as key:
        key.write(data["key"])
    print(f"Successfully paired with {data['version']}")

Connecting to the bridge

Once you have the certificate files, you can connect to the bridge and start controlling devices.

import asyncio

from pylutron_caseta.smartbridge import Smartbridge

async def example():
    # `Smartbridge` provides an API for interacting with the Caséta bridge.
    bridge = Smartbridge.create_tls(
        "YOUR_BRIDGE_IP", "caseta.key", "caseta.crt", "caseta-bridge.crt"
    )
    await bridge.connect()

    # Get the first light.
    # The device is represented by a dict.
    device = bridge.get_devices_by_domain("light")[0]
    # Turn on the light.
    # Methods that act on devices expect to be given the device id.
    await bridge.turn_on(device["device_id"])

    await bridge.close()


# Run the example function within an asyncio loop.
asyncio.run(example())

Open/close/stop covers

HomeWorks QSX and RadioRA 3 projects expose logical zones through the LEAP /area/{area_id}/associatedzone resource. pylutron-caseta represents each zone as a device and uses its ControlType for domain classification. A zone whose control type is exactly OpenCloseStop is returned by get_devices_by_domain("cover"), regardless of its zone ID, area name, load name, or physical motor controller.

This supports any HomeWorks QSX or RadioRA 3 project that reports the same LEAP control type; it is not specific to a particular processor serial number or motor module. It does not imply support for older HomeWorks protocols or for a different, previously unknown ControlType. OpenCloseStop also does not identify whether the physical load is a shade, blind, curtain, or another kind of open/close motor.

These zones accept raise_cover, lower_cover, and stop_cover, which send the LEAP Raise, Lower, and Stop commands. When the processor does not report a level, current_state remains -1; Raise and Lower do not optimistically change it to 100 or 0.

An OpenCloseStop zone notification may contain only the zone identity, with no level, direction, command, motion state, or command source. Such a notification invokes the existing device subscriber but cannot by itself distinguish Raise from Lower. Callers also must not rely on Stop producing a zone notification. Applications that estimate position should correlate their own commands or separately observed controls and otherwise treat the position as unknown.

These limitations describe the QSX OpenCloseStop notifications observed so far; they are not a guarantee that every device, project, or future Lutron release will omit the same attributes. The existing zone-status handler already consumes Level when one is present. If another implementation later reports direction, command, motion, or source attributes, support can be extended from captured protocol evidence without changing the general OpenCloseStop discovery classification.

The leap tool

For development and testing of new features, there is a leap command in the cli extras (pip install pylutron_caseta[cli]) which can be used for communicating directly with the bridge, similar to using curl.

Getting information about the bridge:

$ leap 192.168.86.49/server | jq
{
  "Servers": [
    {
      "href": "/server/1",
      "Type": "LEAP",
      "NetworkInterfaces": [
        {
          "href": "/networkinterface/1"
        }
      ],
      "EnableState": "Enabled",
      "LEAPProperties": {
        "PairingList": {
          "href": "/server/leap/pairinglist"
        }
      },
      "Endpoints": [
        {
          "Protocol": "TCP",
          "Port": 8081,
          "AssociatedNetworkInterfaces": null
        }
      ]
    }
  ]
}

Turning on the first dimmer:

$ ip=192.168.86.49
$ device=$(leap "${ip}/zone/status/expanded?where=Zone.ControlType:\"Dimmed\"" | jq -r '.ZoneExpandedStatuses[0].Zone.href')
$ leap -X CreateRequest "${ip}${device}/commandprocessor" -d '{"Command":{"CommandType":"GoToLevel","Parameter":[{"Type":"Level","Value":100}]}}'

Metadata

Release files for pylutron-caseta 0.30.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pylutron-caseta 0.30.1
File	Size	Uploaded	Provenance
pylutron_caseta-0.30.1.tar.gz	63.6 kB	Oct 24, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pylutron-caseta 0.30.1
File	Interpreter	ABI	Platform	Reset
pylutron_caseta-0.30.1-py3-none-any.whl 37.4 kB Oct 24, 2026 Without provenance	Python 3	none	any	Details

Total release size: 101.0 kB

Release files / pylutron_caseta-0.30.1.tar.gz

Download URL	pylutron_caseta-0.30.1.tar.gz
Size	63.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`5193a70d09f7b4573c517567ee97558a8b751455ea7d4dae30d4063706390422`
BLAKE2b-256 checksum How to use checksums	`293482b4072eb43142cba3001f3584cfae6e9017fc071585bf769b6dae3beb66`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`Hatch/1.16.5 cpython/3.14.8 HTTPX/0.28.1`

Release files / pylutron_caseta-0.30.1-py3-none-any.whl

Download URL	pylutron_caseta-0.30.1-py3-none-any.whl
Size	37.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f2dd8a73a5230c0f6a7dfb0f51d8a7331bd7c318c32ba5bdc951954be07f2b91`
BLAKE2b-256 checksum How to use checksums	`3a4096d987ea036e4c1456a6c233d9b344b2371593eac6fe5ceb4f3c6fc4adec`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`Hatch/1.16.5 cpython/3.14.8 HTTPX/0.28.1`

Security for pylutron-caseta 0.30.1

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.