Casambi Classic BLE Library

An asynchronous Python library for controlling Casambi lighting devices running Classic firmware via Bluetooth Low Energy (BLE).

Classic vs. Evolution Firmware

Casambi networks operate under one of two major radio profiles: Evolution or Classic.

How to check your network profile

Open the official Casambi App → Select your network → More (...) → Network setup → Network configuration → Look at Radio profile:

• Classic: Use casambi-classic-ble (this library).
• Evolution: Use upstream casambi-bt.

Why this specialized fork exists

Classic networks rely on different GATT services (0xFE3D, 0xFE4D), different challenge-handshakes, and passive manufacturer advertisement beacons (0x03C3 / 963). This library provides native, standalone support for Classic devices without cloud lock-in.

Which API Should I Use?

casambi-classic-ble provides two client interfaces depending on your integration needs:

Features

• 🎯 Classic-First Architecture: Tailored specifically for Casambi Classic firmware devices.
• 🔍 BLE Discovery & Scanner: Discover Classic Casambi nodes and decode passive manufacturer advertisement data.
• 📡 Passive State Tracking: Read on/off and dimming levels directly from BLE advertisements with duplicate frame suppression.
• 🔌 Direct BLE Control: Connect directly over Bluetooth Low Energy without mandatory cloud intermediaries.
• 💡 Lighting Controls: Turn lights on/off, set brightness dim levels, color temperature (Kelvin), and RGB colors.
• 🛡️ Robust Concurrency: Serialized GATT writes via asyncio.Lock and domain exception raising.
• ☁️ Cloud Sync (Optional): Optional Casambi Cloud API and WebSocket bridge for topology sync.

Installation

pip install casambi-classic-ble

Or from source:

git clone https://github.com/hellqvio86/casambi-classic-ble.git
cd casambi-classic-ble
pip install -e .

Quick Start

1. Controlling a Device by Address

import asyncio
from casambi_classic_ble import CasambiConnectionError, CasambiDevice

async def main():
    # Target your node by Bluetooth address (or pass a Bleak BLEDevice from Home Assistant)
    light = CasambiDevice(address="AA:BB:CC:DD:EE:FF")
    try:
        await light.connect()
    except CasambiConnectionError as err:
        print(f"Could not connect to {light.address}: {err}")
        return

    try:
        # Optional: Authenticate if your network requires a password
        # (Only needed if the network is password-protected and unauthenticated writes are rejected)
        # await light.authenticate(password="your_network_password")

        # Control a specific unit (e.g. Unit 1)
        await light.turn_on(unit_id=1)
        await light.set_level(unit_id=1, level=0.75)
        await light.set_color_temperature(unit_id=1, temp_kelvin=3000)
        await light.set_rgb(unit_id=1, r=255, g=200, b=100)

        # Or control all units across the mesh (omit unit_id or use broadcast)
        # await light.turn_on()
        # await light.turn_off()
    finally:
        await light.disconnect()

asyncio.run(main())

2. Discovery & Bring-Your-Own-Scanner (Home Assistant)

import asyncio
from casambi_classic_ble import CasambiConnectionError, CasambiDevice, CasambiScanner

async def main():
    scanner = CasambiScanner()
    devices = await scanner.scan(duration=5.0)

    # Filter for your specific device by Bluetooth address rather than connecting blindly
    target = next((d for d in devices if d.address.upper() == "AA:BB:CC:DD:EE:FF"), None)
    if target:
        try:
            await target.connect()
            await target.turn_on(unit_id=1)
        except CasambiConnectionError as err:
            print(f"Failed to connect to {target.address}: {err}")
        finally:
            await target.disconnect()

asyncio.run(main())

3. Passive State Tracking & Subscriptions

from casambi_classic_ble import CasambiDevice

device = CasambiDevice(address="AA:BB:CC:DD:EE:FF")

def on_state_change(state: dict):
    # Decoded passive broadcast state dictionary containing verified status
    print(f"State updated: {'ON' if state['on'] else 'OFF'} ({state['level_percent']}%)")

