Merge branch 'main' into repeat_and_route

Author: Lash-L

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 <!-- version list -->
 
+## v4.10.0 (2026-02-01)
+
+### Features
+
+- Add clean record for Q7 ([#745](https://github.com/Python-roborock/python-roborock/pull/745),
+  [`329e52b`](https://github.com/Python-roborock/python-roborock/commit/329e52bc34b1a5de2685b94002deae025eb0bd1c))
+
+
+## v4.9.1 (2026-02-01)
+
+### Bug Fixes
+
+- Correctly handle unknown categories
+  ([#755](https://github.com/Python-roborock/python-roborock/pull/755),
+  [`742a382`](https://github.com/Python-roborock/python-roborock/commit/742a38200e943a987285cc6979c7e7d5ca729117))
+
+
+## v4.9.0 (2026-02-01)
+
+### Features
+
+- Add VacuumTrait to q10 devices
+  ([#754](https://github.com/Python-roborock/python-roborock/pull/754),
+  [`69b6e0f`](https://github.com/Python-roborock/python-roborock/commit/69b6e0f58ce470f59a3d57756e6b4f760f3fd5a0))
+
+
 ## v4.8.0 (2026-01-27)
 
 ### Features

pyproject.toml

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

roborock/data/b01_q10/b01_q10_code_mappings.py

@@ -34,7 +34,7 @@ class B01_Q10_DP(RoborockModeEnum):
     DUST_SETTING = ("dpDustSetting", 50)
     MAP_SAVE_SWITCH = ("dpMapSaveSwitch", 51)
     CLEAN_RECORD = ("dpCleanRecord", 52)
-    RECEND_CLEAN_RECORD = ("dpRecendCleanRecord", 53)
+    RECENT_CLEAN_RECORD = ("dpRecentCleanRecord", 53)  # NOTE: typo "dpRecendCleanRecord" in source code
     RESTRICTED_ZONE = ("dpRestrictedZone", 54)
     RESTRICTED_ZONE_UP = ("dpRestrictedZoneUp", 55)
     VIRTUAL_WALL = ("dpVirtualWall", 56)
@@ -56,7 +56,7 @@ class B01_Q10_DP(RoborockModeEnum):
     ROOM_MERGE = ("dpRoomMerge", 72)
     ROOM_SPLIT = ("dpRoomSplit", 73)
     RESET_ROOM_NAME = ("dpResetRoomName", 74)
-    REQUSET_NOT_DISTURB_DATA = ("dpRequsetNotDisturbData", 75)
+    REQUEST_NOT_DISTURB_DATA = ("dpRequestNotDisturbData", 75)  # NOTE: typo "dpRequsetNotDisturbData" in source code
     CARPET_CLEAN_TYPE = ("dpCarpetCleanType", 76)
     BUTTON_LIGHT_SWITCH = ("dpButtonLightSwitch", 77)
     CLEAN_LINE = ("dpCleanLine", 78)
@@ -68,7 +68,7 @@ class B01_Q10_DP(RoborockModeEnum):
     LOG_SWITCH = ("dpLogSwitch", 84)
     FLOOR_MATERIAL = ("dpFloorMaterial", 85)
     LINE_LASER_OBSTACLE_AVOIDANCE = ("dpLineLaserObstacleAvoidance", 86)
-    CLEAN_PROGESS = ("dpCleanProgess", 87)
+    CLEAN_PROGRESS = ("dpCleanProgress", 87)  # NOTE: typo "dpCleanProgess" in source code
     GROUND_CLEAN = ("dpGroundClean", 88)
     IGNORE_OBSTACLE = ("dpIgnoreObstacle", 89)
     FAULT = ("dpFault", 90)
@@ -84,7 +84,7 @@ class B01_Q10_DP(RoborockModeEnum):
     SUSPECTED_THRESHOLD_UP = ("dpSuspectedThresholdUp", 100)
     COMMON = ("dpCommon", 101)
     JUMP_SCAN = ("dpJumpScan", 101)
-    REQUETDPS = ("dpRequetdps", 102)  # NOTE: THIS TYPO IS FOUND IN SOURCE CODE
+    REQUEST_DPS = ("dpRequestDps", 102)  # NOTE: typo "dpRequetdps" in source code
     CLIFF_RESTRICTED_AREA = ("dpCliffRestrictedArea", 102)
     CLIFF_RESTRICTED_AREA_UP = ("dpCliffRestrictedAreaUp", 103)
     BREAKPOINT_CLEAN = ("dpBreakpointClean", 104)
@@ -96,7 +96,7 @@ class B01_Q10_DP(RoborockModeEnum):
     HEARTBEAT = ("dpHeartbeat", 110)
     STATUS = ("dpStatus", 121)
     BATTERY = ("dpBattery", 122)
-    FUN_LEVEL = ("dpfunLevel", 123)
+    FAN_LEVEL = ("dpFanLevel", 123)  # NOTE: typo "dpfunLevel" in source code
     WATER_LEVEL = ("dpWaterLevel", 124)
     MAIN_BRUSH_LIFE = ("dpMainBrushLife", 125)
     SIDE_BRUSH_LIFE = ("dpSideBrushLife", 126)
@@ -125,7 +125,7 @@ class YXFanLevel(RoborockModeEnum):
     NORMAL = "normal", 2
     STRONG = "strong", 3
     MAX = "max", 4
-    SUPER = "super", 5
+    SUPER = "super", 8
 
 
 class YXWaterLevel(RoborockModeEnum):

roborock/data/b01_q7/b01_q7_containers.py

@@ -1,5 +1,9 @@
+import datetime
+import json
 from dataclasses import dataclass, field
+from functools import cached_property
 
+from ...exceptions import RoborockException
 from ..containers import RoborockBase
 from .b01_q7_code_mappings import (
     B01Fault,
@@ -217,3 +221,81 @@ def repeat_state_name(self) -> str | None:
     def clean_path_preference_name(self) -> str | None:
         """Returns the name of the current clean path preference."""
         return self.clean_path_preference.value if self.clean_path_preference is not None else None
+
+@dataclass
+class CleanRecordDetail(RoborockBase):
+    """Represents a single clean record detail (from `record_list[].detail`)."""
+
+    record_start_time: int | None = None
+    method: int | None = None
+    record_use_time: int | None = None
+    clean_count: int | None = None
+    # This is seemingly returned in meters (non-squared)
+    record_clean_area: int | None = None
+    record_clean_mode: int | None = None
+    record_clean_way: int | None = None
+    record_task_status: int | None = None
+    record_faultcode: int | None = None
+    record_dust_num: int | None = None
+    clean_current_map: int | None = None
+    record_map_url: str | None = None
+
+    @property
+    def start_datetime(self) -> datetime.datetime | None:
+        """Convert the start datetime into a datetime object."""
+        if self.record_start_time is not None:
+            return datetime.datetime.fromtimestamp(self.record_start_time).astimezone(datetime.UTC)
+        return None
+
+    @property
+    def square_meters_area_cleaned(self) -> float | None:
+        """Returns the area cleaned in square meters."""
+        if self.record_clean_area is not None:
+            return self.record_clean_area / 100
+        return None
+
+
+@dataclass
+class CleanRecordListItem(RoborockBase):
+    """Represents an entry in the clean record list returned by `service.get_record_list`."""
+
+    url: str | None = None
+    detail: str | None = None
+
+    @cached_property
+    def detail_parsed(self) -> CleanRecordDetail | None:
+        """Parse and return the detail as a CleanRecordDetail object."""
+        if self.detail is None:
+            return None
+        try:
+            parsed = json.loads(self.detail)
+        except json.JSONDecodeError as ex:
+            raise RoborockException(f"Invalid B01 record detail JSON: {self.detail!r}") from ex
+        return CleanRecordDetail.from_dict(parsed)
+
+
+@dataclass
+class CleanRecordList(RoborockBase):
+    """Represents the clean record list response from `service.get_record_list`."""
+
+    total_area: int | None = None
+    total_time: int | None = None  # stored in seconds
+    total_count: int | None = None
+    record_list: list[CleanRecordListItem] = field(default_factory=list)
+
+    @property
+    def square_meters_area_cleaned(self) -> float | None:
+        """Returns the area cleaned in square meters."""
+        if self.total_area is not None:
+            return self.total_area / 100
+        return None
+
+
+@dataclass
+class CleanRecordSummary(RoborockBase):
+    """Represents clean record totals for B01/Q7 devices."""
+
+    total_time: int | None = None
+    total_area: int | None = None
+    total_count: int | None = None
+    last_record_detail: CleanRecordDetail | None = None

roborock/data/code_mappings.py

@@ -77,7 +77,8 @@ def from_code(cls, code: int) -> Self:
         raise ValueError(message)
 
     @classmethod
-    def from_code_optional(cls, code: int) -> RoborockModeEnum | None:
+    def from_code_optional(cls, code: int) -> Self | None:
+        """Gracefully return None if the code does not exist."""
         try:
             return cls.from_code(code)
         except ValueError:
@@ -173,8 +174,10 @@ class RoborockCategory(Enum):
     WET_DRY_VAC = "roborock.wetdryvac"
     VACUUM = "robot.vacuum.cleaner"
     WASHING_MACHINE = "roborock.wm"
+    MOWER = "roborock.mower"
     UNKNOWN = "UNKNOWN"
 
-    def __missing__(self, key):
-        _LOGGER.warning("Missing key %s from category", key)
+    @classmethod
+    def _missing_(cls, value):
+        _LOGGER.warning("Missing code %s from category", value)
         return RoborockCategory.UNKNOWN

roborock/devices/traits/b01/q10/__init__.py

@@ -1,12 +1,10 @@
 """Traits for Q10 B01 devices."""
 
-from typing import Any
-
-from roborock.devices.rpc.b01_q7_channel import send_decoded_command
 from roborock.devices.traits import Trait
 from roborock.devices.transport.mqtt_channel import MqttChannel
 
 from .command import CommandTrait
+from .vacuum import VacuumTrait
 
 __all__ = [
     "Q10PropertiesApi",
@@ -19,9 +17,13 @@ class Q10PropertiesApi(Trait):
     command: CommandTrait
     """Trait for sending commands to Q10 devices."""
 
+    vacuum: VacuumTrait
+    """Trait for sending vacuum related commands to Q10 devices."""
+
     def __init__(self, channel: MqttChannel) -> None:
         """Initialize the B01Props API."""
         self.command = CommandTrait(channel)
+        self.vacuum = VacuumTrait(self.command)
 
 
 def create(channel: MqttChannel) -> Q10PropertiesApi:

roborock/devices/traits/b01/q10/vacuum.py

@@ -0,0 +1,56 @@
+"""Traits for Q10 B01 devices."""
+
+from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+
+from .command import CommandTrait
+
+
+class VacuumTrait:
+    """Trait for sending vacuum commands.
+
+    This is a wrapper around the CommandTrait for sending vacuum related
+    commands to Q10 devices.
+    """
+
+    def __init__(self, command: CommandTrait) -> None:
+        """Initialize the VacuumTrait."""
+        self._command = command
+
+    async def start_clean(self) -> None:
+        """Start cleaning."""
+        await self._command.send(
+            command=B01_Q10_DP.START_CLEAN,
+            # TODO: figure out other commands
+            # 1 = start cleaning
+            # 2 = "electoral" clean, also has "clean_parameters"
+            # 4 = fast create map
+            params={"cmd": 1},
+        )
+
+    async def pause_clean(self) -> None:
+        """Pause cleaning."""
+        await self._command.send(
+            command=B01_Q10_DP.PAUSE,
+            params={},
+        )
+
+    async def resume_clean(self) -> None:
+        """Resume cleaning."""
+        await self._command.send(
+            command=B01_Q10_DP.RESUME,
+            params={},
+        )
+
+    async def stop_clean(self) -> None:
+        """Stop cleaning."""
+        await self._command.send(
+            command=B01_Q10_DP.STOP,
+            params={},
+        )
+
+    async def return_to_dock(self) -> None:
+        """Return to dock."""
+        await self._command.send(
+            command=B01_Q10_DP.START_DOCK_TASK,
+            params={},
+        )

roborock/devices/traits/b01/q7/__init__.py

@@ -20,17 +20,24 @@
 from roborock.roborock_message import RoborockB01Props
 from roborock.roborock_typing import RoborockB01Q7Methods
 
+from .clean_summary import CleanSummaryTrait
+
 __all__ = [
     "Q7PropertiesApi",
+    "CleanSummaryTrait",
 ]
 
 
 class Q7PropertiesApi(Trait):
     """API for interacting with B01 devices."""
 
+    clean_summary: CleanSummaryTrait
+    """Trait for clean records / clean summary (Q7 `service.get_record_list`)."""
+
     def __init__(self, channel: MqttChannel) -> None:
         """Initialize the B01Props API."""
         self._channel = channel
+        self.clean_summary = CleanSummaryTrait(channel)
 
     async def query_values(self, props: list[RoborockB01Props]) -> B01Props | None:
         """Query the device for the values of the given Q7 properties."""

roborock/devices/traits/b01/q7/clean_summary.py

@@ -0,0 +1,75 @@
+"""Clean summary / clean records trait for B01 Q7 devices.
+
+For B01/Q7, the Roborock app uses `service.get_record_list` which returns totals
+and a `record_list` whose items contain a JSON string in `detail`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from roborock import CleanRecordDetail, CleanRecordList, CleanRecordSummary
+from roborock.devices.rpc.b01_q7_channel import send_decoded_command
+from roborock.devices.traits import Trait
+from roborock.devices.transport.mqtt_channel import MqttChannel
+from roborock.exceptions import RoborockException
+from roborock.protocols.b01_q7_protocol import Q7RequestMessage
+from roborock.roborock_typing import RoborockB01Q7Methods
+
+__all__ = [
+    "CleanSummaryTrait",
+]
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CleanSummaryTrait(CleanRecordSummary, Trait):
+    """B01/Q7 clean summary + clean record access (via record list service)."""
+
+    def __init__(self, channel: MqttChannel) -> None:
+        """Initialize the clean summary trait.
+
+        Args:
+            channel: MQTT channel used to communicate with the device.
+        """
+        super().__init__()
+        self._channel = channel
+
+    async def refresh(self) -> None:
+        """Refresh totals and last record detail from the device."""
+        record_list = await self._get_record_list()
+
+        self.total_time = record_list.total_time
+        self.total_area = record_list.total_area
+        self.total_count = record_list.total_count
+
+        details = await self._get_clean_record_details(record_list=record_list)
+        self.last_record_detail = details[0] if details else None
+
+    async def _get_record_list(self) -> CleanRecordList:
+        """Fetch the raw device clean record list (`service.get_record_list`)."""
+        result = await send_decoded_command(
+            self._channel,
+            Q7RequestMessage(dps=10000, command=RoborockB01Q7Methods.GET_RECORD_LIST, params={}),
+        )
+
+        if not isinstance(result, dict):
+            raise TypeError(f"Unexpected response type for GET_RECORD_LIST: {type(result).__name__}: {result!r}")
+        return CleanRecordList.from_dict(result)
+
+    async def _get_clean_record_details(self, *, record_list: CleanRecordList) -> list[CleanRecordDetail]:
+        """Return parsed record detail objects (newest-first)."""
+        details: list[CleanRecordDetail] = []
+        for item in record_list.record_list:
+            try:
+                parsed = item.detail_parsed
+            except RoborockException as ex:
+                # Rather than failing if something goes wrong here, we should fail and log to tell the user.
+                _LOGGER.debug("Failed to parse record detail: %s", ex)
+                continue
+            if parsed is not None:
+                details.append(parsed)
+
+        # The server returns the newest record at the end of record_list; reverse so newest is first (index 0).
+        details.reverse()
+        return details