python-roborock 4.0.1__tar.gz → 4.1.0__tar.gz

{python_roborock-4.0.1 → python_roborock-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 4.0.1
+Version: 4.1.0
 Summary: A package to control Roborock vacuums.
 Project-URL: Repository, https://github.com/humbertogontijo/python-roborock
 Project-URL: Documentation, https://python-roborock.readthedocs.io/

{python_roborock-4.0.1 → python_roborock-4.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "4.0.1"
+version = "4.1.0"
 description = "A package to control Roborock vacuums."
 authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
 requires-python = ">=3.11, <4"

{python_roborock-4.0.1 → python_roborock-4.1.0}/roborock/data/code_mappings.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 from collections import namedtuple
 from enum import Enum, IntEnum, StrEnum
+from typing import Self
 
 _LOGGER = logging.getLogger(__name__)
 completed_warnings = set()
@@ -55,8 +56,9 @@ class RoborockModeEnum(StrEnum):
     """A custom StrEnum that also stores an integer code for each member."""
 
     code: int
+    """The integer code associated with the enum member."""
 
-    def __new__(cls, value: str, code: int) -> RoborockModeEnum:
+    def __new__(cls, value: str, code: int) -> Self:
         """Creates a new enum member."""
         member = str.__new__(cls, value)
         member._value_ = value
@@ -64,14 +66,25 @@ class RoborockModeEnum(StrEnum):
         return member
 
     @classmethod
-    def from_code(cls, code: int) -> RoborockModeEnum:
+    def from_code(cls, code: int) -> Self:
         for member in cls:
             if member.code == code:
                 return member
-        raise ValueError(f"{code} is not a valid code for {cls.__name__}")
+        message = f"{code} is not a valid code for {cls.__name__}"
+        if message not in completed_warnings:
+            completed_warnings.add(message)
+            _LOGGER.warning(message)
+        raise ValueError(message)
 
     @classmethod
-    def from_value(cls, value: str) -> RoborockModeEnum:
+    def from_code_optional(cls, code: int) -> RoborockModeEnum | None:
+        try:
+            return cls.from_code(code)
+        except ValueError:
+            return None
+
+    @classmethod
+    def from_value(cls, value: str) -> Self:
         """Find enum member by string value (case-insensitive)."""
         for member in cls:
             if member.value.lower() == value.lower():
@@ -79,7 +92,7 @@ class RoborockModeEnum(StrEnum):
         raise ValueError(f"{value} is not a valid value for {cls.__name__}")
 
     @classmethod
-    def from_name(cls, name: str) -> RoborockModeEnum:
+    def from_name(cls, name: str) -> Self:
         """Find enum member by name (case-insensitive)."""
         for member in cls:
             if member.name.lower() == name.lower():

{python_roborock-4.0.1 → python_roborock-4.1.0}/roborock/devices/device_manager.py

@@ -186,6 +186,7 @@ async def create_device_manager(
     session: aiohttp.ClientSession | None = None,
     ready_callback: DeviceReadyCallback | None = None,
     mqtt_session_unauthorized_hook: SessionUnauthorizedHook | None = None,
+    prefer_cache: bool = True,
 ) -> DeviceManager:
     """Convenience function to create and initialize a DeviceManager.
 
@@ -198,6 +199,7 @@ async def create_device_manager(
         mqtt_session_unauthorized_hook: Optional hook for MQTT session unauthorized
           events which may indicate rate limiting or revoked credentials. The
           caller may use this to refresh authentication tokens as needed.
+        prefer_cache: Whether to prefer cached device data over always fetching it from the API.
 
     Returns:
         An initialized DeviceManager with discovered devices.
@@ -259,5 +261,5 @@ async def create_device_manager(
         return dev
 
     manager = DeviceManager(web_api, device_creator, mqtt_session=mqtt_session, cache=cache, diagnostics=diagnostics)
-    await manager.discover_devices()
+    await manager.discover_devices(prefer_cache)
     return manager

python_roborock-4.1.0/roborock/protocols/b01_q10_protocol.py

@@ -0,0 +1,88 @@
+"""Roborock B01 Protocol encoding and decoding."""
+
+import json
+import logging
+from typing import Any
+
+from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+from roborock.exceptions import RoborockException
+from roborock.roborock_message import (
+    RoborockMessage,
+    RoborockMessageProtocol,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+B01_VERSION = b"B01"
+ParamsType = list | dict | int | None
+
+
+def encode_mqtt_payload(command: B01_Q10_DP, params: ParamsType) -> RoborockMessage:
+    """Encode payload for B01 Q10 commands over MQTT.
+
+    This does not perform any special encoding for the command parameters and expects
+    them to already be in a request specific format.
+    """
+    dps_data = {
+        "dps": {
+            # Important: some commands use falsy values so only default to `{}` when params is actually None.
+            command.code: params if params is not None else {},
+        }
+    }
+    return RoborockMessage(
+        protocol=RoborockMessageProtocol.RPC_REQUEST,
+        version=B01_VERSION,
+        payload=json.dumps(dps_data).encode("utf-8"),
+    )
+
+
+def _convert_datapoints(datapoints: dict[str, Any], message: RoborockMessage) -> dict[B01_Q10_DP, Any]:
+    """Convert the 'dps' dictionary keys from strings to B01_Q10_DP enums."""
+    result: dict[B01_Q10_DP, Any] = {}
+    for key, value in datapoints.items():
+        try:
+            code = int(key)
+        except ValueError as e:
+            raise ValueError(f"dps key is not a valid integer: {e} for {message.payload!r}") from e
+        if (dps := B01_Q10_DP.from_code_optional(code)) is not None:
+            # Update from_code to use `Self` on newer python version to remove this type ignore
+            result[dps] = value  # type: ignore[index]
+    return result
+
+
+def decode_rpc_response(message: RoborockMessage) -> dict[B01_Q10_DP, Any]:
+    """Decode a B01 Q10 RPC_RESPONSE message.
+
+    This does not perform any special decoding for the response body, but does
+    convert the 'dps' keys from strings to B01_Q10_DP enums.
+    """
+    if not message.payload:
+        raise RoborockException("Invalid B01 message format: missing payload")
+    try:
+        payload = json.loads(message.payload.decode())
+    except (json.JSONDecodeError, UnicodeDecodeError) as e:
+        raise RoborockException(f"Invalid B01 json payload: {e} for {message.payload!r}") from e
+
+    if (datapoints := payload.get("dps")) is None:
+        raise RoborockException(f"Invalid B01 json payload: missing 'dps' for {message.payload!r}")
+    if not isinstance(datapoints, dict):
+        raise RoborockException(f"Invalid B01 message format: 'dps' should be a dictionary for {message.payload!r}")
+
+    try:
+        result = _convert_datapoints(datapoints, message)
+    except ValueError as e:
+        raise RoborockException(f"Invalid B01 message format: {e}") from e
+
+    # The COMMON response contains nested datapoints need conversion. To simplify
+    # response handling at higher levels we flatten these into the main result.
+    if B01_Q10_DP.COMMON in result:
+        common_result = result.pop(B01_Q10_DP.COMMON)
+        if not isinstance(common_result, dict):
+            raise RoborockException(f"Invalid dpCommon format: expected dict, got {type(common_result).__name__}")
+        try:
+            common_dps_result = _convert_datapoints(common_result, message)
+        except ValueError as e:
+            raise RoborockException(f"Invalid dpCommon format: {e}") from e
+        result.update(common_dps_result)
+
+    return result