PySwitchbot 0.76.0__tar.gz → 1.0.0__tar.gz

{pyswitchbot-0.76.0 → pyswitchbot-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySwitchbot
-Version: 0.76.0
+Version: 1.0.0
 Summary: A library to communicate with Switchbot
 Home-page: https://github.com/sblibs/pySwitchbot/
 Author: Daniel Hjelseth Hoyer

{pyswitchbot-0.76.0 → pyswitchbot-1.0.0}/PySwitchbot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySwitchbot
-Version: 0.76.0
+Version: 1.0.0
 Summary: A library to communicate with Switchbot
 Home-page: https://github.com/sblibs/pySwitchbot/
 Author: Daniel Hjelseth Hoyer

{pyswitchbot-0.76.0 → pyswitchbot-1.0.0}/PySwitchbot.egg-info/SOURCES.txt

@@ -75,6 +75,7 @@ switchbot/devices/keypad_vision.py
 switchbot/devices/light_strip.py
 switchbot/devices/lock.py
 switchbot/devices/meter.py
+switchbot/devices/meter_pro.py
 switchbot/devices/motion.py
 switchbot/devices/plug.py
 switchbot/devices/relay_switch.py
@@ -91,6 +92,7 @@ tests/test_ceiling_light.py
 tests/test_colormode_imports.py
 tests/test_curtain.py
 tests/test_device.py
+tests/test_discovery_callback.py
 tests/test_encrypted_device.py
 tests/test_evaporative_humidifier.py
 tests/test_fan.py
@@ -99,6 +101,7 @@ tests/test_hub2.py
 tests/test_hub3.py
 tests/test_keypad_vision.py
 tests/test_lock.py
+tests/test_meter_pro.py
 tests/test_relay_switch.py
 tests/test_roller_shade.py
 tests/test_smart_thermostat_radiator.py

{pyswitchbot-0.76.0 → pyswitchbot-1.0.0}/setup.py

@@ -20,7 +20,7 @@ setup(
         "cryptography>=39.0.0",
         "pyOpenSSL>=23.0.0",
     ],
-    version="0.76.0",
+    version="1.0.0",
     description="A library to communicate with Switchbot",
     long_description=long_description,
     long_description_content_type="text/markdown",

{pyswitchbot-0.76.0 → pyswitchbot-1.0.0}/switchbot/__init__.py

@@ -52,6 +52,7 @@ from .devices.light_strip import (
     SwitchbotStripLight3,
 )
 from .devices.lock import SwitchbotLock
+from .devices.meter_pro import SwitchbotMeterProCO2
 from .devices.plug import SwitchbotPlugMini
 from .devices.relay_switch import (
     SwitchbotGarageDoorOpener,
@@ -101,6 +102,7 @@ __all__ = [
     "SwitchbotKeypadVision",
     "SwitchbotLightStrip",
     "SwitchbotLock",
+    "SwitchbotMeterProCO2",
     "SwitchbotModel",
     "SwitchbotModel",
     "SwitchbotOperationError",

{pyswitchbot-0.76.0 → pyswitchbot-1.0.0}/switchbot/devices/device.py

@@ -8,6 +8,7 @@ import logging
 import time
 from collections.abc import Callable
 from dataclasses import replace
+from enum import IntEnum
 from typing import Any, TypeVar, cast
 from uuid import UUID
 
@@ -142,6 +143,21 @@ class SwitchbotOperationError(Exception):
     """Raised when an operation fails."""
 
 
+class AESMode(IntEnum):
+    """Supported AES modes for encrypted devices."""
+
+    CTR = 0
+    GCM = 1
+
+
+def _normalize_encryption_mode(mode: int) -> AESMode:
+    """Normalize encryption mode to AESMode (only 0/1 allowed)."""
+    try:
+        return AESMode(mode)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"Unsupported encryption mode: {mode}") from exc
+
+
 def _sb_uuid(comms_type: str = "service") -> UUID | str:
     """Return Switchbot UUID."""
     _uuid = {"tx": "002", "rx": "003", "service": "d00"}
@@ -982,7 +998,8 @@ class SwitchbotEncryptedDevice(SwitchbotDevice):
         self._key_id = key_id
         self._encryption_key = bytearray.fromhex(encryption_key)
         self._iv: bytes | None = None
-        self._cipher: bytes | None = None
+        self._cipher: Cipher | None = None
+        self._encryption_mode: AESMode | None = None
         super().__init__(device, None, interface, **kwargs)
         self._model = model
 
@@ -1081,9 +1098,8 @@ class SwitchbotEncryptedDevice(SwitchbotDevice):
                 _LOGGER.error("Failed to initialize encryption")
                 return None
 
-            encrypted = (
-                key[:2] + self._key_id + self._iv[0:2].hex() + self._encrypt(key[2:])
-            )
+            ciphertext_hex, header_hex = self._encrypt(key[2:])
+            encrypted = key[:2] + self._key_id + header_hex + ciphertext_hex
             command = bytearray.fromhex(self._commandkey(encrypted))
             _LOGGER.debug("%s: Scheduling command %s", self.name, command.hex())
             max_attempts = retry + 1
@@ -1093,7 +1109,10 @@ class SwitchbotEncryptedDevice(SwitchbotDevice):
             )
             if result is None:
                 return None
-            return result[:1] + self._decrypt(result[4:])
+            decrypted = self._decrypt(result[4:])
+            if self._encryption_mode == AESMode.GCM:
+                self._increment_gcm_iv()
+            return result[:1] + decrypted
 
     async def _ensure_encryption_initialized(self) -> bool:
         """Ensure encryption is initialized, must be called with operation lock held."""
@@ -1117,34 +1136,71 @@ class SwitchbotEncryptedDevice(SwitchbotDevice):
             return False
 
         if ok := self._check_command_result(result, 0, {1}):
-            self._iv = result[4:]
+            _LOGGER.debug("%s: Encryption init response: %s", self.name, result.hex())
+            mode_byte = result[2] if len(result) > 2 else None
+            self._resolve_encryption_mode(mode_byte)
+            if self._encryption_mode == AESMode.GCM:
+                iv = result[4:-4]
+                expected_iv_len = 12
+            else:
+                iv = result[4:]
+                expected_iv_len = 16
+            if len(iv) != expected_iv_len:
+                _LOGGER.error(
+                    "%s: Invalid IV length %d for mode %s (expected %d)",
+                    self.name,
+                    len(iv),
+                    self._encryption_mode.name,
+                    expected_iv_len,
+                )
+                return False
+            self._iv = iv
             self._cipher = None  # Reset cipher when IV changes
             _LOGGER.debug("%s: Encryption initialized successfully", self.name)
 
         return ok
 
     async def _execute_disconnect(self) -> None:
+        """
+        Reset encryption state and disconnect.
+
+        Clears IV, cipher, and encryption mode so they can be
+        re-detected on the next connection (e.g., after firmware update).
+        """
         async with self._connect_lock:
             self._iv = None
             self._cipher = None
+            self._encryption_mode = None
             await self._execute_disconnect_with_lock()
 
     def _get_cipher(self) -> Cipher:
         if self._cipher is None:
             if self._iv is None:
                 raise RuntimeError("Cannot create cipher: IV is None")
-            self._cipher = Cipher(
-                algorithms.AES128(self._encryption_key), modes.CTR(self._iv)
-            )
+            if self._encryption_mode == AESMode.GCM:
+                self._cipher = Cipher(
+                    algorithms.AES128(self._encryption_key), modes.GCM(self._iv)
+                )
+            else:
+                self._cipher = Cipher(
+                    algorithms.AES128(self._encryption_key), modes.CTR(self._iv)
+                )
         return self._cipher
 
-    def _encrypt(self, data: str) -> str:
+    def _encrypt(self, data: str) -> tuple[str, str]:
         if len(data) == 0:
-            return ""
+            return "", ""
         if self._iv is None:
             raise RuntimeError("Cannot encrypt: IV is None")
         encryptor = self._get_cipher().encryptor()
-        return (encryptor.update(bytearray.fromhex(data)) + encryptor.finalize()).hex()
+        ciphertext = encryptor.update(bytearray.fromhex(data)) + encryptor.finalize()
+        if self._encryption_mode == AESMode.GCM:
+            header_hex = encryptor.tag[:2].hex()
+            # GCM cipher is single-use; clear it so _get_cipher() creates a fresh one
+            self._cipher = None
+        else:
+            header_hex = self._iv[0:2].hex()
+        return ciphertext.hex(), header_hex
 
     def _decrypt(self, data: bytearray) -> bytes:
         if len(data) == 0:
@@ -1157,9 +1213,40 @@ class SwitchbotEncryptedDevice(SwitchbotDevice):
                 )
                 return b""
             raise RuntimeError("Cannot decrypt: IV is None")
