PySwitchbot 0.76.0__tar.gz → 1.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySwitchbot
-Version: 0.76.0
+Version: 1.1.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.1.0}/PySwitchbot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySwitchbot
-Version: 0.76.0
+Version: 1.1.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.1.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.1.0}/pyproject.toml

@@ -25,7 +25,6 @@ ignore = [
     "S110", # `try`-`except`-`pass` detected, consider logging the exception
     "D106", # Missing docstring in public nested class
     "UP007", # typer needs Optional syntax
-    "UP038", # Use `X | Y` in `isinstance` is slower
     "S603", #  check for execution of untrusted input
     "S105", # possible hard coded creds
     "TID252", # not for this lib

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

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

{pyswitchbot-0.76.0 → pyswitchbot-1.1.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.1.0}/switchbot/adv_parser.py

@@ -755,6 +755,42 @@ SUPPORTED_TYPES: dict[str | bytes, SwitchbotSupportedType] = {
         "func": process_keypad_vision_pro,
         "manufacturer_id": 2409,
     },
+    b"\x00\x11\x69\x09": {
+        "modelName": SwitchbotModel.LOCK_VISION_PRO,
+        "modelFriendlyName": "Lock Vision Pro",
+        "func": process_lock2,
+        "manufacturer_id": 2409,
+    },
+    b"\x01\x11\x69\x09": {
+        "modelName": SwitchbotModel.LOCK_VISION_PRO,
+        "modelFriendlyName": "Lock Vision Pro",
+        "func": process_lock2,
+        "manufacturer_id": 2409,
+    },
+    b"\x00\x11\x69\x08": {
+        "modelName": SwitchbotModel.LOCK_VISION,
+        "modelFriendlyName": "Lock Vision",
+        "func": process_locklite,
+        "manufacturer_id": 2409,
+    },
+    b"\x01\x11\x69\x08": {
+        "modelName": SwitchbotModel.LOCK_VISION,
+        "modelFriendlyName": "Lock Vision",
+        "func": process_locklite,
+        "manufacturer_id": 2409,
+    },
+    b"\x00\x10\xff\x90": {
+        "modelName": SwitchbotModel.LOCK_PRO_WIFI,
+        "modelFriendlyName": "Lock Pro Wifi",
+        "func": process_wolock_pro,
+        "manufacturer_id": 2409,
+    },
+    b"\x01\x10\xff\x90": {
+        "modelName": SwitchbotModel.LOCK_PRO_WIFI,
+        "modelFriendlyName": "Lock Pro Wifi",
+        "func": process_wolock_pro,
+        "manufacturer_id": 2409,
+    },
 }
 
 _SWITCHBOT_MODEL_TO_CHAR: defaultdict[SwitchbotModel, list[str | bytes]] = defaultdict(

{pyswitchbot-0.76.0 → pyswitchbot-1.1.0}/switchbot/const/__init__.py

@@ -105,6 +105,9 @@ class SwitchbotModel(StrEnum):
     ART_FRAME = "Art Frame"
     KEYPAD_VISION = "Keypad Vision"
     KEYPAD_VISION_PRO = "Keypad Vision Pro"
+    LOCK_VISION_PRO = "Lock Vision Pro"
+    LOCK_VISION = "Lock Vision"
+    LOCK_PRO_WIFI = "Lock Pro Wifi"
 
 
 __all__ = [

{pyswitchbot-0.76.0 → pyswitchbot-1.1.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
 
@@ -105,6 +106,9 @@ API_MODEL_TO_ENUM: dict[str, SwitchbotModel] = {
     "W1128000": SwitchbotModel.SMART_THERMOSTAT_RADIATOR,
     "W1111000": SwitchbotModel.CLIMATE_PANEL,
     "W1130000": SwitchbotModel.ART_FRAME,
+    "W1141001": SwitchbotModel.LOCK_VISION_PRO,
+    "W1141000": SwitchbotModel.LOCK_VISION,
+    "W1114000": SwitchbotModel.LOCK_PRO_WIFI,
 }
 
 REQ_HEADER = "570f"
@@ -142,6 +146,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 +1001,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 +1101,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 +1112,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 +1139,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 +1216,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-0.76.0 → pyswitchbot-1.1.0}/switchbot/devices/lock.py

@@ -18,30 +18,45 @@ COMMAND_LOCK_INFO = {
     SwitchbotModel.LOCK_LITE: f"{COMMAND_HEADER}0f4f8101",
     SwitchbotModel.LOCK_PRO: f"{COMMAND_HEADER}0f4f8104",
     SwitchbotModel.LOCK_ULTRA: f"{COMMAND_HEADER}0f4f8107",
+    SwitchbotModel.LOCK_VISION_PRO: f"{COMMAND_HEADER}0f4f8102",
+    SwitchbotModel.LOCK_VISION: f"{COMMAND_HEADER}0f4f8102",
+    SwitchbotModel.LOCK_PRO_WIFI: f"{COMMAND_HEADER}0f4f810a",
 }
 COMMAND_UNLOCK = {
     SwitchbotModel.LOCK: f"{COMMAND_HEADER}0f4e01011080",
     SwitchbotModel.LOCK_LITE: f"{COMMAND_HEADER}0f4e01011080",
     SwitchbotModel.LOCK_PRO: f"{COMMAND_HEADER}0f4e0101000080",
     SwitchbotModel.LOCK_ULTRA: f"{COMMAND_HEADER}0f4e0101000080",
+    SwitchbotModel.LOCK_VISION_PRO: f"{COMMAND_HEADER}0f4e0101000080",
+    SwitchbotModel.LOCK_VISION: f"{COMMAND_HEADER}0f4e0101000080",
+    SwitchbotModel.LOCK_PRO_WIFI: f"{COMMAND_HEADER}0f4e0101000080",
 }
 COMMAND_UNLOCK_WITHOUT_UNLATCH = {
     SwitchbotModel.LOCK: f"{COMMAND_HEADER}0f4e010110a0",
     SwitchbotModel.LOCK_LITE: f"{COMMAND_HEADER}0f4e010110a0",
     SwitchbotModel.LOCK_PRO: f"{COMMAND_HEADER}0f4e01010000a0",
     SwitchbotModel.LOCK_ULTRA: f"{COMMAND_HEADER}0f4e01010000a0",
+    SwitchbotModel.LOCK_VISION_PRO: f"{COMMAND_HEADER}0f4e01010000a0",
+    SwitchbotModel.LOCK_VISION: f"{COMMAND_HEADER}0f4e01010000a0",
+    SwitchbotModel.LOCK_PRO_WIFI: f"{COMMAND_HEADER}0f4e01010000a0",
 }
 COMMAND_LOCK = {
     SwitchbotModel.LOCK: f"{COMMAND_HEADER}0f4e01011000",
     SwitchbotModel.LOCK_LITE: f"{COMMAND_HEADER}0f4e01011000",
     SwitchbotModel.LOCK_PRO: f"{COMMAND_HEADER}0f4e0101000000",
     SwitchbotModel.LOCK_ULTRA: f"{COMMAND_HEADER}0f4e0101000000",
+    SwitchbotModel.LOCK_VISION_PRO: f"{COMMAND_HEADER}0f4e0101000000",
+    SwitchbotModel.LOCK_VISION: f"{COMMAND_HEADER}0f4e0101000000",
+    SwitchbotModel.LOCK_PRO_WIFI: f"{COMMAND_HEADER}0f4e0101000000",
 }
 COMMAND_ENABLE_NOTIFICATIONS = {
     SwitchbotModel.LOCK: f"{COMMAND_HEADER}0e01001e00008101",
     SwitchbotModel.LOCK_LITE: f"{COMMAND_HEADER}0e01001e00008101",
     SwitchbotModel.LOCK_PRO: f"{COMMAND_HEADER}0e01001e00008104",
     SwitchbotModel.LOCK_ULTRA: f"{COMMAND_HEADER}0e01001e00008107",
+    SwitchbotModel.LOCK_VISION_PRO: f"{COMMAND_HEADER}0e01001e00008102",
+    SwitchbotModel.LOCK_VISION: f"{COMMAND_HEADER}0e01001e00008102",
+    SwitchbotModel.LOCK_PRO_WIFI: f"{COMMAND_HEADER}0e01001e0000810a",
 }
 COMMAND_DISABLE_NOTIFICATIONS = f"{COMMAND_HEADER}0e00"
 
@@ -74,6 +89,9 @@ class SwitchbotLock(SwitchbotSequenceDevice, SwitchbotEncryptedDevice):
             SwitchbotModel.LOCK_PRO,
             SwitchbotModel.LOCK_LITE,
             SwitchbotModel.LOCK_ULTRA,
+            SwitchbotModel.LOCK_VISION_PRO,
+            SwitchbotModel.LOCK_VISION,
+            SwitchbotModel.LOCK_PRO_WIFI,
         ):
             raise ValueError("initializing SwitchbotLock with a non-lock model")
         self._notifications_enabled: bool = False
@@ -236,7 +254,7 @@ class SwitchbotLock(SwitchbotSequenceDevice, SwitchbotEncryptedDevice):
 
     @staticmethod
     def _parse_lock_data(data: bytes, model: SwitchbotModel) -> dict[str, Any]:
-        if model == SwitchbotModel.LOCK:
+        if model in {SwitchbotModel.LOCK, SwitchbotModel.LOCK_VISION_PRO}:
             return {
                 "calibration": bool(data[0] & 0b10000000),
                 "status": LockStatus((data[0] & 0b01110000) >> 4),
@@ -244,7 +262,7 @@ class SwitchbotLock(SwitchbotSequenceDevice, SwitchbotEncryptedDevice):
                 "unclosed_alarm": bool(data[1] & 0b00100000),
                 "unlocked_alarm": bool(data[1] & 0b00010000),
             }
-        if model == SwitchbotModel.LOCK_LITE:
+        if model in {SwitchbotModel.LOCK_LITE, SwitchbotModel.LOCK_VISION}:
             return {
                 "calibration": bool(data[0] & 0b10000000),
                 "status": LockStatus((data[0] & 0b01110000) >> 4),

pyswitchbot-1.1.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.1.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.1.0/switchbot/enum.py

@@ -0,0 +1,7 @@
+"""Enum backports from standard lib."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+__all__ = ["StrEnum"]