This release is a pre-release and may not be stable for production use.
Casambi Bluetooth Revamped - Python library for Casambi networks
This is a customized fork of the original casambi-bt library with additional features and should only be used for special needs:
- Switch event support - Receive button press/release/hold events from Casambi switches (wired + wireless)
- Improved relay status handling - Better support for relay units
- Classic protocol (experimental) - Basic unit control for Classic (legacy) firmware networks
- Bug fixes and improvements - Various fixes based on real-world usage
This library provides a bluetooth interface to Casambi-based lights. It is not associated with Casambi.
For Home Assistant integration using this library, see casambi-bt-hass.
Getting started
This library is available on PyPi:
pip install casambi-bt-revamped
Have a look at demo.py for a small example.
Switch Event Support
This library supports receiving physical switch events as a decoded stream of INVOCATION frames (ground truth from the official Android app).
Event types you can expect, exactly one per physical action:
button_pressbutton_release(short press;press_duration_msis set when reported by the switch itself)button_hold(long press threshold reached)button_release_after_holdinput_event(NotifyInput frame with an unknown code; diagnostics only)
Every event also carries source (button_event = the switch's own ButtonEvent stream,
notify_input = NotifyInput stream) and held (True for hold / release-after-hold).
from CasambiBt import Casambi
def handle_switch_event(event_data):
print(
"Switch event:",
{
"unit_id": event_data.get("unit_id"),
"button": event_data.get("button"),
"event": event_data.get("event"),
# INVOCATION metadata (useful for debugging/correlation)
"event_id": event_data.get("event_id"),
"opcode": event_data.get("opcode"),
"target_type": event_data.get("target_type"),
"origin": event_data.get("origin"),
"age": event_data.get("age"),
# NotifyInput fields (target_type=0x12)
"input_code": event_data.get("input_code"),
"input_channel": event_data.get("input_channel"),
"input_value16": event_data.get("input_value16"),
"input_mapped_event": event_data.get("input_mapped_event"),
},
)
casa = Casambi()
# ... connect to network ...
# Register switch event handler
casa.registerSwitchEventHandler(handle_switch_event)
# Events will be received when buttons are pressed/released
Notes:
- Wireless (battery) switches send a "button stream" (target_type
0x06) for press/release with the press duration; a mains unit additionally reports the same action as NotifyInput (target_type0x12), which is also the only carrier of hold. - Wired switches often only send NotifyInput (target_type
0x12); itsinput_codeis mapped intobutton_press/button_release/.... - The mesh re-floods every frame several times. The library drops these copies by invocation identity (origin handle + opcode + target + payload) and pairs the two streams by count, so no per-button state is kept and a lost or reordered frame never swallows a later press. Consumers do not need their own deduplication.
For the parsing details and field layout, see doc/PROTOCOL_PARSING.md.
Classic (Legacy Firmware) Support (Experimental)
This library can also connect to Classic Casambi networks and send unit control commands.
How it works (ground truth: the bundled Android app sources):
- Classic devices expose a CMAC-signed data channel (
ca51/ca52) or a "Classic conformant" signed channel on the EVO UUID. - The cloud network JSON exposes
visitorKey/managerKey(hex strings) instead of an EVOkeyStore. - Commands are signed with AES-CMAC and sent as Classic "command records" (see
doc/PROTOCOL_PARSING.md).
Environment flags:
CASAMBI_BT_DISABLE_CLASSIC=1to refuse Classic connections (fail fast)CASAMBI_BT_CLASSIC_USE_MANAGER=1to sign with the 16-byte manager signature (default is visitor/4-byte prefix)CASAMBI_BT_LOG_RAW_NOTIFIES=1to enable very verbose per-notify hexdumps (mainly for Classic debugging)
MacOS
MacOS does not expose the Bluetooth MAC address via their official API, if you're running this library on MacOS, it will use an undocumented IOBluetooth API to get the MAC Address. Without the real MAC address the integration with Casambi will not work. If you're running into problems fetching the MAC address on MacOS, try it on a Raspberry Pi.
Casambi network setup
If you have problems connecting to the network please check that your network is configured appropriately before creating an issue. The network I test this with uses the Evoultion firmware and is configured as follows (screenshots are for the iOS app but the Android app should look very similar):
Development / Offline Testing
This repo includes log-driven unit tests for switch parsing:
cd casambi-bt
python -m unittest -v
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file casambi_bt_revamped-0.4.2.dev7.tar.gz.
File metadata
- Download URL: casambi_bt_revamped-0.4.2.dev7.tar.gz
- Upload date:
- Size: 76.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1d8933077dadf056399f23fbdc7a867602046667d4c5b09009b26d42a7de41d0
|
|
| MD5 |
19f1185589bc0d0ea6fd3c8fc4c163bf
|
|
| BLAKE2b-256 |
d05f147ea3c1d8dfc83314dcc54a86e5cb901b91331beb37e079a6072dcfcee3
|
File details
Details for the file casambi_bt_revamped-0.4.2.dev7-py3-none-any.whl.
File metadata
- Download URL: casambi_bt_revamped-0.4.2.dev7-py3-none-any.whl
- Upload date:
- Size: 67.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
811f92636b8c6023c23739e440f7e4ca8a9fb2369b6adbd2933d6be7b73b890c
|
|
| MD5 |
7ac7dae5c75db0dfd9036556b359f1dd
|
|
| BLAKE2b-256 |
56fefb1763e192d466e4ad30f472095d8c1615553bfaf99d969e10c0d0f0964c
|
