pycasperglow

Async Python library for controlling Casper Glow lights via BLE.

Built on bleak and designed for use as a backend for Home Assistant integrations.

Installation

pip install pycasperglow

Usage

Discover devices

import asyncio
from pycasperglow import discover_glows

async def main():
    async for device in discover_glows(timeout=10.0):
        print(f"{device.name} ({device.address})")

asyncio.run(main())

Control a light

import asyncio
from pycasperglow import CasperGlow, discover_glows

async def main():
    glow = None
    async for device in discover_glows():
        glow = CasperGlow(device)
        break
    if glow is None:
        print("No Casper Glow found")
        return
    await glow.turn_on()
    await asyncio.sleep(5)
    await glow.turn_off()

asyncio.run(main())

Home Assistant integration

When used within Home Assistant's Bluetooth stack, pass the managed BleakClient to avoid connection conflicts:

glow = CasperGlow(ble_device, client=bleak_client)
await glow.turn_on()

When an external client is provided, pycasperglow will not disconnect it — the caller retains ownership.

API

CasperGlow(ble_device, client=None)

Async client for a single Casper Glow light.

GlowState

Dataclass returned by query_state() and passed to registered callbacks.

BatteryLevel

IntEnum with four members: PCT_25, PCT_50, PCT_75, PCT_100. Each has a .percentage property returning 25, 50, 75, or 100.

discover_glows(timeout=10.0)

Scan for Casper Glow devices. Async generator that yields BLEDevice objects as they are found. For standalone use — Home Assistant uses its own discovery.

is_casper_glow(device, adv)

Returns True if a BLEDevice and AdvertisementData match a Casper Glow (by service UUID or name prefix).

Exceptions

Examples

See the examples/ directory for runnable scripts. To discover nearby Casper Glow lights and turn them on:

python examples/discover_and_turn_on.py

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run checks:

pytest tests/ -v --cov=pycasperglow
mypy src/ tests/ examples/ --strict
ruff check src/ tests/ examples/

Protocol

The BLE protocol was partially reverse-engineered from dengjeffrey/casper-glow-pro. The connection flow is:

1. Connect and subscribe to notifications on the read characteristic
2. Write the reconnect packet
3. Wait for a notification containing the ready marker
4. Extract the session token from the notification
5. Build and write the action packet (header + token + action body)
6. Disconnect

License

MIT