casambi-bt-revamped 0.3.11__py3-none-any.whl → 0.3.12.dev2__py3-none-any.whl

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.
         """

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,

CasambiBt/_invocation.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Final
+
+
+@dataclass(frozen=True, slots=True)
+class InvocationFrame:
+    """One INVOCATION frame.
+
+    Ground truth: casambi-android `v1.C1775b.Q(Q2.h)` parses:
+    - flags:u16 (big-endian)
+    - opcode:u8
+    - origin:u16
+    - target:u16
+    - age:u16
+    - origin_handle?:u8 (if flags & 0x0200)
+    - payload: flags & 0x3f bytes
+    """
+
+    flags: int
+    opcode: int
+    origin: int
+    target: int
+    age: int
+    origin_handle: int | None
+    payload: bytes
+    offset: int  # start offset of this frame in the decrypted type=7 payload
+
+    @property
+    def payload_len(self) -> int:
+        return self.flags & 0x3F
+
+
+_FLAG_HAS_ORIGIN_HANDLE: Final[int] = 0x0200
+
+
+def parse_invocation_stream(
+    data: bytes, *, logger: logging.Logger | None = None
+) -> list[InvocationFrame]:
+    """Parse decrypted packet type=7 payload into INVOCATION frames."""
+
+    frames: list[InvocationFrame] = []
+    pos = 0
+
+    # Android bails out if < 9 bytes remain.
+    while len(data) - pos >= 9:
+        frame_offset = pos
+
+        flags = int.from_bytes(data[pos : pos + 2], "big")
+        pos += 2
+
+        opcode = data[pos]
+        pos += 1
+
+        origin = int.from_bytes(data[pos : pos + 2], "big")
+        pos += 2
+
+        target = int.from_bytes(data[pos : pos + 2], "big")
+        pos += 2
+
+        age = int.from_bytes(data[pos : pos + 2], "big")
+        pos += 2
+
+        origin_handle: int | None = None
+        if flags & _FLAG_HAS_ORIGIN_HANDLE:
+            if pos >= len(data):
+                if logger:
+                    logger.debug(
+                        "INVOCATION frame truncated at origin_handle (offset=%d flags=0x%04x).",
+                        frame_offset,
+                        flags,
+                    )
+                break
+            origin_handle = data[pos]
+            pos += 1
+
+        payload_len = flags & 0x3F
+        if pos + payload_len > len(data):
+            if logger:
+                logger.debug(
+                    "INVOCATION frame truncated at payload (offset=%d flags=0x%04x payload_len=%d remaining=%d).",
+                    frame_offset,
+                    flags,
+                    payload_len,
+                    len(data) - pos,
+                )
+            break
+
+        payload = data[pos : pos + payload_len]
+        pos += payload_len
+
+        frames.append(
+            InvocationFrame(
+                flags=flags,
+                opcode=opcode,
+                origin=origin,
+                target=target,
+                age=age,
+                origin_handle=origin_handle,
+                payload=payload,
+                offset=frame_offset,
+            )
+        )
+
+    if logger and pos != len(data):
+        logger.debug(
+            "INVOCATION stream has %d trailing bytes (parsed=%d total=%d).",
+            len(data) - pos,
+            pos,
+            len(data),
+        )
+
+    return frames
+

CasambiBt/_switch_events.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import logging
+import time
+from binascii import b2a_hex as b2a
+from dataclasses import dataclass
+from typing import Any, Final
+
+from ._invocation import InvocationFrame, parse_invocation_stream
+
+
+_BUTTON_EVENT_MIN: Final[int] = 29  # FunctionButtonEvent0
+_BUTTON_EVENT_MAX: Final[int] = 36  # FunctionButtonEvent7
+_INPUT_EVENT_MIN: Final[int] = 64  # FunctionNotifyInput0
+_INPUT_EVENT_MAX: Final[int] = 71  # FunctionNotifyInput7
+
+_TARGET_TYPE_BUTTON: Final[int] = 0x06
+_TARGET_TYPE_INPUT: Final[int] = 0x12
+
+
+def _guess_button_label_4gang(button_event_index: int) -> int:
+    """Casambi app labels a typical 4-button switch as 1..4.
+
+    Observed mapping for 4-gang switches in provided logs:
+    - ButtonEvent0 -> label 4
+    - ButtonEvent1 -> label 1
+    - ButtonEvent2 -> label 2
+    - ButtonEvent3 -> label 3
+    """
+
+    if 0 <= button_event_index <= 3:
+        return ((button_event_index + 3) % 4) + 1
+    return button_event_index
+
+
+@dataclass(slots=True)
+class SwitchDecoderStats:
+    frames_total: int = 0
+    frames_button: int = 0
+    frames_input: int = 0
+    frames_ignored: int = 0
+    events_emitted: int = 0
+    events_suppressed_same_state: int = 0
+
+
+class SwitchEventStreamDecoder:
+    """Decode decrypted packet type=7 payload into high-level switch events."""
+
+    def __init__(self, logger: logging.Logger | None = None) -> None:
+        self._logger = logger or logging.getLogger(__name__)
+        # (unit_id, button_event_index) -> pressed(bool)
+        self._last_pressed: dict[tuple[int, int], bool] = {}
+        # (unit_id, input_index) -> last input code (payload[0]) we emitted as a semantic event.
+        self._last_input_code: dict[tuple[int, int], int] = {}
+        # (unit_id, button_label) -> observed real button stream (target_type=0x06) for that button.
+        # If present, we avoid creating synthetic press/release events from input frames.
+        self._button_stream_seen: set[tuple[int, int]] = set()
+
+    def reset(self) -> None:
+        self._last_pressed.clear()
+        self._last_input_code.clear()
+        self._button_stream_seen.clear()
+
+    def decode(
+        self,
+        data: bytes,
+        *,
+        packet_seq: int | None = None,
+        raw_packet: bytes | None = None,
+        arrival_sequence: int | None = None,
+    ) -> tuple[list[dict[str, Any]], SwitchDecoderStats]:
+        """Decode one decrypted switch packet payload."""
+
+        frames = parse_invocation_stream(data, logger=self._logger)
+        stats = SwitchDecoderStats(frames_total=len(frames))
+        events: list[dict[str, Any]] = []
+
+        for frame in frames:
+            ev = self._decode_frame(
+                frame,
+                data=data,
+                packet_seq=packet_seq,
+                raw_packet=raw_packet,
+                arrival_sequence=arrival_sequence,
+                stats=stats,
+            )
+            if ev is None:
+                continue
+            events.append(ev)
+            stats.events_emitted += 1
+
+        return events, stats
+
+    def _decode_frame(
+        self,
+        frame: InvocationFrame,
+        *,
+        data: bytes,
+        packet_seq: int | None,
+        raw_packet: bytes | None,
+        arrival_sequence: int | None,
+        stats: SwitchDecoderStats,
+    ) -> dict[str, Any] | None:
+        unit_id = (frame.target >> 8) & 0xFF
+        target_type = frame.target & 0xFF
+
+        origin_unit_id = (frame.origin >> 8) & 0xFF
+        origin_type = frame.origin & 0xFF
+
+        # Button events (press/release) are INVOCATIONs targeted at type 0x06.
+        if (
+            target_type == _TARGET_TYPE_BUTTON
+            and _BUTTON_EVENT_MIN <= frame.opcode <= _BUTTON_EVENT_MAX
+        ):
+            stats.frames_button += 1
+
+            button_event_index = frame.opcode - _BUTTON_EVENT_MIN
+            button = _guess_button_label_4gang(button_event_index)
+            self._button_stream_seen.add((unit_id, button))
+
+            pressed = bool(frame.payload and (frame.payload[0] & 0x80))
+            state_key = (unit_id, button_event_index)
+            last_pressed = self._last_pressed.get(state_key)
+
+            # Wireless switches retransmit; drop repeated same-state frames to avoid duplicate events.
+            if last_pressed is not None and last_pressed == pressed:
+                stats.events_suppressed_same_state += 1
+                self._logger.debug(
+                    "[CASAMBI_EVENT_SUPPRESS] unit=%d button_index=%d button=%d pressed=%s opcode=0x%02x origin=0x%04x age=0x%04x",
+                    unit_id,
+                    button_event_index,
+                    button,
+                    pressed,
+                    frame.opcode,
+                    frame.origin,
+                    frame.age,
+                )
+                return None
+            self._last_pressed[state_key] = pressed
+
+            b0 = frame.payload[0] if frame.payload else 0
+            param_p = (b0 >> 3) & 0x0F
+            param_s = b0 & 0x07
+
+            event = "button_press" if pressed else "button_release"
+
+            # Stable identifier for consumers to deduplicate further if needed.
+            event_id = f"invoke:{frame.origin:04x}:{frame.age:04x}:{frame.opcode:02x}:{frame.target:04x}"
+
+            if self._logger.isEnabledFor(logging.DEBUG):
+                self._logger.debug(
+                    "[CASAMBI_BUTTON_EVENT] packet=%s unit=%d button=%d event=%s opcode=0x%02x origin=0x%04x age=0x%04x flags=0x%04x payload=%s",
+                    packet_seq,
+                    unit_id,
+                    button,
+                    event,
+                    frame.opcode,
+                    frame.origin,
+                    frame.age,
+                    frame.flags,
+                    b2a(frame.payload),
+                )
+
+            return {
+                # Back-compat / existing consumers
+                "unit_id": unit_id,
+                "button": button,
+                "event": event,
+                "message_type": 0x07,  # decrypted packet type (SwitchEvent)
+                "message_position": frame.offset,
+                "extra_data": None,
+                # INVOCATION fields
+                "invocation_flags": frame.flags,
+                "opcode": frame.opcode,
+                "origin": frame.origin,
+                "origin_unit_id": origin_unit_id,
+                "origin_type": origin_type,
+                "target": frame.target,
+                "target_type": target_type,
+                "age": frame.age,
+                "origin_handle": frame.origin_handle,
+                "payload": frame.payload,
+                "payload_hex": b2a(frame.payload),
+                "frame_offset": frame.offset,
+                "button_event_index": button_event_index,
+                "param_p": param_p,
+                "param_s": param_s,
+                # Diagnostics / correlation
+                "packet_sequence": packet_seq,
+                "arrival_sequence": arrival_sequence,
+                "event_id": event_id,
+                "raw_packet": b2a(raw_packet) if raw_packet else None,
+                "decrypted_data": b2a(data),
+                "frame_hex": b2a(
+                    data[frame.offset : frame.offset + (9 + (1 if frame.origin_handle is not None else 0) + frame.payload_len)]
+                ),
+                "received_at": time.time(),
+            }
+
+        # Input notify frames (often accompany wireless switches).
+        if (
+            target_type == _TARGET_TYPE_INPUT
+            and _INPUT_EVENT_MIN <= frame.opcode <= _INPUT_EVENT_MAX
+        ):
+            stats.frames_input += 1
+            input_index = frame.opcode - _INPUT_EVENT_MIN
+            input_code = frame.payload[0] if frame.payload else None
+            input_b1 = frame.payload[1] if len(frame.payload) >= 2 else None
+            input_channel = (input_b1 & 0x07) if input_b1 is not None else None
+            input_value16 = (
+                int.from_bytes(frame.payload[2:4], "little")
+                if len(frame.payload) >= 4
+                else None
+            )
+            button = _guess_button_label_4gang(input_index)
+
+            # Map common input codes into the legacy "switch" event taxonomy.
+            # Observed:
+            # - wired: 01xx press, 02xx release, 0cxx release_after_hold
+            # - wireless: 09xx hold, 0cxx release_after_hold (+ separate button stream for press/release)
+            mapped_event: str | None = None
+            if input_code is not None:
+                if input_code == 0x09:
+                    mapped_event = "button_hold"
+                elif input_code == 0x0C:
+                    mapped_event = "button_release_after_hold"
+                elif input_code == 0x01:
+                    mapped_event = "button_press"
+                elif input_code == 0x02:
+                    mapped_event = "button_release"
+
+            input_mapped_event = mapped_event
+
+            # Avoid duplicating press/release for wireless switches that also produce the real button stream.
+            if mapped_event in ("button_press", "button_release") and (unit_id, button) in self._button_stream_seen:
+                mapped_event = None
+
+            if mapped_event is not None and input_code is not None:
+                state_key = (unit_id, input_index)
+                last_code = self._last_input_code.get(state_key)
+                if last_code == input_code:
+                    stats.events_suppressed_same_state += 1
+                    self._logger.debug(
+                        "[CASAMBI_EVENT_SUPPRESS] input unit=%d input_index=%d button=%d code=0x%02x opcode=0x%02x origin=0x%04x age=0x%04x",
+                        unit_id,
+                        input_index,
+                        button,
+                        input_code,
+                        frame.opcode,
+                        frame.origin,
+                        frame.age,
+                    )
+                    return None
+                self._last_input_code[state_key] = input_code
+
+                if self._logger.isEnabledFor(logging.DEBUG):
+                    self._logger.debug(
+                        "[CASAMBI_INPUT_AS_BUTTON] packet=%s unit=%d button=%d event=%s code=0x%02x opcode=0x%02x origin=0x%04x age=0x%04x flags=0x%04x payload=%s",
+                        packet_seq,
+                        unit_id,
+                        button,
+                        mapped_event,
+                        input_code,
+                        frame.opcode,
+                        frame.origin,
+                        frame.age,
+                        frame.flags,
+                        b2a(frame.payload),
+                    )
+            event = mapped_event or "input_event"
+            self._logger.debug(
+                "[CASAMBI_INPUT_EVENT] packet=%s unit=%d input=%d opcode=0x%02x origin=0x%04x age=0x%04x flags=0x%04x code=%s ch=%s val=%s payload=%s",
+                packet_seq,
+                unit_id,
+                input_index,
+                frame.opcode,
+                frame.origin,
+                frame.age,
+                frame.flags,
+                f"0x{input_code:02x}" if input_code is not None else None,
+                input_channel,
+                input_value16,
+                b2a(frame.payload),
+            )
+            return {
+                "unit_id": unit_id,
+                "button": button,
+                "event": event,
+                "message_type": 0x07,
+                "message_position": frame.offset,
+                "extra_data": None,
+                "invocation_flags": frame.flags,
+                "opcode": frame.opcode,
+                "origin": frame.origin,
+                "origin_unit_id": origin_unit_id,
+                "origin_type": origin_type,
+                "target": frame.target,
+                "target_type": target_type,
+                "age": frame.age,
+                "origin_handle": frame.origin_handle,
+                "payload": frame.payload,
+                "payload_hex": b2a(frame.payload),
+                "frame_offset": frame.offset,
+                "input_index": input_index,
+                "input_code": input_code,
+                "input_b1": input_b1,
+                "input_channel": input_channel,
+                "input_value16": input_value16,
+                "input_mapped_event": input_mapped_event,
+                "packet_sequence": packet_seq,
+                "arrival_sequence": arrival_sequence,
+                "event_id": f"invoke:{frame.origin:04x}:{frame.age:04x}:{frame.opcode:02x}:{frame.target:04x}",
+                "raw_packet": b2a(raw_packet) if raw_packet else None,
+                "decrypted_data": b2a(data),
+                "received_at": time.time(),
+            }
+
+        stats.frames_ignored += 1
+        self._logger.debug(
+            "[CASAMBI_INVOKE_IGNORED] packet=%s opcode=0x%02x origin=0x%04x target=0x%04x age=0x%04x flags=0x%04x payload=%s",
+            packet_seq,
+            frame.opcode,
+            frame.origin,
+            frame.target,
+            frame.age,
+            frame.flags,
+            b2a(frame.payload),
+        )
+        return None

CasambiBt/_unit.py

@@ -3,7 +3,7 @@ from binascii import b2a_hex as b2a
 from colorsys import hsv_to_rgb, rgb_to_hsv
 from dataclasses import dataclass
 from enum import Enum, unique
-from typing import Final
+from typing import Any, Final
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -112,6 +112,39 @@ class UnitState:
         self._xy: tuple[float, float] | None = None
         self._slider: int | None = None
         self._onoff: bool | None = None
+        # Last raw state bytes, as received from the network.
+        self._raw_state: bytes | None = None
+        # Unknown controls that we don't have semantic parsing for yet.
+        # Items are (offset_bits, length_bits, value_int).
+        self._unknown_controls: list[tuple[int, int, int]] = []
+
+    @property
+    def raw_state(self) -> bytes | None:
+        return self._raw_state
+
+    @property
+    def unknown_controls(self) -> list[tuple[int, int, int]]:
+        # Expose a copy so callers can't mutate internal tracking.
+        return list(self._unknown_controls)
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return a stable, JSON-friendly representation for diagnostics."""
+        return {
+            "dimmer": self.dimmer,
+            "vertical": self.vertical,
+            "rgb": self.rgb,
+            "white": self.white,
+            "temperature": self.temperature,
+            "colorsource": self.colorsource.name if self.colorsource is not None else None,
+            "xy": self.xy,
+            "slider": self.slider,
+            "onoff": self.onoff,
+            "raw_state_hex": b2a(self._raw_state).decode("ascii") if self._raw_state is not None else None,
+            "unknown_controls": [
+                {"offset": off, "length": length, "value": val}
+                for (off, length, val) in self._unknown_controls
+            ],
+        }
 
     def _check_range(
         self, value: int | float, min: int | float, max: int | float
@@ -429,6 +462,8 @@ class Unit:
         """
         if not self._state:
             self._state = UnitState()
+        self._state._raw_state = value
+        self._state._unknown_controls = []
 
         # TODO: Support for resolutions >8 byte?
         for c in self.unitType.controls:
@@ -500,6 +535,7 @@ class Unit:
                 _LOGGER.debug(
                     f"Value for unkown control type at {c.offset}: {cInt}. Unit type is {self.unitType.id}."
                 )
+                self._state._unknown_controls.append((c.offset, c.length, cInt))
 
         _LOGGER.debug(f"Parsed {b2a(value)} to {self.state.__repr__()}")
 

{casambi_bt_revamped-0.3.11.dist-info → casambi_bt_revamped-0.3.12.dev2.dist-info}/METADATA

@@ -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.12.dev2.dist-info/RECORD

@@ -0,0 +1,20 @@
+CasambiBt/__init__.py,sha256=TW445xSu5PV3TyMjJfwaA1JoWvQQ8LXhZgGdDTfWf3s,302
+CasambiBt/_cache.py,sha256=3bQil8vhSy4f4sf9JusMfEdQC7d3cJuva9qHhyKro-0,3808
+CasambiBt/_casambi.py,sha256=i-60A7zDblZwOVb4UfXz9EEwsbWEFPnrMvVkKMl6amY,34752
+CasambiBt/_client.py,sha256=z3AnTQrZMVLkQTXdyLOZyNkNonU3arMFtEHMxUF59Ig,31581
+CasambiBt/_constants.py,sha256=_AxkG7Btxl4VeS6mO7GJW5Kc9dFs3s9sDmtJ83ZEKNw,359
+CasambiBt/_discover.py,sha256=H7HpiFYIy9ELvmPXXd_ck-5O5invJf15dDIRk-vO5IE,1696
+CasambiBt/_encryption.py,sha256=CLcoOOrggQqhJbnr_emBnEnkizpWDvb_0yFnitq4_FM,3831
+CasambiBt/_invocation.py,sha256=fkG4R0Gv5_amFfD_P6DKuIEe3oKWZW0v8RSU8zDjPdI,2985
+CasambiBt/_keystore.py,sha256=Jdiq0zMPDmhfpheSojKY6sTUpmVrvX_qOyO7yCYd3kw,2788
+CasambiBt/_network.py,sha256=Gh0n3FEcOUHUMuBXALwcb3tws-AofpYLegKIquqtZl4,14665
+CasambiBt/_operation.py,sha256=Q5UccsrtNp_B_wWqwH_3eLFW_yF6A55FMmfUKDk2WrI,1059
+CasambiBt/_switch_events.py,sha256=S8OD0dBcw5T4J2C7qfmOQMnTJ7omIXRUYv4PqDOB87E,13137
+CasambiBt/_unit.py,sha256=KIpvUT_Wm-O2Lmb1JVnNO625-j5j7GqufmZzfTR-jW0,18587
+CasambiBt/errors.py,sha256=0JgDjaKlAKDes0poWzA8nrTUYQ8qdNfBb8dfaqqzCRA,1664
+CasambiBt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+casambi_bt_revamped-0.3.12.dev2.dist-info/licenses/LICENSE,sha256=TAIIitFxpxEDi6Iju7foW4TDQmWvC-IhLVLhl67jKmQ,11341
+casambi_bt_revamped-0.3.12.dev2.dist-info/METADATA,sha256=nMUsaWF7HLmwMjYQFq_uJM3N_CGyP7SPmUKaGjKWdQk,4907
+casambi_bt_revamped-0.3.12.dev2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+casambi_bt_revamped-0.3.12.dev2.dist-info/top_level.txt,sha256=uNbqLjtecFosoFzpGAC89-5icikWODKI8rOjbi8v_sA,10
+casambi_bt_revamped-0.3.12.dev2.dist-info/RECORD,,

casambi_bt_revamped-0.3.11.dist-info/RECORD

@@ -1,18 +0,0 @@
-CasambiBt/__init__.py,sha256=TW445xSu5PV3TyMjJfwaA1JoWvQQ8LXhZgGdDTfWf3s,302
-CasambiBt/_cache.py,sha256=3bQil8vhSy4f4sf9JusMfEdQC7d3cJuva9qHhyKro-0,3808
-CasambiBt/_casambi.py,sha256=AfyuzEU2ylJOGLmZ87Qft-aNXI_JK8Ng9Tfk4fWYOwo,34345
-CasambiBt/_client.py,sha256=cmRXPxURJpp8xQM-FJe2NBMtfFFC7NnWExTaN65LQ5c,32142
-CasambiBt/_constants.py,sha256=_AxkG7Btxl4VeS6mO7GJW5Kc9dFs3s9sDmtJ83ZEKNw,359
-CasambiBt/_discover.py,sha256=H7HpiFYIy9ELvmPXXd_ck-5O5invJf15dDIRk-vO5IE,1696
-CasambiBt/_encryption.py,sha256=CLcoOOrggQqhJbnr_emBnEnkizpWDvb_0yFnitq4_FM,3831
-CasambiBt/_keystore.py,sha256=Jdiq0zMPDmhfpheSojKY6sTUpmVrvX_qOyO7yCYd3kw,2788
-CasambiBt/_network.py,sha256=Gh0n3FEcOUHUMuBXALwcb3tws-AofpYLegKIquqtZl4,14665
-CasambiBt/_operation.py,sha256=Q5UccsrtNp_B_wWqwH_3eLFW_yF6A55FMmfUKDk2WrI,1059
-CasambiBt/_unit.py,sha256=KR_dvVhCH8WIPGJgZYHyAPVA6ru0KmMOL5NgkxYHIUQ,17042
-CasambiBt/errors.py,sha256=0JgDjaKlAKDes0poWzA8nrTUYQ8qdNfBb8dfaqqzCRA,1664
-CasambiBt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-casambi_bt_revamped-0.3.11.dist-info/licenses/LICENSE,sha256=TAIIitFxpxEDi6Iju7foW4TDQmWvC-IhLVLhl67jKmQ,11341
-casambi_bt_revamped-0.3.11.dist-info/METADATA,sha256=iZGwjYA0uCljUzih5kyGU63Fj-EZIE-acg7wE5fWHwM,3154
-casambi_bt_revamped-0.3.11.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-casambi_bt_revamped-0.3.11.dist-info/top_level.txt,sha256=uNbqLjtecFosoFzpGAC89-5icikWODKI8rOjbi8v_sA,10
-casambi_bt_revamped-0.3.11.dist-info/RECORD,,