python-roborock 5.9.1__tar.gz → 5.10.0__tar.gz

{python_roborock-5.9.1 → python_roborock-5.10.0}/PKG-INFO

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

{python_roborock-5.9.1 → python_roborock-5.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.9.1"
+version = "5.10.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-5.9.1 → python_roborock-5.10.0}/roborock/callbacks.py

@@ -26,7 +26,7 @@ def safe_callback(
         try:
             callback(value)
         except Exception as ex:  # noqa: BLE001
-            logger.error("Uncaught error in callback '%s': %s", callback.__name__, ex)
+            logger.error("Uncaught error in callback '%s': %s", getattr(callback, "__name__", "Unknown"), ex)
 
     return wrapper
 

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/cli.py

@@ -419,7 +419,7 @@ async def _v1_trait(context: RoborockContext, device_id: str, display_func: Call
     device = await device_manager.get_device(device_id)
     if device.v1_properties is None:
         raise RoborockUnsupportedFeature(f"Device {device.name} does not support V1 protocol")
-    await device.v1_properties.discover_features()
+    await device.v1_properties.start()
     trait = display_func(device.v1_properties)
     if trait is None:
         raise RoborockUnsupportedFeature("Trait not supported by device")

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/data/v1/v1_containers.py

@@ -100,13 +100,14 @@ class FieldNameBase(StrEnum):
 
 
 class StatusField(FieldNameBase):
-    """An enum that represents a field in the `Status` class.
+    """An enum that represents a field in the `StatusV2` class.
 
     This is used with `roborock.devices.traits.v1.status.DeviceFeaturesTrait`
     to understand if a feature is supported by the device using `is_field_supported`.
 
-    The enum values are names of fields in the `Status` class. Each field is annotated
-    with a metadata value to determine if the field is supported by the device.
+    The enum values are names of fields in the `StatusV2` class. Each field is
+    annotated with `dps` metadata to map the field to a `RoborockDataProtocol`
+    value used to check support against the product schema.
     """
 
     STATE = "state"
@@ -670,8 +671,9 @@ class ConsumableField(FieldNameBase):
     This is used with `roborock.devices.traits.v1.status.DeviceFeaturesTrait`
     to understand if a feature is supported by the device using `is_field_supported`.
 
-    The enum values are names of fields in the `Consumable` class. Each field is annotated
-    with a metadata value to determine if the field is supported by the device.
+    The enum values are names of fields in the `Consumable` class. Each field is
+    annotated with `dps` metadata to map the field to a `RoborockDataProtocol`
+    value used to check support against the product schema.
     """
 
     MAIN_BRUSH_WORK_TIME = "main_brush_work_time"

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/devices/device.py

@@ -199,7 +199,7 @@ class RoborockDevice(ABC, TraitsMixin):
         unsub = await self._channel.subscribe(self._on_message)
         try:
             if self.v1_properties is not None:
-                await self.v1_properties.discover_features()
+                await self.v1_properties.start()
             elif self.b01_q10_properties is not None:
                 await self.b01_q10_properties.start()
         except RoborockException:
@@ -216,6 +216,8 @@ class RoborockDevice(ABC, TraitsMixin):
                 await self._connect_task
             except asyncio.CancelledError:
                 pass
+        if self.v1_properties is not None:
+            self.v1_properties.close()
         if self.b01_q10_properties is not None:
             await self.b01_q10_properties.close()
         if self._unsub:

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/devices/device_manager.py

@@ -236,6 +236,7 @@ async def create_device_manager(
                     channel.rpc_channel,
                     channel.mqtt_rpc_channel,
                     channel.map_rpc_channel,
+                    channel.add_dps_listener,
                     web_api,
                     device_cache=device_cache,
                     map_parser_config=map_parser_config,

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/devices/rpc/v1_channel.py

@@ -11,6 +11,7 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any, TypeVar
 
+from roborock.callbacks import CallbackList
 from roborock.data import HomeDataDevice, NetworkInfo, RoborockBase, UserData
 from roborock.devices.cache import DeviceCache
 from roborock.devices.transport.channel import Channel
@@ -30,9 +31,10 @@ from roborock.protocols.v1_protocol import (
     V1RpcChannel,
     create_map_response_decoder,
     create_security_data,
+    decode_data_protocol_message,
     decode_rpc_response,
 )
-from roborock.roborock_message import RoborockMessage, RoborockMessageProtocol
+from roborock.roborock_message import RoborockDataProtocol, RoborockMessage, RoborockMessageProtocol
 from roborock.roborock_typing import RoborockCommand
 from roborock.util import RoborockLoggerAdapter
 
@@ -188,6 +190,7 @@ class V1Channel(Channel):
         self._device_cache = device_cache
         self._reconnect_task: asyncio.Task[None] | None = None
         self._last_network_info_refresh: datetime.datetime | None = None
+        self._dps_listeners = CallbackList[dict[RoborockDataProtocol, Any]](self._logger)
 
     @property
     def is_connected(self) -> bool:
@@ -305,12 +308,16 @@ class V1Channel(Channel):
             loop = asyncio.get_running_loop()
             self._reconnect_task = loop.create_task(self._background_reconnect())
 
-        if not self.is_local_connected:
-            # We were not able to connect locally, so fallback to MQTT and at least
-            # establish that connection explicitly. If this fails then raise an
-            # error and let the caller know we failed to subscribe.
+        # We maintain an active MQTT subscription even when connected locally to receive
+        # unsolicited status updates (DPS push messages) directly from the cloud.
+        try:
             self._mqtt_unsub = await self._mqtt_channel.subscribe(self._on_mqtt_message)
-            self._logger.debug("V1Channel connected to device via MQTT")
+        except RoborockException as err:
+            if not self.is_local_connected:
+                # Propagate error if both local and MQTT failed
+                self._logger.debug("MQTT connection also failed: %s", err)
+                raise
+            self._logger.debug("MQTT subscription failed, continuing with local-only connection: %s", err)
 
         def unsub() -> None:
             """Unsubscribe from all messages."""
@@ -328,6 +335,16 @@ class V1Channel(Channel):
         self._callback = callback
         return unsub
 
+    def add_dps_listener(self, listener: Callable[[dict[RoborockDataProtocol, Any]], None]) -> Callable[[], None]:
+        """Add a listener for DPS updates.
+
+        This will attach a listener to the existing subscription, invoking
+        the listener whenever new DPS values arrive from the subscription.
+        This will only work if a subscription has already been setup, which is
+        handled by the device start.
+        """
+        return self._dps_listeners.add_callback(listener)
+
     async def _get_networking_info(self, *, prefer_cache: bool = True) -> NetworkInfo:
         """Retrieve networking information for the device.
 
@@ -428,6 +445,14 @@ class V1Channel(Channel):
         self._logger.debug("V1Channel received MQTT message: %s", message)
         if self._callback:
             self._callback(message)
+        try:
+            datapoints = decode_data_protocol_message(message)
+        except RoborockException as e:
+            self._logger.debug("Error decoding data protocol message: %s", e)
+            return
+
+        if datapoints:
+            self._dps_listeners(datapoints)
 
     def _on_local_message(self, message: RoborockMessage) -> None:
         """Handle incoming local messages."""

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/devices/traits/v1/__init__.py

@@ -53,6 +53,7 @@ HomeDataProduct Schema that is required for the field to be supported.
 """
 
 import logging
+from collections.abc import Callable
 from dataclasses import dataclass, field, fields
 from typing import Any, get_args
 
@@ -60,8 +61,10 @@ from roborock.data.containers import HomeData, HomeDataProduct, RoborockBase
 from roborock.data.v1.v1_code_mappings import RoborockDockTypeCode
 from roborock.devices.cache import DeviceCache
 from roborock.devices.traits import Trait
+from roborock.exceptions import RoborockException
 from roborock.map.map_parser import MapParserConfig
-from roborock.protocols.v1_protocol import V1RpcChannel
+from roborock.protocols.v1_protocol import V1RpcChannel, decode_data_protocol_message
+from roborock.roborock_message import RoborockDataProtocol, RoborockMessage
 from roborock.web_api import UserWebApiClient
 
 from . import (
@@ -176,6 +179,7 @@ class PropertiesApi(Trait):
         rpc_channel: V1RpcChannel,
         mqtt_rpc_channel: V1RpcChannel,
         map_rpc_channel: V1RpcChannel,
+        add_dps_listener: Callable[[Callable[[dict[RoborockDataProtocol, Any]], None]], Callable[[], None]],
         web_api: UserWebApiClient,
         device_cache: DeviceCache,
         map_parser_config: MapParserConfig | None = None,
@@ -189,6 +193,8 @@ class PropertiesApi(Trait):
         self._web_api = web_api
         self._device_cache = device_cache
         self._region = region
+        self._unsub: Callable[[], None] | None = None
+        self._add_dps_listener = add_dps_listener
 
         self.device_features = DeviceFeaturesTrait(product, self._device_cache)
         self.status = StatusTrait(self.device_features, region=self._region)
@@ -227,6 +233,29 @@ class PropertiesApi(Trait):
         else:
             return self._rpc_channel
 
+    async def start(self) -> None:
+        """Start the properties API and discover features."""
+        if self._unsub:
+            return
+        await self.discover_features()
+        self._unsub = self._add_dps_listener(self._on_dps_update)
+
+    def close(self) -> None:
+        if self._unsub:
+            self._unsub()
+            self._unsub = None
+
+    def _on_dps_update(self, dps: dict[RoborockDataProtocol, Any]) -> None:
+        """Handle incoming messages from the device.
+
+        This will notify all traits of the new values. This can be improved in
+        the future to be dynamic when we have more traits that support dynamic
+        updates but for now we just invoke them manually.
+        """
+        _LOGGER.debug("Received message from device: %s", dps)
+        self.status.update_from_dps(dps)
+        self.consumables.update_from_dps(dps)
+
     async def discover_features(self) -> None:
         """Populate any supported traits that were not initialized in __init__."""
         _LOGGER.debug("Starting optional trait discovery")
@@ -330,6 +359,7 @@ def create(
     rpc_channel: V1RpcChannel,
     mqtt_rpc_channel: V1RpcChannel,
     map_rpc_channel: V1RpcChannel,
+    add_dps_listener: Callable[[Callable[[dict[RoborockDataProtocol, Any]], None]], Callable[[], None]],
     web_api: UserWebApiClient,
     device_cache: DeviceCache,
     map_parser_config: MapParserConfig | None = None,
@@ -343,6 +373,7 @@ def create(
         rpc_channel,
         mqtt_rpc_channel,
         map_rpc_channel,
+        add_dps_listener,
         web_api,
         device_cache,
         map_parser_config,

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/devices/traits/v1/consumeable.py

@@ -4,17 +4,24 @@ A consumable attribute is one that is expected to be replaced or refilled
 periodically, such as filters, brushes, etc.
 """
 
+import logging
 from enum import StrEnum
-from typing import Self
+from typing import Any, Self
 
 from roborock.data import Consumable
+from roborock.devices.traits.common import DpsDataConverter, TraitUpdateListener
 from roborock.devices.traits.v1 import common
+from roborock.roborock_message import RoborockDataProtocol
 from roborock.roborock_typing import RoborockCommand
 
 __all__ = [
     "ConsumableTrait",
 ]
 
+_LOGGER = logging.getLogger(__name__)
+
+_DPS_CONVERTER = DpsDataConverter.from_dataclass(Consumable)
+
 
 class ConsumableAttribute(StrEnum):
     """Enum for consumable attributes."""
@@ -35,7 +42,7 @@ class ConsumableAttribute(StrEnum):
         raise ValueError(f"Unknown ConsumableAttribute: {value}")
 
 
-class ConsumableTrait(Consumable, common.V1TraitMixin):
+class ConsumableTrait(Consumable, common.V1TraitMixin, TraitUpdateListener):
     """Trait for managing consumable attributes on Roborock devices.
 
     After the first refresh, you can tell what consumables are supported by
@@ -45,7 +52,21 @@ class ConsumableTrait(Consumable, common.V1TraitMixin):
     command = RoborockCommand.GET_CONSUMABLE
     converter = common.DefaultConverter(Consumable)
 
+    def __init__(self) -> None:
+        """Initialize the consumable trait."""
+        super().__init__()
+        TraitUpdateListener.__init__(self, logger=_LOGGER)
+
     async def reset_consumable(self, consumable: ConsumableAttribute) -> None:
         """Reset a specific consumable attribute on the device."""
         await self.rpc_channel.send_command(RoborockCommand.RESET_CONSUMABLE, params=[consumable.value])
         await self.refresh()
+
+    def update_from_dps(self, decoded_dps: dict[RoborockDataProtocol, Any]) -> None:
+        """Update the trait from data protocol push message data.
+
+        This handles unsolicited status updates pushed by the device
+        via RoborockDataProtocol codes (e.g. STATE=121, BATTERY=122).
+        """
+        if _DPS_CONVERTER.update_from_dps(self, decoded_dps):
+            self._notify_update()

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/devices/traits/v1/status.py

@@ -1,4 +1,6 @@
+import logging
 from functools import cached_property
+from typing import Any
 
 from roborock import (
     CleanRoutes,
@@ -10,13 +12,19 @@ from roborock import (
     get_water_mode_mapping,
     get_water_modes,
 )
+from roborock.devices.traits.common import DpsDataConverter, TraitUpdateListener
+from roborock.roborock_message import RoborockDataProtocol
 from roborock.roborock_typing import RoborockCommand
 
 from . import common
 from .device_features import DeviceFeaturesTrait
 
+_LOGGER = logging.getLogger(__name__)
 
-class StatusTrait(StatusV2, common.V1TraitMixin):
+_DPS_CONVERTER = DpsDataConverter.from_dataclass(StatusV2)
+
+
+class StatusTrait(StatusV2, common.V1TraitMixin, TraitUpdateListener):
     """Trait for managing the status of Roborock devices.
 
     The StatusTrait gives you the access to the state of a Roborock vacuum.
@@ -47,6 +55,7 @@ class StatusTrait(StatusV2, common.V1TraitMixin):
     def __init__(self, device_feature_trait: DeviceFeaturesTrait, region: str | None = None) -> None:
         """Initialize the StatusTrait."""
         super().__init__()
+        TraitUpdateListener.__init__(self, logger=_LOGGER)
         self._device_features_trait = device_feature_trait
         self._region = region
 
@@ -91,3 +100,12 @@ class StatusTrait(StatusV2, common.V1TraitMixin):
         if self.mop_mode is None:
             return None
         return self.mop_route_mapping.get(self.mop_mode)
+
+    def update_from_dps(self, decoded_dps: dict[RoborockDataProtocol, Any]) -> None:
+        """Update the trait from data protocol push message data.
+
+        This handles unsolicited status updates pushed by the device
+        via RoborockDataProtocol codes (e.g. STATE=121, BATTERY=122).
+        """
+        if _DPS_CONVERTER.update_from_dps(self, decoded_dps):
+            self._notify_update()

{python_roborock-5.9.1 → python_roborock-5.10.0}/roborock/protocols/v1_protocol.py

@@ -15,7 +15,7 @@ from typing import Any, Protocol, TypeVar, overload
 from roborock.data import RoborockBase, RRiot
 from roborock.exceptions import RoborockException, RoborockInvalidStatus, RoborockUnsupportedFeature
 from roborock.protocol import Utils
-from roborock.roborock_message import RoborockMessage, RoborockMessageProtocol
+from roborock.roborock_message import RoborockDataProtocol, RoborockMessage, RoborockMessageProtocol
 from roborock.roborock_typing import RoborockCommand
 from roborock.util import get_next_int, get_timestamp
 
@@ -24,6 +24,7 @@ _LOGGER = logging.getLogger(__name__)
 __all__ = [
     "SecurityData",
     "create_security_data",
+    "decode_data_protocol_message",
     "decode_rpc_response",
     "V1RpcChannel",
 ]
@@ -139,6 +140,28 @@ class ResponseMessage:
     """The API error message of the response if any."""
 
 
+def _decode_dps_message(message: RoborockMessage) -> dict[int, Any] | None:
+    """Decode a V1 push message containing data protocol updates."""
+    if not message.payload:
+        return None
+    try:
+        payload = json.loads(message.payload.decode())
+    except (json.JSONDecodeError, TypeError, UnicodeDecodeError) as e:
+        raise RoborockException(f"Invalid V1 message payload: {e} for {message.payload!r}") from e
+
+    datapoints = payload.get("dps")
+    if not isinstance(datapoints, dict):
+        return None
+    result: dict[int, Any] = {}
+    for key, value in datapoints.items():
+        try:
+            code = int(key)
+        except (ValueError, TypeError):
+            continue
+        result[code] = value
+    return result if result else None
+
+
 def decode_rpc_response(message: RoborockMessage) -> ResponseMessage:
     """Decode a V1 RPC_RESPONSE message.
 
@@ -149,17 +172,13 @@ def decode_rpc_response(message: RoborockMessage) -> ResponseMessage:
     """
     if not message.payload:
         return ResponseMessage(request_id=message.seq, data={})
-    try:
-        payload = json.loads(message.payload.decode())
-    except (json.JSONDecodeError, TypeError, UnicodeDecodeError) as e:
-        raise RoborockException(f"Invalid V1 message payload: {e} for {message.payload!r}") from e
 
-    _LOGGER.debug("Decoded V1 message payload: %s", payload)
-    datapoints = payload.get("dps", {})
-    if not isinstance(datapoints, dict):
-        raise RoborockException(f"Invalid V1 message format: 'dps' should be a dictionary for {message.payload!r}")
+    if (datapoints := _decode_dps_message(message)) is None:
+        raise RoborockException(
+            f"Invalid V1 message format: missing or invalid 'dps' in payload for {message.payload!r}"
+        )
 
-    if not (data_point := datapoints.get(str(RoborockMessageProtocol.RPC_RESPONSE))):
+    if not (data_point := datapoints.get(RoborockMessageProtocol.RPC_RESPONSE)):
         raise RoborockException(
             f"Invalid V1 message format: missing '{RoborockMessageProtocol.RPC_RESPONSE}' data point"
         )
@@ -206,6 +225,31 @@ def decode_rpc_response(message: RoborockMessage) -> ResponseMessage:
     return ResponseMessage(request_id=request_id, data=result, api_error=api_error)
 
 
+def decode_data_protocol_message(message: RoborockMessage) -> dict[RoborockDataProtocol, Any] | None:
+    """Decode a V1 push message containing data protocol updates.
+
+    V1 devices push unsolicited status updates containing data points keyed
+    by RoborockDataProtocol codes (e.g., 121=STATE, 122=BATTERY). This function
+    extracts those data points from the message payload.
+
+    Returns a dict mapping RoborockDataProtocol to values, or None if the
+    message does not contain any recognized data protocol updates.
+    """
+    if (datapoints := _decode_dps_message(message)) is None:
+        return None
+
+    result: dict[RoborockDataProtocol, Any] = {}
+    for code, value in datapoints.items():
+        try:
+            protocol = RoborockDataProtocol(code)
+        except ValueError:
+            _LOGGER.debug("Ignoring unknown V1 data protocol code: %s", code)
+            continue
+        result[protocol] = value
+
+    return result if result else None
+
+
 @dataclass
 class MapResponse:
     """Data structure for the V1 Map response."""