casambi-bt-revamped 0.3.11__tar.gz → 0.3.12.dev2__tar.gz

{casambi_bt_revamped-0.3.11 → casambi_bt_revamped-0.3.12.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: casambi-bt-revamped
-Version: 0.3.11
+Version: 0.3.12.dev2
 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
@@ -26,7 +26,7 @@ Dynamic: license-file
 
 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 events from Casambi switches
+- **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
 
@@ -46,15 +46,38 @@ Have a look at `demo.py` for a small example.
 
 ### Switch Event Support
 
-This library now supports receiving switch button events:
+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(f"Switch event: Unit {event_data['unit_id']}, "
-          f"Button {event_data['button']}, "
-          f"Action: {event_data['event']}")
+    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 ...
@@ -65,6 +88,13 @@ 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),
@@ -79,3 +109,12 @@ If you have problems connecting to the network please check that your network is
 ![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.11 → casambi_bt_revamped-0.3.12.dev2}/README.md

@@ -5,7 +5,7 @@
 
 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 events from Casambi switches
+- **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
 
@@ -25,15 +25,38 @@ Have a look at `demo.py` for a small example.
 
 ### Switch Event Support
 
-This library now supports receiving switch button events:
+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(f"Switch event: Unit {event_data['unit_id']}, "
-          f"Button {event_data['button']}, "
-          f"Action: {event_data['event']}")
+    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 ...
@@ -44,6 +67,13 @@ 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),
@@ -58,3 +88,12 @@ If you have problems connecting to the network please check that your network is
 ![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.11 → casambi_bt_revamped-0.3.12.dev2}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = casambi-bt-revamped
-version = 0.3.11
+version = 0.3.12.dev2
 author = rankjie
 author_email = rankjie@gmail.com
 description = Forked Casambi Bluetooth client library with switch event support, use original if no special need. https://github.com/lkempf/casambi-bt

{casambi_bt_revamped-0.3.11 → casambi_bt_revamped-0.3.12.dev2}/src/CasambiBt/_casambi.py

@@ -400,7 +400,7 @@ class Casambi:
     def _dataCallback(
         self, packetType: IncommingPacketType, data: dict[str, Any]
     ) -> None:
