casambi-bt-revamped 0.3.10__tar.gz → 0.3.12.dev1__tar.gz

casambi_bt_revamped-0.3.12.dev1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: casambi-bt-revamped
+Version: 0.3.12.dev1
+Summary: Forked Casambi Bluetooth client library with switch event support, use original if no special need. https://github.com/lkempf/casambi-bt
+Home-page: https://github.com/rankjie/casambi-bt
+Author: rankjie
+Author-email: rankjie@gmail.com
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak!=2.0.0,>=0.22
+Requires-Dist: cryptography>=40.0.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: bleak_retry_connector>=3.6.0
+Requires-Dist: anyio>=4.10.0
+Dynamic: license-file
+
+![PyPI](https://img.shields.io/pypi/v/casambi-bt-revamped)
+[![Discord](https://img.shields.io/discord/1186445089317326888)](https://discord.gg/jgZVugfx)
+
+# Casambi Bluetooth Revamped - Python library for Casambi networks
+
+This is a customized fork of the original [casambi-bt](https://github.com/lkempf/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
+- **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](https://github.com/rankjie/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:
+- `button_press`
+- `button_release`
+- `button_hold`
+- `button_release_after_hold`
+- `input_event` (raw NotifyInput frame that may accompany presses/holds; useful for diagnostics and some wired devices)
+
+```python
+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 typically send a "button stream" (target_type `0x06`) for press/release, and a NotifyInput stream (target_type `0x12`) for hold/release-after-hold.
+- Wired switches often only send NotifyInput (target_type `0x12`), so `input_code` is mapped into `button_press/button_release/...` when appropriate.
+- The library suppresses same-state retransmits at the protocol layer (edge detection), so Home Assistant-style time-window deduplication should generally not be necessary.
+
+For the parsing details and field layout, see `doc/PROTOCOL_PARSING.md`.
+
+### MacOS
+
+MacOS [does not expose the Bluetooth MAC address via their official API](https://github.com/hbldh/bleak/issues/140),
+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):
+
+![Gateway settings](/doc/img/gateway.png)
+![Network settings](/doc/img/network.png)
+![Performance settings](/doc/img/perf.png)
+
+## Development / Offline Testing
+
+This repo includes log-driven unit tests for switch parsing:
+
+```bash
+cd casambi-bt
+python -m unittest -v
+```

casambi_bt_revamped-0.3.12.dev1/README.md

@@ -0,0 +1,99 @@
+![PyPI](https://img.shields.io/pypi/v/casambi-bt-revamped)
+[![Discord](https://img.shields.io/discord/1186445089317326888)](https://discord.gg/jgZVugfx)
+
+# Casambi Bluetooth Revamped - Python library for Casambi networks
+
+This is a customized fork of the original [casambi-bt](https://github.com/lkempf/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
+- **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](https://github.com/rankjie/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:
+- `button_press`
+- `button_release`
+- `button_hold`
+- `button_release_after_hold`
+- `input_event` (raw NotifyInput frame that may accompany presses/holds; useful for diagnostics and some wired devices)
+
+```python
+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 typically send a "button stream" (target_type `0x06`) for press/release, and a NotifyInput stream (target_type `0x12`) for hold/release-after-hold.
+- Wired switches often only send NotifyInput (target_type `0x12`), so `input_code` is mapped into `button_press/button_release/...` when appropriate.
+- The library suppresses same-state retransmits at the protocol layer (edge detection), so Home Assistant-style time-window deduplication should generally not be necessary.
+
+For the parsing details and field layout, see `doc/PROTOCOL_PARSING.md`.
+
+### MacOS
+
+MacOS [does not expose the Bluetooth MAC address via their official API](https://github.com/hbldh/bleak/issues/140),
+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):
+
+![Gateway settings](/doc/img/gateway.png)
+![Network settings](/doc/img/network.png)
+![Performance settings](/doc/img/perf.png)
+
+## Development / Offline Testing
+
+This repo includes log-driven unit tests for switch parsing:
+
+```bash
+cd casambi-bt
+python -m unittest -v
+```

{casambi_bt_revamped-0.3.10 → casambi_bt_revamped-0.3.12.dev1}/setup.cfg

@@ -1,9 +1,9 @@
 [metadata]
 name = casambi-bt-revamped
-version = 0.3.10
+version = 0.3.12.dev1
 author = rankjie
 author_email = rankjie@gmail.com
-description = Enhanced Casambi Bluetooth client library with switch event support
+description = Forked Casambi Bluetooth client library with switch event support, use original if no special need. https://github.com/lkempf/casambi-bt
 long_description = file: README.md
 long_description_content_type = text/markdown
 url = https://github.com/rankjie/casambi-bt
@@ -23,7 +23,7 @@ install_requires =
 	cryptography>=40.0.0
 	httpx>=0.25
 	bleak_retry_connector >= 3.6.0
-	aiopath==0.7.*
+	anyio>=4.10.0
 
 [options.packages.find]
 where = src

{casambi_bt_revamped-0.3.10 → casambi_bt_revamped-0.3.12.dev1}/src/CasambiBt/_cache.py

@@ -6,28 +6,28 @@ import shutil
 from types import TracebackType
 from typing import Final
 
-from aiopath import AsyncPath  # type: ignore
+from anyio import Path
 
 _LOGGER = logging.getLogger(__name__)
 
-CACHE_PATH_DEFAULT: Final = AsyncPath(os.getcwd()) / "casambi-bt-store"
+CACHE_PATH_DEFAULT: Final = Path(os.getcwd()) / "casambi-bt-store"
 CACHE_VERSION: Final = 2
 
-# We need a global lock since there could be multiple Caambi instances
+# We need a global lock since there could be multiple Casambi instances
 # with their own cache instances pointing to the same folder.
 _cacheLock = asyncio.Lock()
 
 
-def _blocking_delete(path: AsyncPath) -> None:
+def _blocking_delete(path: Path) -> None:
     shutil.rmtree(pathlib.Path(path))
 
 
 class Cache:
-    def __init__(self, cachePath: AsyncPath | pathlib.Path | None) -> None:
+    def __init__(self, cachePath: Path | pathlib.Path | None) -> None:
         if cachePath is None:
             self._cachePath = CACHE_PATH_DEFAULT
-        elif not isinstance(cachePath, AsyncPath):
-            self._cachePath = AsyncPath(cachePath)
+        elif not isinstance(cachePath, Path):
+            self._cachePath = Path(cachePath)
         else:
             self._cachePath = cachePath
 
@@ -69,7 +69,7 @@ class Cache:
             await self._cachePath.mkdir(mode=0o700)
             await self._cacheVersionFile.write_text(str(CACHE_VERSION))
 
-    async def __aenter__(self) -> AsyncPath:
+    async def __aenter__(self) -> Path:
         await _cacheLock.acquire()
 
         if self._uuid is None:
@@ -78,7 +78,7 @@ class Cache:
         try:
             await self._ensureCacheValid()
 
-            cacheDir = AsyncPath(self._cachePath / self._uuid)
+            cacheDir = Path(self._cachePath / self._uuid)
             if not await cacheDir.exists():
                 _LOGGER.debug("Creating cache entry for id %s", self._uuid)
                 await cacheDir.mkdir()

{casambi_bt_revamped-0.3.10 → casambi_bt_revamped-0.3.12.dev1}/src/CasambiBt/_casambi.py

@@ -473,13 +473,17 @@ class Casambi:
         """Register a new handler for switch events.
 
         This handler is called whenever a switch event is received.
-        The handler is supplied with a dictionary containing:
-        - unit_id: The ID of the switch unit
-        - button: The button number that was pressed/released
-        - event: Either "button_press" or "button_release"
-        - message_type: The raw message type (0x08 or 0x10)
-        - flags: Additional flags from the message
-        - extra_data: Any additional data from the message
+        The handler is supplied with a dictionary containing (at minimum):
+        - unit_id: target unit id (from INVOCATION target high byte)
+        - button: best-effort "label" (typically 1..4 for 4-gang switches)
+        - event: "button_press" | "button_release" | "input_event"
+
+        Switch events are parsed from decrypted packet type=7 (INVOCATION stream),
+        matching casambi-android `v1.C1775b.Q(Q2.h)`. Extra diagnostic keys include:
+        - invocation_flags, opcode, origin, target, target_type, age, origin_handle
+        - button_event_index (0..7), param_p, param_s
+        - input_index (0..7), input_code, input_b1, input_channel, input_value16, input_mapped_event
+        - packet_sequence, arrival_sequence, raw_packet, decrypted_data, payload_hex, frame_offset, event_id
 
         :param handler: The method to call when a switch event is received.
         """