casambi-bt-revamped 0.3.7.dev3__py3-none-any.whl → 0.3.12.dev15__py3-none-any.whl

CasambiBt/_constants.py

@@ -6,6 +6,22 @@ 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"
+CASA_CLASSIC_CA53_CHAR_UUID: Final = "0000ca53-0000-1000-8000-00805f9b34fb"
+
+# Classic "conformant" firmware maps the legacy CA5A/CA5x UUIDs onto the FE4D service.
+# Ground truth: casambi-android `t1.C1713d.e(UUID)` mapping:
+# - CA52 -> 0001 (same as CASA_AUTH_CHAR_UUID)
+# - CA51 -> 0002
+# - CA53 -> 0003
+CASA_CLASSIC_CONFORMANT_CA51_CHAR_UUID: Final = "c9ffde48-ca5a-0002-ab83-8f519b482f77"
+CASA_CLASSIC_CONFORMANT_CA53_CHAR_UUID: Final = "c9ffde48-ca5a-0003-ab83-8f519b482f77"
+
 
 @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

@@ -1,9 +1,10 @@
 import json
 import logging
 import pickle
+import random
 from dataclasses import dataclass
 from datetime import datetime, timedelta
-from typing import Final, cast
+from typing import Any, Final, cast
 
 import httpx
 from httpx import AsyncClient, RequestError
@@ -44,6 +45,11 @@ 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]] = {}
         self.units: list[Unit] = []
@@ -59,6 +65,50 @@ class Network:
 
         self._cache = cache
 
+        # Android sends "fb:<FCM_token>" — we have no push token, use empty string
+        # to match the field type without leaking platform info.
+        self._token: str = ""
+        # Android: "{flavor}/{version} {manufacturer}_{model}/{os_release}"
+        _app_version = random.choice((
+            "3.19.0", "3.18.2", "3.18.1", "3.18.0",
+            "3.17.4", "3.17.3", "3.17.2", "3.17.1", "3.17.0",
+            "3.16.5", "3.16.4", "3.16.3", "3.16.1", "3.16.0",
+            "3.15.3", "3.15.2", "3.15.1", "3.15.0",
+            "3.14.2", "3.14.1", "3.14.0",
+            "3.13.2", "3.13.1", "3.13.0",
+            "3.12.4", "3.12.3", "3.12.1", "3.12.0",
+            "3.11.2", "3.11.1",
+        ))
+        _device = random.choice((
+            # Samsung Galaxy S series
+            "samsung_SM-S928B/15",   # S24 Ultra
+            "samsung_SM-S926B/15",   # S24+
+            "samsung_SM-S921B/15",   # S24
+            "samsung_SM-S918B/14",   # S23 Ultra
+            "samsung_SM-S916B/14",   # S23+
+            "samsung_SM-S911B/14",   # S23
+            "samsung_SM-S908B/14",   # S22 Ultra
+            "samsung_SM-S906B/14",   # S22+
+            "samsung_SM-S901B/14",   # S22
+            "samsung_SM-G998B/13",   # S21 Ultra
+            "samsung_SM-G996B/13",   # S21+
+            "samsung_SM-G991B/13",   # S21
+            # Samsung Galaxy A series
+            "samsung_SM-A556B/14",   # A55
+            "samsung_SM-A546B/14",   # A54
+            "samsung_SM-A346B/14",   # A34
+            "samsung_SM-A536B/13",   # A53
+            # Google Pixel
+            "Google_Pixel 8 Pro/14",
+            "Google_Pixel 8/14",
+            "Google_Pixel 7 Pro/14",
+            "Google_Pixel 7/14",
+            # OnePlus
+            "OnePlus_IN2023/14",     # 12
+            "OnePlus_CPH2449/14",    # 11
+        ))
+        self._clientInfo: str = f"Casambi/{_app_version} {_device}"
+
     async def load(self) -> None:
         self._keystore = KeyStore(self._cache)
         await self._keystore.load()
@@ -145,6 +195,10 @@ class Network:
             return False
         return not self._session.expired()
 
+    def isManager(self) -> bool:
+        """Whether the current cloud session has manager privileges."""
+        return bool(self._session and self._session.manager)
+
     @property
     def keyStore(self) -> KeyStore:
         return self._keystore