# Register subscription callback (automatically deduplicates identical frames)
unsubscribe = device.register_state_callback(callback=on_state_change)

# Feed raw manufacturer data (0x03C3) received from Bleak or Home Assistant
def on_advertisement(mfr_data: bytes):
    device.update_from_advertisement(mfr_data=mfr_data)

4. Optional Cloud API Bridge

Install with cloud extras: pip install casambi-classic-ble[cloud]

import asyncio
from casambi_classic_ble import CasambiCloud

async def main():
    # Required credentials:
    # - api_key: Casambi developer API key
    # - email & user_password: User account credentials
    # - network_password: Password of the specific lighting network
    async with CasambiCloud(
        api_key="your_api_key",
        email="user@example.com",
        user_password="password",
        network_password="network_password",
    ) as cloud:
        await cloud.create_user_session()
        await cloud.create_network_session()
        net_info = await cloud.get_network_information()
        print("Discovered cloud network information:", net_info)

asyncio.run(main())

Hardware Compatibility & Limitations

• Supported Hardware (Verified in Production):
  • Vadsbo LD220WCM (Trailing-edge phase-cut dimmer)
  • Vadsbo LD220WCM_onoff (On/off relay module)
  • Casambi CBU-PWM4 RGBW (4-channel PWM dimmer)
  • AIMOTION GLOW (Pendant luminaire)
  • All running Casambi Classic firmware (v26.x or earlier).
• Command Variants & Hardware Evidence: See the Command Variant & Hardware Compatibility Matrix in docs/protocol.md for exact opcode payloads (1-byte vs 2-byte unit IDs), verified models, and capture provenance.
• Concurrent Connections: Casambi mesh nodes typically allow only one active BLE connection at a time. If the official Casambi mobile app is actively connected to a node, connection attempts from other clients will be rejected until the app disconnects.
• Protocol Details: See docs/protocol.md for characteristic UUIDs, opcodes, signed session packets, and Wireshark capture guides.

Troubleshooting

Connection Times Out While Casambi App Is Open

Casambi mesh nodes strictly allow only one active Bluetooth Low Energy GATT connection at a time. If the official Casambi mobile app (iOS or Android) is open in the foreground or background on a smartphone or tablet in range, it will hold the GATT connection to the node. Any connection attempt from casambi-classic-ble or Home Assistant will time out with a CasambiConnectionError.

Solution: Force-close or background-disconnect the official Casambi mobile app before connecting with casambi-classic-ble.

Troubleshooting

• Linux / BlueZ Permissions: Non-root users may need permission to access Bluetooth adapters via D-Bus:

  sudo usermod -a -G bluetooth $USER
  

• BlueZ Version: BlueZ >= 5.64 is strongly recommended for reliable BLE GATT operation and connection stability.
• Connection Drops / Timeouts: If connecting directly, ensure the target node is within adequate RF range and no mobile app has an active session open. Using casambi-classic-bt-hass leverages Home Assistant's proxying Bluetooth architecture automatically.

Contributing & Security

• Contributing: See CONTRIBUTING.md and AGENTS.md for development setup, coding standards, and pull request guidelines.
• Security Policy: See SECURITY.md for vulnerability disclosure procedures and private reporting channels.
• Protocol Documentation: See docs/protocol.md for packet formats, opcode tables, and Wireshark capture guides.

Acknowledgements & Attribution

This library is a specialized fork of casambi-bt, originally created by Lukas Kempf (@lkempf). We are immensely grateful to Lukas Kempf and the upstream contributors for their pioneering reverse-engineering and BLE protocol architecture.

See ATTRIBUTION.md for detailed attribution and fork history.

Authors & Maintainers

• Lukas Kempf (@lkempf) — Original author and creator of casambi-bt
• Olof Hellqvist (@hellqvio86, olof.hellqvist@gmail.com) — Maintainer of the casambi-classic-ble fork

License

This project is licensed under the Apache License, Version 2.0 — see the LICENSE file for the full text.