Merge branch 'main' into main

Author: Lash-L

CHANGELOG.md

@@ -2,6 +2,63 @@
 
 <!-- version list -->
 
+## v5.10.1 (2026-05-12)
+
+### Bug Fixes
+
+- Handle Web API unauthorized errors
+  ([#825](https://github.com/Python-roborock/python-roborock/pull/825),
+  [`ad8d8f0`](https://github.com/Python-roborock/python-roborock/commit/ad8d8f095a260ee720c3e0193bcba5bd691c9f96))
+
+- Mark non vacuum v1 devices as not supported
+  ([#828](https://github.com/Python-roborock/python-roborock/pull/828),
+  [`2e9a848`](https://github.com/Python-roborock/python-roborock/commit/2e9a84807f5d0c2cffb5b0b6592b9baa6ee14c64))
+
+
+## v5.10.0 (2026-05-03)
+
+### Features
+
+- Implement direct device trait updates from data protocol messages using `dps` metadata and add
+  corresponding update listeners
+  ([#799](https://github.com/Python-roborock/python-roborock/pull/799),
+  [`ba57677`](https://github.com/Python-roborock/python-roborock/commit/ba576778bb51f7e381e16ec93ff218d4a898e009))
+
+
+## v5.9.1 (2026-05-02)
+
+### Bug Fixes
+
+- Fix operator precedence bug with walrus operator in cli.py command execution
+  ([#822](https://github.com/Python-roborock/python-roborock/pull/822),
+  [`c3ae98b`](https://github.com/Python-roborock/python-roborock/commit/c3ae98b9ff7acadb97d4d5be8e3409d9fa8ed2a5))
+
+
+## v5.9.0 (2026-04-29)
+
+### Chores
+
+- Address review feedback for dock_state
+  ([#821](https://github.com/Python-roborock/python-roborock/pull/821),
+  [`3fdb963`](https://github.com/Python-roborock/python-roborock/commit/3fdb963401c8e81a39faf9ce5c11e9ecec303d91))
+
+### Features
+
+- Implement RoborockDockState synthesis and RoborockChargeStatus enum
+  ([#821](https://github.com/Python-roborock/python-roborock/pull/821),
+  [`3fdb963`](https://github.com/Python-roborock/python-roborock/commit/3fdb963401c8e81a39faf9ce5c11e9ecec303d91))
+
+- Implement RoborockDockState synthesis and RoborockChargeStatus enum for improved device status
+  reporting ([#821](https://github.com/Python-roborock/python-roborock/pull/821),
+  [`3fdb963`](https://github.com/Python-roborock/python-roborock/commit/3fdb963401c8e81a39faf9ce5c11e9ecec303d91))
+
+### Refactoring
+
+- Centralize trait update listener and dps converter
+  ([#820](https://github.com/Python-roborock/python-roborock/pull/820),
+  [`d125afb`](https://github.com/Python-roborock/python-roborock/commit/d125afbd53b03e883e539bddc28faef836be8cb9))
+
+
 ## v5.8.0 (2026-04-26)
 
 ### Features

docs/DEVICES.md

@@ -357,7 +357,7 @@ graph LR
 1. **Temporary Subscriptions**: Each RPC creates a temporary subscription that matches the request ID
 2. **Subscription Reuse**: `MqttSession` keeps subscriptions alive for 60 seconds (or idle timeout) to enable reuse during command bursts
 3. **Timeout Handling**: Commands timeout after 10 seconds if no response is received
-4. **Multiple Strategies**: `V1Channel` tries local first, then falls back to MQTT if local fails
+4. **Multiple Strategies**: `V1Channel` tries connect to both Local faster local commands and MQTT for streaming updates.
 
 ## Class Design & Components
 

pyproject.toml

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

roborock/callbacks.py

@@ -26,7 +26,7 @@ def wrapper(value: V) -> None:
         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
 

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")
@@ -780,7 +780,7 @@ async def command(ctx, cmd, device_id, params):
         if result:
             click.echo(dump_json(result))
     elif device.b01_q10_properties is not None:
-        if cmd_value := B01_Q10_DP.from_any_optional(cmd) is None:
+        if (cmd_value := B01_Q10_DP.from_any_optional(cmd)) is None:
             raise RoborockException(f"Invalid command {cmd} for B01_Q10 device")
         command_trait: Trait = device.b01_q10_properties.command
         await command_trait.send(cmd_value, json.loads(params) if params is not None else None)

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

roborock/data/v1/v1_containers.py

@@ -46,9 +46,11 @@
     ClearWaterBoxStatus,
     DirtyWaterBoxStatus,
     DustBagStatus,
+    RoborockChargeStatus,
     RoborockCleanType,
     RoborockDockDustCollectionModeCode,
     RoborockDockErrorCode,
+    RoborockDockState,
     RoborockDockTypeCode,
     RoborockErrorCode,
     RoborockFanPowerCode,
@@ -98,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"
@@ -161,7 +164,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 +334,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 +421,41 @@ def dock_cool_fan_status(self) -> int | None:
             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)
 
@@ -629,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"

roborock/devices/device.py

@@ -199,7 +199,7 @@ async def connect(self) -> None:
         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 @@ async def close(self) -> None:
                 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:

roborock/devices/device_manager.py

@@ -13,6 +13,7 @@
     HomeData,
     HomeDataDevice,
     HomeDataProduct,
+    RoborockCategory,
     UserData,
 )
 from roborock.devices.device import DeviceReadyCallback, RoborockDevice
@@ -173,14 +174,15 @@ def create_web_api_wrapper(
     *,
     cache: Cache | None = None,
     session: aiohttp.ClientSession | None = None,
+    unauthorized_hook: SessionUnauthorizedHook | None = None,
 ) -> UserWebApiClient:
     """Create a home data API wrapper from an existing API client."""
 
     # Note: This will auto discover the API base URL. This can be improved
     # by caching this next to `UserData` if needed to avoid unnecessary API calls.
     client = RoborockApiClient(username=user_params.username, base_url=user_params.base_url, session=session)
 
-    return UserWebApiClient(client, user_params.user_data)
+    return UserWebApiClient(client, user_params.user_data, unauthorized_hook=unauthorized_hook)
 
 
 async def create_device_manager(
@@ -212,7 +214,9 @@ async def create_device_manager(
     if cache is None:
         cache = NoCache()
 
-    web_api = create_web_api_wrapper(user_params, session=session, cache=cache)
+    web_api = create_web_api_wrapper(
+        user_params, session=session, cache=cache, unauthorized_hook=mqtt_session_unauthorized_hook
+    )
     user_data = user_params.user_data
 
     diagnostics = Diagnostics()
@@ -228,6 +232,10 @@ def device_creator(home_data: HomeData, device: HomeDataDevice, product: HomeDat
         device_cache: DeviceCache = DeviceCache(device.duid, cache)
         match device.pv:
             case DeviceVersion.V1:
+                if product.category != RoborockCategory.VACUUM:
+                    raise UnsupportedDeviceError(
+                        f"Device {device.name} has unsupported V1 category {product.category}: {product.model}"
+                    )
                 channel = create_v1_channel(user_data, mqtt_params, mqtt_session, device, device_cache)
                 trait = v1.create(
                     device.duid,
@@ -236,6 +244,7 @@ def device_creator(home_data: HomeData, device: HomeDataDevice, product: HomeDat
                     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,
@@ -264,6 +273,12 @@ def device_creator(home_data: HomeData, device: HomeDataDevice, product: HomeDat
             dev.add_ready_callback(ready_callback)
         return dev
 
-    manager = DeviceManager(web_api, device_creator, mqtt_session=mqtt_session, cache=cache, diagnostics=diagnostics)
+    manager = DeviceManager(
+        web_api,
+        device_creator,
+        mqtt_session=mqtt_session,
+        cache=cache,
+        diagnostics=diagnostics,
+    )
     await manager.discover_devices(prefer_cache)
     return manager