@@ -153,6 +207,23 @@ 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
+
     async def logIn(self, password: str, forceOffline: bool = False) -> None:
         await self.getNetworkId(forceOffline)
 
@@ -164,7 +235,12 @@ class Network:
         getSessionUrl = f"https://api.casambi.com/network/{self._id}/session"
 
         res = await self._httpClient.post(
-            getSessionUrl, json={"password": password, "deviceName": DEVICE_NAME}
+            getSessionUrl,
+            json={
+                "token": self._token,
+                "password": password,
+                "deviceName": DEVICE_NAME,
+            },
         )
         if res.status_code == httpx.codes.OK:
             # Parse session
@@ -191,6 +267,7 @@ class Network:
             cachedNetworkPah = cachePath / f"{self._id}.json"
             if await cachedNetworkPah.exists():
                 network = json.loads(await cachedNetworkPah.read_bytes())
+                self._rawNetworkData = network
                 self._networkRevision = network["network"]["revision"]
                 self._logger.info(
                     f"Loaded cached network. Revision: {self._networkRevision}"
@@ -204,14 +281,16 @@ class Network:
             getNetworkUrl = f"https://api.casambi.com/network/{self._id}/"
 
             try:
+                payload = {
+                    "formatVersion": 1,
+                    "deviceName": DEVICE_NAME,
+                    "revision": self._networkRevision,
+                }
+
                 # **SECURITY**: Do not set session header for client! This could leak the session with external clients.
                 res = await self._httpClient.put(
                     getNetworkUrl,
-                    json={
-                        "formatVersion": 1,
-                        "deviceName": DEVICE_NAME,
-                        "revision": self._networkRevision,
-                    },
+                    json=payload,
                     headers={"X-Casambi-Session": self._session.session},  # type: ignore[union-attr]
                 )
 
@@ -224,22 +303,50 @@ class Network:
                     )
                     await self._cache.invalidateCache()
 
+                if res.status_code == httpx.codes.BAD_REQUEST:
+                    # Some backend variants may reject the minimal update payload.
+                    # Retry once with Android-like fields (token/clientInfo) for diagnostics/testing.
+                    self._logger.warning(
+                        "[CASAMBI_CLOUD_UPDATE_RETRY] status=400 retry_with_token_clientInfo=true body_prefix=%r",
+                        (res.text or "")[:200],
+                    )
+                    payload2: dict[str, Any] = dict(payload)
+                    payload2["token"] = self._token
+                    payload2["clientInfo"] = self._clientInfo
+                    res = await self._httpClient.put(
+                        getNetworkUrl,
+                        json=payload2,
+                        headers={"X-Casambi-Session": self._session.session},  # type: ignore[union-attr]
+                    )
+
                 if res.status_code != httpx.codes.OK:
-                    self._logger.error(f"Update failed: {res.status_code}\n{res.text}")
-                    raise NetworkUpdateError("Could not update network!")
-
-                self._logger.debug(f"Network: {res.text}")
-
-                updateResult = res.json()
-                if updateResult["status"] != "UPTODATE":
-                    self._networkRevision = updateResult["network"]["revision"]
-                    async with self._cache as cachePath:
-                        cachedNetworkPah = cachePath / f"{self._id}.json"
-                        await cachedNetworkPah.write_bytes(res.content)
-                    network = updateResult
-                    self._logger.info(
-                        f"Fetched updated network with revision {self._networkRevision}"
+                    body_prefix = (res.text or "")[:500]
+                    # If we have cached network data, do not fail setup; continue offline.
+                    # This is important for HA stability and for "cloud down / API changed" scenarios.
+                    have_cache = bool(self._networkRevision and self._networkRevision > 0 and self._rawNetworkData)
+                    self._logger.warning(
+                        "[CASAMBI_CLOUD_UPDATE_FAILED] status=%s cached_revision=%s continuing_offline=%s body_prefix=%r",
+                        res.status_code,
+                        self._networkRevision,
+                        have_cache,
+                        body_prefix,
                     )
+                    if not have_cache:
+                        raise NetworkUpdateError("Could not update network!")
+                else:
+                    self._logger.debug(f"Network: {res.text}")
+
+                    updateResult = res.json()
+                    if updateResult["status"] != "UPTODATE":
+                        self._networkRevision = updateResult["network"]["revision"]
+                        self._rawNetworkData = updateResult
+                        async with self._cache as cachePath:
+                            cachedNetworkPah = cachePath / f"{self._id}.json"
+                            await cachedNetworkPah.write_bytes(res.content)
+                        network = updateResult
+                        self._logger.info(
+                            f"Fetched updated network with revision {self._networkRevision}"
+                        )
             except RequestError as err:
                 if self._networkRevision == 0:
                     raise NetworkUpdateError from err
@@ -256,12 +363,45 @@ 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)
+            if not (self._classicVisitorKey or self._classicManagerKey):
+                # Android still sends Classic frames even when keys are null (signature bytes remain zeros).
+                # We need this as a loud hint for testers when Classic control doesn't work yet.
+                self._logger.warning(
+                    "[CASAMBI_CLASSIC_KEYS_MISSING] visitorKey=false managerKey=false"
+                )
+            else:
+                self._logger.info(
+                    "Classic keys present: visitor=%s manager=%s",
+                    bool(self._classicVisitorKey),
+                    bool(self._classicManagerKey),
+                )
 
         # Parse units
         self.units = []
         units = network["network"]["units"]
