python-roborock 5.28.1__tar.gz → 5.30.0__tar.gz

{python_roborock-5.28.1 → python_roborock-5.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 5.28.1
+Version: 5.30.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.28.1 → python_roborock-5.30.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.28.1"
+version = "5.30.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.28.1 → python_roborock-5.30.0}/roborock/data/containers.py

@@ -60,6 +60,25 @@ def _attr_repr(obj: Any) -> str:
     return f"{type(obj).__name__}({', '.join(parts)})"
 
 
+def field_metadata(**kwargs):
+    """Decorator to attach capability check metadata to a property.
+
+    This attaches a `_field_metadata` dictionary to the underlying getter function,
+    which is then preserved when decorated with `@property`.
+
+    Supported metadata keys:
+    - `feature` (str): Name of a capability property on `DeviceFeaturesTrait`.
+    - `dock_feature` (str): Name of a capability property on `RoborockDockFeatures`.
+    - `dps` (str/int): RoborockDataProtocol ID to check against supported schema IDs.
+    """
+
+    def decorator(func):
+        func._field_metadata = kwargs
+        return func
+
+    return decorator
+
+
 @dataclass(repr=False)
 class RoborockBase:
     """Base class for all Roborock data classes."""

{python_roborock-5.28.1 → python_roborock-5.30.0}/roborock/data/v1/v1_containers.py

@@ -39,7 +39,7 @@ from roborock.const import (
 from roborock.exceptions import RoborockException
 from roborock.roborock_message import RoborockDataProtocol
 
-from ..containers import NamedRoomMapping, RoborockBase, RoborockBaseTimer, _attr_repr
+from ..containers import NamedRoomMapping, RoborockBase, RoborockBaseTimer, _attr_repr, field_metadata
 from .v1_clean_modes import WashTowelModes
 from .v1_code_mappings import (
     CleanFluidStatus,
@@ -117,6 +117,15 @@ class StatusField(FieldNameBase):
     CHARGE_STATUS = "charge_status"
     DRY_STATUS = "dry_status"
     ERROR_CODE = "error_code"
+    WATER_BOX_CARRIAGE_STATUS = "water_box_carriage_status"
+    WATER_BOX_STATUS = "water_box_status"
+    WATER_SHORTAGE_STATUS = "water_shortage_status"
+    DIRTY_WATER_BOX_STATUS = "dirty_water_box_status"
+    CLEAR_WATER_BOX_STATUS = "clear_water_box_status"
+    CLEAN_FLUID_STATUS = "clean_fluid_status"
+    CLEAN_PERCENT = "clean_percent"
+    DOCK_ERROR_STATUS = "dock_error_status"
+    RDT = "rdt"
 
 
 @dataclass
@@ -246,12 +255,14 @@ class Status(RoborockBase):
         return (self.dss & 3) == 2
 
     @property
+    @field_metadata(dock_feature="is_washable")
     def clear_water_box_status(self) -> ClearWaterBoxStatus | None:
         if self.dss:
             return ClearWaterBoxStatus((self.dss >> 2) & 3)
         return None
 
     @property
+    @field_metadata(dock_feature="is_washable")
     def dirty_water_box_status(self) -> DirtyWaterBoxStatus | None:
         if self.dss:
             return DirtyWaterBoxStatus((self.dss >> 4) & 3)
@@ -270,6 +281,9 @@ class Status(RoborockBase):
         return None
 
     @property
+    @field_metadata(
+        dock_feature="is_clean_fluid_auto_delivery_supported",
+    )
     def clean_fluid_status(self) -> CleanFluidStatus | None:
         if self.dss:
             value = (self.dss >> 10) & 3
@@ -313,7 +327,7 @@ class StatusV2(RoborockBase):
     in_returning: int | None = None
     in_fresh_state: int | None = None
     lab_status: int | None = None
-    water_box_status: int | None = None
+    water_box_status: int | None = field(default=None, metadata={"feature": "is_support_water_mode"})
     back_type: int | None = None
     wash_phase: int | None = None
     wash_ready: int | None = None
@@ -323,14 +337,14 @@ class StatusV2(RoborockBase):
     is_locating: int | None = None
     lock_status: int | None = None
     water_box_mode: int | None = field(default=None, metadata={"dps": RoborockDataProtocol.WATER_BOX_MODE})
-    water_box_carriage_status: int | None = None
+    water_box_carriage_status: int | None = field(default=None, metadata={"feature": "is_support_water_mode"})
     mop_forbidden_enable: int | None = None
     camera_status: int | None = None
     is_exploring: int | None = None
     home_sec_status: int | None = None
     home_sec_enable_password: int | None = None
     adbumper_status: list[int] | None = None
-    water_shortage_status: int | None = None
+    water_shortage_status: int | None = field(default=None, metadata={"feature": "is_support_water_mode"})
     dock_type: RoborockDockTypeCode | None = None
     dust_collection_status: int | None = None
     auto_dust_collection: int | None = None
@@ -339,7 +353,8 @@ class StatusV2(RoborockBase):
     debug_mode: int | None = None
     collision_avoid_status: int | None = None
     switch_map_mode: int | None = None
-    dock_error_status: RoborockDockErrorCode | None = None
+    dock_error_status: RoborockDockErrorCode | None = field(default=None, metadata={"dock_feature": "has_dock"})
+
     charge_status: RoborockChargeStatus | None = field(
         default=None, metadata={"dps": RoborockDataProtocol.CHARGE_STATUS}
     )
@@ -349,8 +364,8 @@ class StatusV2(RoborockBase):
     distance_off: int | None = None
     in_warmup: int | None = None
     dry_status: int | None = field(default=None, metadata={"dps": RoborockDataProtocol.DRYING_STATUS})
-    rdt: int | None = None
-    clean_percent: int | None = None
+    rdt: int | None = field(default=None, metadata={"feature": "is_supported_drying"})
+    clean_percent: int | None = field(default=None, metadata={"feature": "is_support_clean_estimate"})
     rss: int | None = None
     dss: int | None = None
     common_status: int | None = None
@@ -389,12 +404,14 @@ class StatusV2(RoborockBase):
         return (self.dss & 3) == 2
 
     @property
+    @field_metadata(dock_feature="is_washable")
     def clear_water_box_status(self) -> ClearWaterBoxStatus | None:
         if self.dss:
             return ClearWaterBoxStatus((self.dss >> 2) & 3)
         return None
 
     @property
+    @field_metadata(dock_feature="is_washable")
     def dirty_water_box_status(self) -> DirtyWaterBoxStatus | None:
         if self.dss:
             return DirtyWaterBoxStatus((self.dss >> 4) & 3)
@@ -413,6 +430,9 @@ class StatusV2(RoborockBase):
         return None
 
     @property
+    @field_metadata(
+        dock_feature="is_clean_fluid_auto_delivery_supported",
+    )
     def clean_fluid_status(self) -> CleanFluidStatus | None:
         if self.dss:
             value = (self.dss >> 10) & 3

{python_roborock-5.28.1 → python_roborock-5.30.0}/roborock/devices/traits/v1/__init__.py

@@ -264,6 +264,7 @@ class PropertiesApi(Trait):
         # Dock type also acts like a device feature for some traits.
         dock_type = await self._dock_type()
         dock_features = RoborockDockFeatures.from_dock_type(dock_type, has_am=self.status.has_am)
+        self.device_features.dock_features = dock_features
 
         # Initialize traits with special arguments before the generic loop
         if self.wash_towel_mode is None and self._is_supported(WashTowelModeTrait, "wash_towel_mode", dock_features):

{python_roborock-5.28.1 → python_roborock-5.30.0}/roborock/devices/traits/v1/device_features.py

@@ -1,12 +1,33 @@
-from dataclasses import Field, fields
+from dataclasses import fields
+from typing import Any
 
 from roborock.data import AppInitStatus, HomeDataProduct, RoborockBase
+from roborock.data.v1 import RoborockDockTypeCode
 from roborock.data.v1.v1_containers import FieldNameBase
-from roborock.device_features import DeviceFeatures
+from roborock.device_features import DeviceFeatures, RoborockDockFeatures
 from roborock.devices.cache import DeviceCache
 from roborock.devices.traits.v1 import common
 from roborock.roborock_typing import RoborockCommand
 
+# Cache of metadata for each trait class
+_metadata_cache: dict[type[RoborockBase], dict[str, dict[str, Any]]] = {}
+
+
+def _get_field_metadata(cls: type[RoborockBase]) -> dict[str, Any]:
+    """Helper to get metadata from either class properties or dataclass fields."""
+    if cls not in _metadata_cache:
+        metadata_map = {}
+        # Inspect properties with @field_metadata
+        for name in dir(cls):
+            prop = getattr(cls, name, None)
+            if isinstance(prop, property):
+                metadata_map[name] = getattr(prop.fget, "_field_metadata", {})
+        # Inspect dataclass fields metadata
+        for f in fields(cls):
+            metadata_map[f.name] = f.metadata
+        _metadata_cache[cls] = metadata_map
+    return _metadata_cache[cls]
+
 
 class DeviceTraitsConverter(common.V1TraitDataConverter):
     """Converter for APP_GET_INIT_STATUS responses into DeviceFeatures."""
@@ -40,31 +61,37 @@ class DeviceFeaturesTrait(DeviceFeatures, common.V1TraitMixin):
         self.converter = DeviceTraitsConverter(product)
         self._product = product
         self._device_cache = device_cache
+        # Dock features are populated after device feature discovery
+        # is triggered.
+        self.dock_features: RoborockDockFeatures = RoborockDockFeatures.from_dock_type(RoborockDockTypeCode.o0_dock)
         # All fields of DeviceFeatures are required. Initialize them to False
         # so we have some known state.
         for field in fields(self):
             setattr(self, field.name, False)
 
-    @staticmethod
-    def _get_dataclass_field(cls: type[RoborockBase], field_name: FieldNameBase) -> Field:
-        """Look up a dataclass field by its FieldNameBase name."""
-        for f in fields(cls):
-            if f.name == field_name:
-                return f
-        raise ValueError(f"Field {field_name!r} not found in {cls}")
-
     def is_field_supported(self, cls: type[RoborockBase], field_name: FieldNameBase) -> bool:
         """Determines if the specified field is supported by this device.
 
-        We use the `dps` dataclass field metadata to get the `RoborockDataProtocol`
-        integer ID and check it against the set of supported schema IDs for the
-        device returned in the product information.
+        We inspect the metadata defined for the field (either via dataclass field metadata
+        or the `@field_metadata` decorator on properties). Supported checks include:
+
+        - `feature`: Maps to a boolean capability property on `DeviceFeatures` / `DeviceFeaturesTrait`
+          (e.g. `is_support_water_mode`).
+        - `dock_feature`: Maps to a boolean capability property on `RoborockDockFeatures` (e.g. `is_washable`).
+        - `dps`: Maps to a `RoborockDataProtocol` ID checked against the product's supported schema IDs.
         """
-        dataclass_field = self._get_dataclass_field(cls, field_name)
-        if (dps := dataclass_field.metadata.get("dps")) is None:
-            # No DPS metadata — field is assumed always supported
-            return True
-        return int(dps) in self._product.supported_schema_ids
+        if self.dock_features is None:
+            raise ValueError("DeviceFeaturesTrait was invoked but was not fully initialized")
+        metadata_map = _get_field_metadata(cls)
+        if (field_metadata := metadata_map.get(field_name)) is not None:
+            if (feature := field_metadata.get("feature")) is not None:
+                return getattr(self, feature, False)
+            if (dock_feature := field_metadata.get("dock_feature")) is not None:
+                return getattr(self.dock_features, dock_feature, False)
+            if (dps := field_metadata.get("dps")) is not None:
+                return int(dps) in self._product.supported_schema_ids
+        # No metadata, field is assumed always supported
+        return True
 
     async def refresh(self) -> None:
         """Refresh the contents of this trait.

{python_roborock-5.28.1 → python_roborock-5.30.0}/roborock/roborock_message.py

@@ -274,6 +274,9 @@ ROBOROCK_DATA_CONSUMABLE_PROTOCOL = [
 ]
 
 
+MAX_PAYLOAD_REPR_LEN = 1024
+
+
 @dataclass
 class RoborockMessage:
     protocol: RoborockMessageProtocol
@@ -282,3 +285,18 @@ class RoborockMessage:
     version: bytes = b"1.0"
     random: int = field(default_factory=lambda: get_next_int(10000, 99999))
     timestamp: int = field(default_factory=lambda: get_timestamp())
+
+    def __repr__(self) -> str:
+        payload_repr = "None"
+        if self.payload is not None:
+            if isinstance(self.payload, (bytes, bytearray, str)) and len(self.payload) > MAX_PAYLOAD_REPR_LEN:
+                r = repr(self.payload[:MAX_PAYLOAD_REPR_LEN])
+                quote = r[-1]
+                payload_repr = f"{r[:-1]}...{quote} (length: {len(self.payload)})"
+            else:
+                payload_repr = repr(self.payload)
+        return (
+            f"RoborockMessage(protocol={self.protocol}, payload={payload_repr}, "
+            f"seq={self.seq}, version={self.version!r}, random={self.random}, "
+            f"timestamp={self.timestamp})"
+        )