-        self._logger.info(f"Incomming data callback of type {packetType}")
+        self._logger.debug("Incomming data callback of type %s", packetType)
         if packetType == IncommingPacketType.UnitState:
             self._logger.debug(
                 f"Handling changed state {b2a(data['state'])} for unit {data['id']}"
@@ -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.
         """

{casambi_bt_revamped-0.3.11 → casambi_bt_revamped-0.3.12.dev2}/src/CasambiBt/_client.py

@@ -1,6 +1,7 @@
 import asyncio
 import inspect
 import logging
+import platform
 import struct
 from binascii import b2a_hex as b2a
 from collections.abc import Callable
@@ -24,6 +25,7 @@ from cryptography.hazmat.primitives.asymmetric import ec
 from ._constants import CASA_AUTH_CHAR_UUID, ConnectionState
 from ._encryption import Encryptor
 from ._network import Network
+from ._switch_events import SwitchEventStreamDecoder
 
 # We need to move these imports here to prevent a cycle.
 from .errors import (  # noqa: E402
@@ -43,7 +45,7 @@ class IncommingPacketType(IntEnum):
 
 
 MIN_VERSION: Final[int] = 10
-MAX_VERSION: Final[int] = 10
+MAX_VERSION: Final[int] = 11
 
 
 class CasambiClient:
@@ -79,6 +81,7 @@ class CasambiClient:
             else address_or_device
         )
         self._logger = logging.getLogger(__name__)
+        self._switchDecoder = SwitchEventStreamDecoder(self._logger)
         self._connectionState: ConnectionState = ConnectionState.NONE
         self._dataCallback = dataCallback
         self._disconnectedCallback = disonnectedCallback
@@ -122,6 +125,33 @@ class CasambiClient:
             else await get_device(self.address)
         )
 
+        if not device and isinstance(self._address_or_devive, str) and platform.system() == "Darwin":
+            # macOS CoreBluetooth typically reports random per-device identifiers as addresses
+            # unless `use_bdaddr` is enabled. Our `discover()` uses that flag so try it here.
+            try:
+                from ._discover import discover as discover_networks  # local import to avoid cycles
+
+                networks = await discover_networks()
+                wanted = self.address.replace(":", "").lower()
+                for d in networks:
+                    if d.address.replace(":", "").lower() == wanted:
+                        device = d
+                        break
+
+                if not device:
+                    self._logger.warning(
+                        "macOS BLE lookup by address failed. Discovered %d Casambi networks, but none match %s. Discovered=%s",
+                        len(networks),
+                        self.address,
+                        [d.address for d in networks[:10]],
+                    )
+            except Exception:
+                self._logger.debug(
+                    "macOS fallback discovery failed while trying to find %s.",
+                    self.address,
+                    exc_info=True,
+                )
+
         if not device:
             self._logger.error("Failed to discover client.")
             raise NetworkNotFoundError
@@ -448,11 +478,28 @@ class CasambiClient:
             return
 
         packetType = decrypted_data[0]
-        self._logger.debug(f"Incoming data of type {packetType}: {b2a(decrypted_data)}")
+        if self._logger.isEnabledFor(logging.DEBUG):
+            self._logger.debug(
+                "Incoming data of type %d: %s", packetType, b2a(decrypted_data)
+            )
 
         if packetType == IncommingPacketType.UnitState:
             self._parseUnitStates(decrypted_data[1:])
         elif packetType == IncommingPacketType.SwitchEvent:
+            # Stable logs for offline analysis: packet seq + encrypted + decrypted.
+            # (Decrypted data includes the leading packet type byte.)
+            if self._logger.isEnabledFor(logging.DEBUG):
+                self._logger.debug(
+                    "[CASAMBI_RAW_PACKET] Encrypted #%s: %s",
+                    device_sequence,
+                    b2a(raw_encrypted_packet),
+                )
+                self._logger.debug(
+                    "[CASAMBI_DECRYPTED] Type=%d #%s: %s",
+                    packetType,
+                    device_sequence,
+                    b2a(decrypted_data),
+                )
             # Pass the device sequence as the packet sequence for consumers,
             # and still include the raw encrypted packet for diagnostics.
             seq_for_consumer = device_sequence if device_sequence is not None else self._inPacketCount
@@ -466,187 +513,145 @@ class CasambiClient:
             # In the future we might want to parse the revision and issue a warning if there is a mismatch.
             pass
         else:
-            self._logger.info(f"Packet type {packetType} not implemented. Ignoring!")
+            self._logger.debug("Packet type %d not implemented. Ignoring!", packetType)
 
     def _parseUnitStates(self, data: bytes) -> None:
-        self._logger.info("Parsing incoming unit states...")
-        self._logger.debug(f"Incoming unit state: {b2a(data)}")
+        # Ground truth: casambi-android `v1.C1775b.V(Q2.h)` parses decrypted packet type=6
+        # as a stream of unit state records. Records have optional bytes depending on flags.
+        self._logger.debug("Parsing incoming unit states...")
+        if self._logger.isEnabledFor(logging.DEBUG):
+            self._logger.debug("Incoming unit state: %s", b2a(data))
 
         pos = 0
         oldPos = 0
         try:
+            # Android uses `while (available() >= 4)` as the loop condition.
             while pos <= len(data) - 4:
-                id = data[pos]
+                unit_id = data[pos]
                 flags = data[pos + 1]
-                stateLen = ((data[pos + 2] >> 4) & 15) + 1
-                prio = data[pos + 2] & 15
+                b8 = data[pos + 2]
+                state_len = ((b8 >> 4) & 0x0F) + 1
+                prio = b8 & 0x0F
                 pos += 3
 
-                online = flags & 2 != 0
-                on = flags & 1 != 0
-
-                if flags & 4:
-                    pos += 1  # TODO: con?
-                if flags & 8:
-                    pos += 1  # TODO: sid?
-                if flags & 16:
-                    pos += 1  # Unkown value
+                online = (flags & 0x02) != 0
+                on = (flags & 0x01) != 0
+
+                con: int | None = None
+                sid: int | None = None
+
+                # Optional bytes, matching Android:
+                # - flags&0x04: con (1 byte)
+                # - flags&0x08: sid (1 byte)
+                # - flags&0x10: extra byte; if missing Android uses 0xFF
+                if flags & 0x04:
+                    con = data[pos]
+                    pos += 1
+                if flags & 0x08:
+                    sid = data[pos]
+                    pos += 1
+
+                if flags & 0x10:
+                    extra_byte = data[pos]
+                    pos += 1
+                else:
+                    extra_byte = 0xFF
 
-                state = data[pos : pos + stateLen]
-                pos += stateLen
+                state = data[pos : pos + state_len]
+                pos += state_len
 
-                pos += (flags >> 6) & 3  # Padding?
+                padding_len = (flags >> 6) & 0x03
+                padding = data[pos : pos + padding_len] if padding_len else b""
+                pos += padding_len
 
-                self._logger.debug(
-                    f"Parsed state: Id {id}, prio {prio}, online {online}, on {on}, state {b2a(state)}1"
-                )
+                if self._logger.isEnabledFor(logging.DEBUG):
+                    self._logger.debug(
+                        "[CASAMBI_UNITSTATE_PARSED] unit=%d flags=0x%02x prio=%d online=%s on=%s con=%s sid=%s extra_byte=%d state=%s padding=%s",
+                        unit_id,
+                        flags,
+                        prio,
+                        online,
+                        on,
+                        con,
+                        sid,
+                        extra_byte,
+                        b2a(state),
+                        b2a(padding),
+                    )
 
                 self._dataCallback(
                     IncommingPacketType.UnitState,
-                    {"id": id, "online": online, "on": on, "state": state},
+                    {
+                        "id": unit_id,
+                        "online": online,
+                        "on": on,
+                        "state": state,
+                        # Additional fields for diagnostics/analysis
+                        "flags": flags,
+                        "prio": prio,
+                        "state_len": state_len,
+                        "padding_len": padding_len,
+                        "con": con,
+                        "sid": sid,
+                        "extra_byte": extra_byte,
+                        "extra_float": extra_byte / 255.0,
+                    },
                 )
 
                 oldPos = pos
         except IndexError:
             self._logger.error(
-                f"Ran out of data while parsing unit state! Remaining data {b2a(data[oldPos:])} in {b2a(data)}."
+                "Ran out of data while parsing unit state! Remaining data %s in %s.",
+                b2a(data[oldPos:]),
+                b2a(data),
             )
 
     def _parseSwitchEvent(
         self, data: bytes, packet_seq: int = None, raw_packet: bytes = None
     ) -> None:
-        """Parse switch event packet which contains multiple message types."""
-        self._logger.info(
-            f"Parsing incoming switch event packet #{packet_seq}... Data: {b2a(data)}"
-        )
+        """Parse decrypted packet type=7 payload (INVOCATION stream).
 
-        # Special handling for message type 0x29 - likely an extended/aux message
-        if len(data) >= 1 and data[0] == 0x29:
-            # Log details so we can correlate with outgoing ExtPacketSend trials
-            if len(data) >= 3:
-                length = ((data[2] >> 4) & 15) + 1
-                parameter = data[2] & 15
-                payload = data[3 : 3 + min(length, max(0, len(data) - 3))]
-                self._logger.info(
-                    f"Ext-like message at packet head: flags=0x{data[1]:02x}, param={parameter}, payload={b2a(payload)}"
-                )
-            else:
-                self._logger.info(
-                    f"Ext-like message 0x29 at packet head with insufficient length: {b2a(data)}"
-                )
-            return
-
-        pos = 0
-        oldPos = 0
-        switch_events_found = 0
+        Ground truth: casambi-android `v1.C1775b.Q(Q2.h)` parses decrypted packet type=7
+        as a stream of INVOCATION frames. Switch button events are INVOCATIONs.
+        """
 
-        try:
-            while pos <= len(data) - 3:
-                oldPos = pos
-
-                # Parse message header
-                message_type = data[pos]
-                flags = data[pos + 1]
-                length = ((data[pos + 2] >> 4) & 15) + 1
-                parameter = data[pos + 2]  # Full byte, not just lower 4 bits
-                pos += 3
-
-                # Sanity check: message type should be reasonable
-                if message_type > 0x80:
-                    self._logger.debug(
-                        f"Skipping invalid message type 0x{message_type:02x} at position {oldPos}"
-                    )
-                    # Try to resync by looking for next valid message
-                    pos = oldPos + 1
-                    continue
-
-                # Check if we have enough data for the payload
-                if pos + length > len(data):
-                    self._logger.debug(
-                        f"Incomplete message at position {oldPos}. "
-                        f"Type: 0x{message_type:02x}, declared length: {length}, available: {len(data) - pos}"
-                    )
-                    break
-
-                # Extract the payload
-                payload = data[pos : pos + length]
-                pos += length
-
-                # Process based on message type
-                if message_type == 0x08 or message_type == 0x10:  # Switch/button events
-                    switch_events_found += 1
-                    
-                    # Button extraction differs between type 0x08 and type 0x10
-                    if message_type == 0x08:
-                        # For type 0x08, the lower nibble is a code that maps to physical button id
-                        # Using formula: ((code + 2) % 4) + 1 based on reverse engineering findings
-                        code_nibble = parameter & 0x0F
-                        button = ((code_nibble + 2) % 4) + 1
-                        self._logger.debug(
-                            f"Type 0x08 button extraction: parameter=0x{parameter:02x}, code={code_nibble}, button={button}"
-                        )
-                    else:
-                        # For type 0x10, use existing logic
-                        button_lower = parameter & 0x0F
-                        button_upper = (parameter >> 4) & 0x0F
-
-                        # Use upper 4 bits if lower 4 bits are 0, otherwise use lower 4 bits
-                        if button_lower == 0 and button_upper != 0:
-                            button = button_upper
-                            self._logger.debug(
-                                f"Type 0x10 button extraction: parameter=0x{parameter:02x}, using upper nibble, button={button}"
-                            )
-                        else:
-                            button = button_lower
-                            self._logger.debug(
-                                f"Type 0x10 button extraction: parameter=0x{parameter:02x}, using lower nibble, button={button}"
-                            )
-
-                    # For type 0x10 messages, we need to pass additional data beyond the declared payload
-                    if message_type == 0x10:
-                        # Extend to include at least 10 bytes from message start for state byte
-                        extended_end = min(oldPos + 11, len(data))
-                        full_message_data = data[oldPos:extended_end]
-                    else:
-                        full_message_data = data
-                    self._processSwitchMessage(
-                        message_type,
-                        flags,
-                        button,
-                        payload,
-                        full_message_data,
-                        oldPos,
-                        packet_seq,
-                        raw_packet,
-                    )
-                elif message_type == 0x29:
-                    # Extended/aux message embedded in switch event packet
-                    self._logger.info(
-                        f"Embedded 0x29 ext-like msg: flags=0x{flags:02x}, param=0x{parameter & 0x0F:01x}, payload={b2a(payload)}"
-                    )
-                elif message_type in [0x00, 0x06, 0x09, 0x1F, 0x2A]:
-                    # Known non-switch message types - log at debug level
-                    self._logger.debug(
-                        f"Non-switch message type 0x{message_type:02x}: flags=0x{flags:02x}, "
-                        f"param={parameter}, payload={b2a(payload)}"
-                    )
-                else:
-                    # Unknown message types - log at info level
-                    self._logger.info(
-                        f"Unknown message type 0x{message_type:02x}: flags=0x{flags:02x}, "
-                        f"param={parameter}, payload={b2a(payload)}"
-                    )
+        if self._logger.isEnabledFor(logging.DEBUG):
+            data_hex = b2a(data)
+            self._logger.debug(
+                "Parsing incoming switch event packet #%s... Data: %s",
+                packet_seq,
+                data_hex,
+            )
+            self._logger.debug(
+                "[CASAMBI_SWITCH_PACKET] Full data #%s: hex=%s len=%d",
+                packet_seq,
+                data_hex,
+                len(data),
+            )
 
-                oldPos = pos
+        events, stats = self._switchDecoder.decode(
+            data,
+            packet_seq=packet_seq,
+            raw_packet=raw_packet,
+            arrival_sequence=self._inPacketCount,
+        )
 
-        except IndexError:
-            self._logger.error(
-                f"Ran out of data while parsing switch event packet! "
-                f"Remaining data {b2a(data[oldPos:])} in {b2a(data)}."
-            )
+        self._logger.debug(
+            "[CASAMBI_SWITCH_SUMMARY] packet=%s frames=%d button_frames=%d input_frames=%d ignored=%d emitted=%d suppressed_same_state=%d",
+            packet_seq,
+            stats.frames_total,
+            stats.frames_button,
+            stats.frames_input,
+            stats.frames_ignored,
+            stats.events_emitted,
+            stats.events_suppressed_same_state,
+        )
 
-        if switch_events_found == 0:
-            self._logger.debug(f"No switch events found in packet: {b2a(data)}")
+        for ev in events:
+            # Back-compat alias: older consumers looked for 'flags'
+            if "flags" not in ev:
+                ev["flags"] = ev.get("invocation_flags")
+            self._dataCallback(IncommingPacketType.SwitchEvent, ev)
 
     def _processSwitchMessage(
         self,