+        units_with_security_key = 0
         for u in units:
             uType = await self._fetchUnitInfo(u["type"])
             if uType is None:
@@ -269,6 +409,23 @@ class Network:
                     "Failed to fetch type for unit %i. Skipping.", u["type"]
                 )
                 continue
+
+            security_key: bytes | None = None
+            sec_hex = u.get("securityKey")
+            if isinstance(sec_hex, str):
+                sec_hex = sec_hex.strip()
+                if sec_hex:
+                    try:
+                        security_key = bytes.fromhex(sec_hex)
+                    except ValueError:
+                        self._logger.debug(
+                            "Invalid unit securityKey hex for unit %s (len=%d).",
+                            u.get("deviceID"),
+                            len(sec_hex),
+                        )
+            if security_key is not None:
+                units_with_security_key += 1
+
             uObj = Unit(
                 u["type"],
                 u["deviceID"],
@@ -277,9 +434,24 @@ class Network:
                 u["name"],
                 str(u["firmware"]),
                 uType,
+                securityKey=security_key,
             )
             self.units.append(uObj)
 
+        # One compact profile line to help interpret mixed/legacy networks from tester logs.
+        # Keep EVO networks at INFO to avoid noisy HA warnings; elevate legacy (<10) to WARNING.
+        level = logging.WARNING if self._protocolVersion < 10 else logging.INFO
+        self._logger.log(
+            level,
+            "[CASAMBI_NETWORK_PROFILE] uuid=%s id=%s protocolVersion=%s units=%d units_with_securityKey=%d keyStore=%s",
+            self._uuid,
+            self._id,
+            self._protocolVersion,
+            len(self.units),
+            units_with_security_key,
+            "keyStore" in network["network"],
+        )
+
         # Parse cells
         self.groups = []
         cells = network["network"]["grid"]["cells"]

CasambiBt/_operation.py

@@ -11,6 +11,9 @@ class OpCode(IntEnum):
     SetWhite = 5
     SetColor = 7
     SetSlider = 12
+    SetParameter = 26
+    AcquireSwitchSession = 42
+    ExtPacketSend = 43
     SetState = 48
     SetColorXY = 54
 
@@ -20,11 +23,19 @@ class OperationsContext:
         self.origin: int = 1
         self.lifetime: int = 5
 
-    def prepareOperation(self, op: OpCode, target: int, payload: bytes) -> bytes:
+    def prepareOperation(
+        self,
+        op: OpCode,
+        target: int,
+        payload: bytes,
+        *,
+        lifetime: int | None = None,
+    ) -> bytes:
         if len(payload) > 63:
             raise ValueError("Payload too long")
 
-        flags = (self.lifetime & 15) << 11 | len(payload)
+        lt = self.lifetime if lifetime is None else int(lifetime)
+        flags = (lt & 15) << 11 | len(payload)
 
         # Ensure that origin can't overflow.
         # TODO: Check that unsigned is actually correct here.