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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.8.0"
+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.8.0 → 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.8.0 → 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)
 

{python_roborock-5.8.0 → 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.8.0/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