+        if self._encryption_mode == AESMode.GCM:
+            # Firmware only returns a 2-byte partial tag which can't be used for
+            # verification. Use a dummy 16-byte tag and skip finalize() since
+            # authentication is handled by the firmware.
+            decryptor = Cipher(
+                algorithms.AES128(self._encryption_key),
+                modes.GCM(self._iv, b"\x00" * 16),
+            ).decryptor()
+            return decryptor.update(data)
         decryptor = self._get_cipher().decryptor()
         return decryptor.update(data) + decryptor.finalize()
 
+    def _increment_gcm_iv(self) -> None:
+        """Increment GCM IV by 1 (big-endian). Called after each encrypted command."""
+        if self._iv is None:
+            raise RuntimeError("Cannot increment GCM IV: IV is None")
+        if len(self._iv) != 12:
+            raise RuntimeError("Cannot increment GCM IV: IV length is not 12 bytes")
+        iv_int = int.from_bytes(self._iv, "big") + 1
+        self._iv = iv_int.to_bytes(12, "big")
+        self._cipher = None
+
+    def _resolve_encryption_mode(self, mode_byte: int | None) -> None:
+        """Resolve encryption mode from device response when available."""
+        if mode_byte is None:
+            raise ValueError("Encryption mode byte is missing")
+        detected_mode = _normalize_encryption_mode(mode_byte)
+        if self._encryption_mode is not None and self._encryption_mode != detected_mode:
+            raise ValueError(
+                f"Conflicting encryption modes detected: {self._encryption_mode.name} vs {detected_mode.name}"
+            )
+        self._encryption_mode = detected_mode
+        _LOGGER.debug("%s: Detected encryption mode: %s", self.name, detected_mode.name)
+
 
 class SwitchbotDeviceOverrideStateDuringConnection(SwitchbotBaseDevice):
     """

pyswitchbot-1.0.0/switchbot/devices/meter_pro.py

@@ -0,0 +1,172 @@
+from typing import Any
+
+from ..helpers import parse_uint24_be
+from .device import SwitchbotDevice, SwitchbotOperationError
+
+COMMAND_SET_TIME_OFFSET = "570f680506"
+COMMAND_GET_TIME_OFFSET = "570f690506"
+MAX_TIME_OFFSET = (1 << 24) - 1
+
+COMMAND_GET_DEVICE_DATETIME = "570f6901"
+COMMAND_SET_DEVICE_DATETIME = "57000503"
+COMMAND_SET_DISPLAY_FORMAT = "570f680505"
+
+
+class SwitchbotMeterProCO2(SwitchbotDevice):
+    """API to control Switchbot Meter Pro CO2."""
+
+    async def get_time_offset(self) -> int:
+        """
+        Get the current display time offset from the device.
+
+        Returns:
+            int: The time offset in seconds. Max 24 bits.
+
+        """
+        # Response Format: 5 bytes, where
+        # - byte 0: "01" (success)
+        # - byte 1: "00" (plus offset) or "80" (minus offset)
+        # - bytes 2-4: int24, number of seconds to offset.
+        # Example response: 01-80-00-10-00 -> subtract 4096 seconds.
+        result = await self._send_command(COMMAND_GET_TIME_OFFSET)
+        result = self._validate_result("get_time_offset", result, min_length=5)
+
+        is_negative = bool(result[1] & 0b10000000)
+        offset = parse_uint24_be(result, 2)
+        return -offset if is_negative else offset
+
+    async def set_time_offset(self, offset_seconds: int) -> None:
+        """
+        Set the display time offset on the device. This is what happens when
+        you adjust display time in the Switchbot app. The displayed time is
+        calculated as the internal device time (usually comes from the factory
+        settings or set by the Switchbot app upon syncing) + offset. The offset
+        is provided in seconds and can be positive or negative.
+
+        Args:
+            offset_seconds (int): 2^24 maximum, can be negative.
+
+        """
+        abs_offset = abs(offset_seconds)
+        if abs_offset > MAX_TIME_OFFSET:
+            raise SwitchbotOperationError(
+                f"{self.name}: Requested to set_time_offset of {offset_seconds} seconds, allowed +-{MAX_TIME_OFFSET} max."
+            )
+
+        sign_byte = "80" if offset_seconds < 0 else "00"
+
+        # Example: 57-0f-68-05-06-80-00-10-00 -> subtract 4096 seconds.
+        payload = f"{COMMAND_SET_TIME_OFFSET}{sign_byte}{abs_offset:06x}"
+        result = await self._send_command(payload)
+        self._validate_result("set_time_offset", result)
+
+    async def get_datetime(self) -> dict[str, Any]:
+        """
+        Get the current device time and settings as it is displayed. Contains
+        a time offset, if any was applied (see set_time_offset).
+        Doesn't include the current time zone.
+
+        Returns:
+            dict: Dictionary containing:
+                - 12h_mode (bool): True if 12h mode, False if 24h mode.
+                - year (int)
+                - month (int)
+                - day (int)
+                - hour (int)
+                - minute (int)
+                - second (int)
+
+        """
+        # Response Format: 13 bytes, where
+        # - byte 0: "01" (success)
+        # - bytes 1-4: temperature, ignored here.
+        # - byte 5: time display format:
+        #   - "80" - 12h (am/pm)
+        #   - "00" - 24h
+        # - bytes 6-12: yyyy-MM-dd-hh-mm-ss
+        # Example: 01-e4-02-94-23-00-07-e9-0c-1e-08-37-01 contains
+        # "year 2025, 30 December, 08:55:01, displayed in 24h format".
+        result = await self._send_command(COMMAND_GET_DEVICE_DATETIME)
+        result = self._validate_result("get_datetime", result, min_length=13)
+        return {
+            # Whether the time is displayed in 12h(am/pm) or 24h mode.
+            "12h_mode": bool(result[5] & 0b10000000),
+            "year": (result[6] << 8) + result[7],
+            "month": result[8],
+            "day": result[9],
+            "hour": result[10],
+            "minute": result[11],
+            "second": result[12],
+        }
+
+    async def set_datetime(
+        self, timestamp: int, utc_offset_hours: int = 0, utc_offset_minutes: int = 0
+    ) -> None:
+        """
+        Set the device internal time and timezone. Similar to how the
+        Switchbot app does it upon syncing with the device.
+        Pay attention to calculating UTC offset hours and minutes, see
+        examples below.
+
+        Args:
+            timestamp (int): Unix timestamp in seconds.
+            utc_offset_hours (int): UTC offset in hours, floor()'ed,
+                within [-12; 14] range.
+                Examples: -5 for UTC-05:00, -6 for UTC-05:30,
+                5 for UTC+05:00, 5 for UTC+5:30.
+            utc_offset_minutes (int): UTC offset minutes component, always
+                positive, complements utc_offset_hours.
+                Examples: 45 for UTC+05:45, 15 for UTC-5:45.
+
+        """
+        if not (-12 <= utc_offset_hours <= 14):
+            raise SwitchbotOperationError(
+                f"{self.name}: utc_offset_hours must be between -12 and +14 inclusive, got {utc_offset_hours}"
+            )
+        if not (0 <= utc_offset_minutes < 60):
+            raise SwitchbotOperationError(
+                f"{self.name}: utc_offset_minutes must be between 0 and 59 inclusive, got {utc_offset_minutes}"
+            )
+
+        # The device doesn't automatically add offset minutes, it expects them
+        # to come as a part of the timestamp.
+        adjusted_timestamp = timestamp + utc_offset_minutes * 60
+
+        # The timezone is encoded as 1 byte, where 00 stands for UTC-12.
+        # TZ with minute offset gets floor()ed: 4:30 yields 4, -4:30 yields -5.
+        utc_byte = utc_offset_hours + 12
+
+        payload = (
+            f"{COMMAND_SET_DEVICE_DATETIME}{utc_byte:02x}"
+            f"{adjusted_timestamp:016x}{utc_offset_minutes:02x}"
+        )
+
+        result = await self._send_command(payload)
+        self._validate_result("set_datetime", result)
+
+    async def set_time_display_format(self, is_12h_mode: bool = False) -> None:
+        """
+        Set the time display format on the device: 12h(AM/PM) or 24h.
+
+        Args:
+            is_12h_mode (bool): True for 12h (AM/PM) mode, False for 24h mode.
+
+        """
+        mode_byte = "80" if is_12h_mode else "00"
+        payload = f"{COMMAND_SET_DISPLAY_FORMAT}{mode_byte}"
+        result = await self._send_command(payload)
+        self._validate_result("set_time_display_format", result)
+
+    def _validate_result(
+        self, op_name: str, result: bytes | None, min_length: int | None = None
+    ) -> bytes:
+        if not self._check_command_result(result, 0, {1}):
+            raise SwitchbotOperationError(
+                f"{self.name}: Unexpected response code for {op_name} (result={result.hex() if result else 'None'} rssi={self.rssi})"
+            )
+        assert result is not None
+        if min_length is not None and len(result) < min_length:
+            raise SwitchbotOperationError(
+                f"{self.name}: Unexpected response len for {op_name}, wanted at least {min_length} (result={result.hex() if result else 'None'} rssi={self.rssi})"
+            )
+        return result

{pyswitchbot-0.76.0 → pyswitchbot-1.0.0}/switchbot/discovery.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from collections.abc import Callable
 
 import bleak
 from bleak.backends.device import BLEDevice
@@ -20,10 +21,15 @@ CONNECT_LOCK = asyncio.Lock()
 class GetSwitchbotDevices:
     """Scan for all Switchbot devices and return by type."""
 
-    def __init__(self, interface: int = 0) -> None:
+    def __init__(
+        self,
+        interface: int = 0,
+        callback: Callable[[SwitchBotAdvertisement], None] | None = None,
+    ) -> None:
         """Get switchbot devices class constructor."""
         self._interface = f"hci{interface}"
         self._adv_data: dict[str, SwitchBotAdvertisement] = {}
+        self._callback = callback
 
     def detection_callback(
         self,
@@ -34,6 +40,11 @@ class GetSwitchbotDevices:
         discovery = parse_advertisement_data(device, advertisement_data)
         if discovery:
             self._adv_data[discovery.address] = discovery
+            if self._callback is not None:
+                try:
+                    self._callback(discovery)
+                except Exception:
+                    _LOGGER.exception("Error in discovery callback")
 
     async def discover(
         self, retry: int = DEFAULT_RETRY_COUNT, scan_timeout: int = DEFAULT_SCAN_TIMEOUT

pyswitchbot-1.0.0/tests/test_discovery_callback.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import switchbot.discovery as discovery_module
+from switchbot.discovery import GetSwitchbotDevices
+from switchbot.models import SwitchBotAdvertisement
+
+
+@dataclass
+class _FakeBleakScanner:
+    detection_callback: object
+    adapter: str
+
+    async def start(self) -> None:
+        # detection_callback signature: (device, advertisement_data)
+        self.detection_callback(object(), object())
+        self.detection_callback(object(), object())
+
+    async def stop(self) -> None:
+        return
+
+
+@pytest.mark.asyncio
+async def test_discover_fires_callback_for_each_packet(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls: list[SwitchBotAdvertisement] = []
+
+    # Patch parse_advertisement_data to return a different parsed object per invocation.
+    parsed: list[SwitchBotAdvertisement] = [
+        SwitchBotAdvertisement(
+            address="aa:bb:cc:dd:ee:ff",
+            data={"model": "c", "modelName": "Curtain", "data": {"position": 10}},
+            device=object(),
+            rssi=-80,
+            active=True,
+        ),
+        SwitchBotAdvertisement(
+            address="aa:bb:cc:dd:ee:ff",
+            data={"model": "c", "modelName": "Curtain", "data": {"position": 20}},
+            device=object(),
+            rssi=-70,
+            active=True,
+        ),
+    ]
+
+    def _fake_parse(_device: object, _advertisement_data: object):
+        return parsed.pop(0)
+
+    async def _fake_sleep(_seconds: float) -> None:
+        return
+
+    def _fake_bleak_scanner(*, detection_callback, adapter: str):
+        return _FakeBleakScanner(detection_callback=detection_callback, adapter=adapter)
+
+    monkeypatch.setattr(discovery_module, "parse_advertisement_data", _fake_parse)
+    monkeypatch.setattr(discovery_module.asyncio, "sleep", _fake_sleep)
+    monkeypatch.setattr(discovery_module.bleak, "BleakScanner", _fake_bleak_scanner)
+
+    scanner = GetSwitchbotDevices(callback=calls.append)
+    result = await scanner.discover(scan_timeout=60)
+
+    assert len(calls) == 2
+    assert calls[0].data["data"]["position"] == 10
+    assert calls[1].data["data"]["position"] == 20
+
+    # discover() retains backwards compatibility by still returning accumulated data.
+    assert result["aa:bb:cc:dd:ee:ff"].data["data"]["position"] == 20
+
+
+@pytest.mark.asyncio
+async def test_callback_exception_does_not_break_discovery(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    adv = SwitchBotAdvertisement(
+        address="11:22:33:44:55:66",
+        data={"model": "H", "modelName": "Bot", "data": {}},
+        device=object(),
+        rssi=-50,
+        active=True,
+    )
+
+    def _fake_parse(_device: object, _advertisement_data: object):
+        return adv
+
+    async def _fake_sleep(_seconds: float) -> None:
+        return
+
+    def _fake_bleak_scanner(*, detection_callback, adapter: str):
+        class _S:
+            async def start(self) -> None:
+                detection_callback(object(), object())
+
+            async def stop(self) -> None:
+                return
+
+        return _S()
+
+    def _boom(_adv: SwitchBotAdvertisement) -> None:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(discovery_module, "parse_advertisement_data", _fake_parse)
+    monkeypatch.setattr(discovery_module.asyncio, "sleep", _fake_sleep)
+    monkeypatch.setattr(discovery_module.bleak, "BleakScanner", _fake_bleak_scanner)
+
+    scanner = GetSwitchbotDevices(callback=_boom)
+    result = await scanner.discover(scan_timeout=1)
+
+    assert result["11:22:33:44:55:66"] == adv
+
+
+@pytest.mark.asyncio
+async def test_callback_exception_is_logged_and_suppressed(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """
+    Test that exceptions raised in the user callback are caught,
+    logged, and do not crash the discovery process.
+    """
+    mock_callback = MagicMock(side_effect=RuntimeError("Boom!"))
+
+    scanner = GetSwitchbotDevices(callback=mock_callback)
+
+    adv = SwitchBotAdvertisement(
+        address="aa:bb:cc:dd:ee:ff",
+        data={"model": "H", "modelName": "Bot", "data": {}},
+        device=MagicMock(),
+        rssi=-80,
+        active=True,
+    )
+
+    with patch("switchbot.discovery.parse_advertisement_data", return_value=adv):
+        scanner.detection_callback(MagicMock(), MagicMock())
+
+    mock_callback.assert_called_once()
+
+    assert "Error in discovery callback" in caplog.text
+    assert "Boom!" in caplog.text  # Exception message should also be in the log