python-roborock 5.7.1__tar.gz → 5.9.0__tar.gz

{python_roborock-5.7.1 → python_roborock-5.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 5.7.1
+Version: 5.9.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.7.1 → python_roborock-5.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.7.1"
+version = "5.9.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.7.1 → python_roborock-5.9.0}/roborock/data/v1/v1_code_mappings.py

@@ -1,3 +1,4 @@
+from enum import StrEnum
 from typing import Self
 
 from ..code_mappings import RoborockEnum
@@ -63,6 +64,60 @@ class RoborockCleanType(RoborockEnum):
     pet_patrol = 6
 
 
+class RoborockChargeStatus(RoborockEnum):
+    """Describes the charging status of the device."""
+
+    unknown = -1
+    charge_waiting = 0
+    charging = 1
+
+
+class RoborockDockState(StrEnum):
+    """Synthesized high-level dock and power state of the device.
+
+    This enum represents a unified "UI-level" state that combines multiple raw
+    device data points (`state`, `charge_status`, `battery`) into a single,
+    human-readable status that accurately reflects what the vacuum is doing
+    relative to the dock.
+
+    It is highly recommended for consumers of this API
+    to use this synthesized state to determine if the vacuum is charging or
+    docked, rather than attempting to parse the raw integer data points, as
+    this safely handles backward compatibility for older models that lack
+    explicit off-peak schedule reporting.
+    """
+
+    unknown = "unknown"
+    """The dock state could not be determined or is unmapped."""
+
+    idle = "idle"
+    """The vacuum is away from the dock (e.g., cleaning, paused, or errored).
+    In the official app, this state presents the 'Return to Dock' or 'Recharge' action."""
+
+    returning = "returning"
+    """The vacuum is actively navigating its way back to the dock.
+    In the official app, this state presents the 'Stop' or 'Pause' action."""
+
+    charging = "charging"
+    """The vacuum is on the dock and actively receiving electricity.
+    In the official app, this state is displayed as 'Charging'."""
+
+    off_peak_waiting = "off_peak_waiting"
+    """The vacuum is on the dock but charging is paused. It is waiting for the
+    user's scheduled 'Valley Electricity' off-peak hours to begin before
+    drawing power.
+    In the official app, this state is displayed as 'Charging paused during peak hours'."""
+
+    full = "full"
+    """The vacuum is on the dock and the battery is at 100% capacity.
+    In the official app, this state is displayed as 'Fully charged'."""
+
+    dusting = "dusting"
+    """The vacuum is on the dock and is currently being evacuated by the
+    auto-empty base.
+    In the official app, this state is displayed as 'Emptying dustbin'."""
+
+
 class RoborockStartType(RoborockEnum):
     button = 1
     app = 2

{python_roborock-5.7.1 → python_roborock-5.9.0}/roborock/data/v1/v1_containers.py

@@ -46,9 +46,11 @@ from .v1_code_mappings import (
     ClearWaterBoxStatus,
     DirtyWaterBoxStatus,
     DustBagStatus,
+    RoborockChargeStatus,
     RoborockCleanType,
     RoborockDockDustCollectionModeCode,
     RoborockDockErrorCode,
+    RoborockDockState,
     RoborockDockTypeCode,
     RoborockErrorCode,
     RoborockFanPowerCode,
@@ -161,7 +163,9 @@ class Status(RoborockBase):
     collision_avoid_status: int | None = None
     switch_map_mode: int | None = None
     dock_error_status: RoborockDockErrorCode | None = None
-    charge_status: int | None = field(default=None, metadata={"dps": RoborockDataProtocol.CHARGE_STATUS})
+    charge_status: RoborockChargeStatus | None = field(
+        default=None, metadata={"dps": RoborockDataProtocol.CHARGE_STATUS}
+    )
     unsave_map_reason: int | None = None
     unsave_map_flag: int | None = None
     wash_status: int | None = None
@@ -329,7 +333,9 @@ class StatusV2(RoborockBase):
     collision_avoid_status: int | None = None
     switch_map_mode: int | None = None
     dock_error_status: RoborockDockErrorCode | None = None
-    charge_status: int | None = field(default=None, metadata={"dps": RoborockDataProtocol.CHARGE_STATUS})
+    charge_status: RoborockChargeStatus | None = field(
+        default=None, metadata={"dps": RoborockDataProtocol.CHARGE_STATUS}
+    )
     unsave_map_reason: int | None = None
     unsave_map_flag: int | None = None
     wash_status: int | None = None
@@ -414,6 +420,41 @@ class StatusV2(RoborockBase):
             return (self.dss >> 15) & 3
         return None
 
+    @property
+    def dock_state(self) -> RoborockDockState:
+        """A synthesized, high-level dock state reflecting the UI's display.
+
+        This property simplifies integration by handling the complex logic
+        of checking state, charge_status, and battery level simultaneously. It handles
+        newer off-peak charging logic seamlessly while maintaining backwards compatibility
+        with older devices.
+        """
+        if self.state is None or self.state == RoborockStateCode.unknown:
+            return RoborockDockState.unknown
+
+        # 6. DUSTING
+        if self.state == RoborockStateCode.emptying_the_bin:
+            return RoborockDockState.dusting
+
+        # 5. FULL
+        if self.state == RoborockStateCode.charging_complete or (
+            self.state == RoborockStateCode.charging and self.battery == 100
+        ):
+            return RoborockDockState.full
+
+        # 3 & 4. CHARGING and CHARGE_WAITING
+        if self.state == RoborockStateCode.charging:
+            if self.charge_status == RoborockChargeStatus.charge_waiting:
+                return RoborockDockState.off_peak_waiting
+            return RoborockDockState.charging
+
+        # 2. RECHARGING
+        if self.state in (RoborockStateCode.returning_home, RoborockStateCode.docking):
+            return RoborockDockState.returning
+
+        # 1. IDLE (Not on dock, or doing something else)
+        return RoborockDockState.idle
+
     def __repr__(self) -> str:
         return _attr_repr(self)
 
@@ -792,7 +833,7 @@ class AppInitStatusLocalInfo(RoborockBase):
 class AppInitStatus(RoborockBase):
     local_info: AppInitStatusLocalInfo
     feature_info: list[int]
-    new_feature_info: int
+    new_feature_info: int = 0
     new_feature_info_str: str = ""
     new_feature_info_2: int | None = None
     carriage_type: int | None = None

{python_roborock-5.7.1 → python_roborock-5.9.0}/roborock/devices/traits/b01/q10/status.py

@@ -5,8 +5,7 @@ from typing import Any
 
 from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
 from roborock.data.b01_q10.b01_q10_containers import Q10Status
-
-from .common import DpsDataConverter, TraitUpdateListener
+from roborock.devices.traits.common import DpsDataConverter, TraitUpdateListener
 
 _LOGGER = logging.getLogger(__name__)
 

{python_roborock-5.7.1/roborock/devices/traits/b01/q10 → python_roborock-5.9.0/roborock/devices/traits}/common.py

@@ -1,8 +1,7 @@
-"""Common utilities for Q10 traits.
+"""Common utilities for device traits.
 
-This module provides infrastructure for mapping Roborock Data Points (DPS) to
-Python dataclass fields and handling the lifecycle of data updates from the
-device.
+This module provides shared infrastructure for mapping Roborock Data Points (DPS) to
+Python dataclass fields and handling the lifecycle of data updates from the device.
 
 ### DPS Metadata Annotation
 
@@ -21,7 +20,7 @@ class MyStatus(RoborockBase):
 
 ### Update Lifecycle
 1. **Raw Data**: The device sends encoded DPS updates over MQTT.
-2. **Decoding**: The transport layer decodes these into a dictionary (e.g., `{"101": 80}`).
+2. **Decoding**: The transport layer decodes these into a dictionary (e.g., {"101": 80}).
 3. **Conversion**: `DpsDataConverter` uses `RoborockBase.convert_dict` to transform
    raw values into appropriate Python types (e.g., Enums, ints) based on the
    dataclass field types.
@@ -32,18 +31,18 @@ class MyStatus(RoborockBase):
 
 Typically, a trait will instantiate a single `DpsDataConverter` for its status class
 and call `update_from_dps` whenever new data is received from the device stream.
-
 """
 
 import dataclasses
 import logging
 from collections.abc import Callable
-from typing import Any
+from typing import Any, Generic, TypeVar
 
 from roborock.callbacks import CallbackList
-from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
 from roborock.data.containers import RoborockBase
 
+TDps = TypeVar("TDps", bound=int)
+
 
 class TraitUpdateListener:
     """Trait update listener.
@@ -71,14 +70,14 @@ class TraitUpdateListener:
         self._update_callbacks(None)
 
 
-class DpsDataConverter:
+class DpsDataConverter(Generic[TDps]):
     """Utility to handle the transformation and merging of DPS data into models.
 
     This class pre-calculates the mapping between Data Point IDs and dataclass fields
     to optimize repeated updates from device streams.
     """
 
-    def __init__(self, dps_type_map: dict[B01_Q10_DP, type], dps_field_map: dict[B01_Q10_DP, str]):
+    def __init__(self, dps_type_map: dict[TDps, type], dps_field_map: dict[TDps, str]):
         """Initialize the converter for a specific RoborockBase-derived class."""
         self._dps_type_map = dps_type_map
         self._dps_field_map = dps_field_map
@@ -86,8 +85,8 @@ class DpsDataConverter:
     @classmethod
     def from_dataclass(cls, dataclass_type: type[RoborockBase]):
         """Initialize the converter for a specific RoborockBase-derived class."""
-        dps_type_map: dict[B01_Q10_DP, type] = {}
-        dps_field_map: dict[B01_Q10_DP, str] = {}
+        dps_type_map: dict[TDps, type] = {}
+        dps_field_map: dict[TDps, str] = {}
         for field_obj in dataclasses.fields(dataclass_type):
             if field_obj.metadata and "dps" in field_obj.metadata:
                 dps_id = field_obj.metadata["dps"]
@@ -95,7 +94,7 @@ class DpsDataConverter:
                 dps_field_map[dps_id] = field_obj.name
         return cls(dps_type_map, dps_field_map)
 
-    def update_from_dps(self, target: RoborockBase, decoded_dps: dict[B01_Q10_DP, Any]) -> bool:
+    def update_from_dps(self, target: RoborockBase, decoded_dps: dict[TDps, Any]) -> bool:
         """Convert and merge raw DPS data into the target object.
 
         Uses the pre-calculated type mapping to ensure values are converted to the

{python_roborock-5.7.1 → python_roborock-5.9.0}/roborock/devices/traits/v1/clean_summary.py

@@ -2,6 +2,7 @@ import logging
 
 from roborock.data import CleanRecord, CleanSummaryWithDetail, RoborockBase
 from roborock.devices.traits.v1 import common
+from roborock.exceptions import RoborockParsingException
 from roborock.roborock_typing import RoborockCommand
 from roborock.util import unpack_list
 
@@ -87,4 +88,12 @@ class CleanSummaryTrait(CleanSummaryWithDetail, common.V1TraitMixin):
     async def get_clean_record(self, record_id: int) -> CleanRecord:
         """Load a specific clean record by ID."""
         response = await self.rpc_channel.send_command(RoborockCommand.GET_CLEAN_RECORD, params=[record_id])
-        return self.clean_record_converter.convert(response)
+        try:
+            return self.clean_record_converter.convert(response)
+        except (TypeError, ValueError) as err:
+            raise RoborockParsingException(
+                trait_name=type(self).__name__,
+                command=RoborockCommand.GET_CLEAN_RECORD,
+                payload=response,
+                inner_error=err,
+            ) from err

{python_roborock-5.7.1 → python_roborock-5.9.0}/roborock/devices/traits/v1/common.py

@@ -9,6 +9,7 @@ from dataclasses import fields
 from typing import ClassVar
 
 from roborock.data import RoborockBase
+from roborock.exceptions import RoborockParsingException
 from roborock.protocols.v1_protocol import V1RpcChannel
 from roborock.roborock_typing import RoborockCommand
 
@@ -63,7 +64,7 @@ class V1TraitMixin(ABC):
 
     def __init__(self) -> None:
         """Initialize the V1TraitMixin."""
-        self._rpc_channel = None
+        self._rpc_channel: V1RpcChannel | None = None
 
     @property
     def rpc_channel(self) -> V1RpcChannel:
@@ -75,7 +76,15 @@ class V1TraitMixin(ABC):
     async def refresh(self) -> None:
         """Refresh the contents of this trait."""
         response = await self.rpc_channel.send_command(self.command)
-        new_data = self.converter.convert(response)
+        try:
+            new_data = self.converter.convert(response)
+        except (TypeError, ValueError) as err:
+            raise RoborockParsingException(
+                trait_name=type(self).__name__,
+                command=self.command,
+                payload=response,
+                inner_error=err,
+            ) from err
         merge_trait_values(self, new_data)  # type: ignore[arg-type]
 
 

{python_roborock-5.7.1 → python_roborock-5.9.0}/roborock/devices/traits/v1/rooms.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 
 from roborock.data import HomeData, HomeDataRoom, NamedRoomMapping, RoborockBase
 from roborock.devices.traits.v1 import common
+from roborock.exceptions import RoborockParsingException
 from roborock.roborock_typing import RoborockCommand
 from roborock.web_api import UserWebApiClient
 
@@ -94,7 +95,12 @@ class RoomsTrait(Rooms, common.V1TraitMixin):
         """Refresh room mappings and backfill unknown room names from the web API."""
         response = await self.rpc_channel.send_command(self.command)
         if not isinstance(response, list):
-            raise ValueError(f"Unexpected RoomsTrait response format: {response!r}")
+            raise RoborockParsingException(
+                trait_name=type(self).__name__,
+                command=self.command,
+                payload=response,
+                inner_error="Unexpected RoomsTrait response format",
+            )
 
         segment_map = RoomsConverter.extract_segment_map(response)
         # Track all iot ids seen before. Refresh the room list when new ids are found.
@@ -105,8 +111,16 @@ class RoomsTrait(Rooms, common.V1TraitMixin):
                 _LOGGER.debug("Updating rooms: %s", list(updated_rooms))
                 self._home_data.rooms = updated_rooms
             self._discovered_iot_ids.update(new_iot_ids)
+        try:
+            rooms = self.converter.convert(response)
+        except (TypeError, ValueError) as err:
+            raise RoborockParsingException(
+                trait_name=type(self).__name__,
+                command=self.command,
+                payload=response,
+                inner_error=err,
+            ) from err
 
-        rooms = self.converter.convert(response)
         rooms = rooms.with_room_names(self._home_data.rooms_name_map)
         common.merge_trait_values(self, rooms)
 

{python_roborock-5.7.1 → python_roborock-5.9.0}/roborock/exceptions.py

@@ -1,5 +1,8 @@
 """Roborock exceptions."""
 
+from enum import Enum
+from typing import Any
+
 
 class RoborockException(Exception):
     """Class for Roborock exceptions."""
@@ -91,3 +94,14 @@ class RoborockInvalidStatus(RoborockException):
 
 class RoborockUnsupportedFeature(RoborockException):
     """Class for Roborock unsupported feature exceptions."""
+
+
+class RoborockParsingException(RoborockException):
+    """Class for Roborock exceptions when parsing device responses."""
+
+    def __init__(self, trait_name: str, command: Enum | str, payload: Any, inner_error: Exception | str) -> None:
+        cmd_name = command.name if isinstance(command, Enum) else str(command)
+        self.message = (
+            f"Failed to parse {cmd_name} response for {trait_name}. Payload: {payload!r} Error: {inner_error!r}"
+        )
+        super().__init__(self.message)