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

CasambiBt/_constants.py

@@ -6,6 +6,13 @@ DEVICE_NAME: Final = "Casambi BT Python"
 CASA_UUID: Final = "0000fe4d-0000-1000-8000-00805f9b34fb"
 CASA_AUTH_CHAR_UUID: Final = "c9ffde48-ca5a-0001-ab83-8f519b482f77"
 
+# Classic firmware/protocol uses different GATT characteristics (see casambi-android t1.C1713d):
+# - 0000ca51-...: connection hash (first 8 bytes are used as CMAC input prefix)
+# - 0000ca52-...: signed data channel (write + notify)
+CASA_UUID_CLASSIC: Final = "0000ca5a-0000-1000-8000-00805f9b34fb"
+CASA_CLASSIC_HASH_CHAR_UUID: Final = "0000ca51-0000-1000-8000-00805f9b34fb"
+CASA_CLASSIC_DATA_CHAR_UUID: Final = "0000ca52-0000-1000-8000-00805f9b34fb"
+
 
 @unique
 class ConnectionState(IntEnum):

CasambiBt/_discover.py

@@ -5,7 +5,7 @@ from bleak import BleakScanner
 from bleak.backends.client import BLEDevice
 from bleak.exc import BleakDBusError, BleakError
 
-from ._constants import CASA_UUID
+from ._constants import CASA_UUID, CASA_UUID_CLASSIC
 from .errors import BluetoothError
 
 _LOGGER = logging.getLogger(__name__)
@@ -39,7 +39,8 @@ async def discover() -> list[BLEDevice]:
     discovered = []
     for _, (d, advertisement) in devices_and_advertisements.items():
         if 963 in advertisement.manufacturer_data:
-            if CASA_UUID in advertisement.service_uuids:
+            # Evolution networks advertise FE4D; Classic networks advertise CA5A.
+            if CASA_UUID in advertisement.service_uuids or CASA_UUID_CLASSIC in advertisement.service_uuids:
                 _LOGGER.debug(f"Discovered network at {d.address}")
                 discovered.append(d)
 

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/_network.py

@@ -44,6 +44,10 @@ class Network:
         self._networkName: str | None = None
         self._networkRevision: int | None = None
         self._protocolVersion: int = -1
+        # Classic networks do not have a `keyStore`; instead they expose visitor/manager keys.
+        # Ground truth: casambi-android `D1.Z0` exports `visitorKey`/`managerKey`.
+        self._classicVisitorKey: bytes | None = None
+        self._classicManagerKey: bytes | None = None
         self._rawNetworkData: dict | None = None
 
         self._unitTypes: dict[int, tuple[UnitType | None, datetime]] = {}
@@ -154,6 +158,19 @@ class Network:
     def protocolVersion(self) -> int:
         return self._protocolVersion
 
+    def classicVisitorKey(self) -> bytes | None:
+        return self._classicVisitorKey
+
+    def classicManagerKey(self) -> bytes | None:
+        return self._classicManagerKey
+
+    def classicBestKey(self) -> bytes | None:
+        # Prefer manager key if present, otherwise visitor key.
+        return self._classicManagerKey or self._classicVisitorKey
+
+    def hasClassicKeys(self) -> bool:
+        return bool(self._classicVisitorKey or self._classicManagerKey)
+
     @property
     def rawNetworkData(self) -> dict | None:
         return self._rawNetworkData
@@ -263,8 +280,33 @@ class Network:
             keys = network["network"]["keyStore"]["keys"]
             for k in keys:
                 await self._keystore.addKey(k)
-
-        # TODO: Parse managerKey and visitorKey for classic networks.
+            # Evolution network: classic keys not used
+            self._classicVisitorKey = None
+            self._classicManagerKey = None
+        else:
+            # Classic network: parse visitorKey / managerKey (hex strings).
+            # Ground truth: casambi-android `D1.Z0` exports these fields.
+            visitor_hex = network["network"].get("visitorKey")
+            manager_hex = network["network"].get("managerKey")
+
+            def _parse_hex_key(v: object) -> bytes | None:
+                if not isinstance(v, str):
+                    return None
+                v = v.strip()
+                if not v:
+                    return None
+                try:
+                    return bytes.fromhex(v)
+                except ValueError:
+                    return None
+
+            self._classicVisitorKey = _parse_hex_key(visitor_hex)
+            self._classicManagerKey = _parse_hex_key(manager_hex)
+            self._logger.info(
+                "Classic keys present: visitor=%s manager=%s",
+                bool(self._classicVisitorKey),
+                bool(self._classicManagerKey),
+            )
 
         # Parse units
         self.units = []

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__()}")
 

CasambiBt/errors.py

@@ -69,3 +69,15 @@ class UnsupportedProtocolVersion(CasambiBtError):
     """Exception that is raised when the network has an unsupported version."""
 
     pass
+
+
+class ClassicKeysMissingError(ProtocolError):
+    """Classic network is missing visitorKey/managerKey required for signing packets."""
+
+    pass
+
+
+class ClassicHandshakeError(ProtocolError):
+    """Classic network handshake/initialization failed (e.g. connection hash unavailable)."""
+
+    pass