Merge branch 'upstream/main' into decouple-b01-transport-layer

Author: allenporter

CHANGELOG.md

@@ -2,6 +2,158 @@
 
 <!-- version list -->
 
+## v5.25.0 (2026-07-03)
+
+### Chores
+
+- Add dataclasses for Roborock mower
+  ([#862](https://github.com/Python-roborock/python-roborock/pull/862),
+  [`413d6e5`](https://github.com/Python-roborock/python-roborock/commit/413d6e57ae74d3d54f9f1d4c8918ffbe9d215b7b))
+
+- Add some comments that better explain 'get_mop_only_vacuum_mode'
+  ([#817](https://github.com/Python-roborock/python-roborock/pull/817),
+  [`9474bfa`](https://github.com/Python-roborock/python-roborock/commit/9474bfaa607f15c7b66f520af17d81c849651f68))
+
+- Address comments ([#817](https://github.com/Python-roborock/python-roborock/pull/817),
+  [`9474bfa`](https://github.com/Python-roborock/python-roborock/commit/9474bfaa607f15c7b66f520af17d81c849651f68))
+
+- Address comments from copilot
+  ([#817](https://github.com/Python-roborock/python-roborock/pull/817),
+  [`9474bfa`](https://github.com/Python-roborock/python-roborock/commit/9474bfaa607f15c7b66f520af17d81c849651f68))
+
+- Apply suggestions from code review
+  ([#862](https://github.com/Python-roborock/python-roborock/pull/862),
+  [`413d6e5`](https://github.com/Python-roborock/python-roborock/commit/413d6e57ae74d3d54f9f1d4c8918ffbe9d215b7b))
+
+- Drop int typing and improve comment
+  ([#817](https://github.com/Python-roborock/python-roborock/pull/817),
+  [`9474bfa`](https://github.com/Python-roborock/python-roborock/commit/9474bfaa607f15c7b66f520af17d81c849651f68))
+
+### Features
+
+- Add better cleaning mode support
+  ([#817](https://github.com/Python-roborock/python-roborock/pull/817),
+  [`9474bfa`](https://github.com/Python-roborock/python-roborock/commit/9474bfaa607f15c7b66f520af17d81c849651f68))
+
+
+## v5.24.0 (2026-07-03)
+
+### Features
+
+- Implement dynamic map update listeners and filtering on HomeTrait
+  ([#861](https://github.com/Python-roborock/python-roborock/pull/861),
+  [`a793c8e`](https://github.com/Python-roborock/python-roborock/commit/a793c8e0a3e0359027d491d406dd36f2d62d41f6))
+
+
+## v5.23.1 (2026-07-03)
+
+### Bug Fixes
+
+- Verify MQTT connection requires successful subscription
+  ([#858](https://github.com/Python-roborock/python-roborock/pull/858),
+  [`e3c97c6`](https://github.com/Python-roborock/python-roborock/commit/e3c97c68ce5cf38022241bf85d68977c223b8922))
+
+### Documentation
+
+- Clarify is_mqtt_connected docstring with motivation
+  ([#858](https://github.com/Python-roborock/python-roborock/pull/858),
+  [`e3c97c6`](https://github.com/Python-roborock/python-roborock/commit/e3c97c68ce5cf38022241bf85d68977c223b8922))
+
+### Refactoring
+
+- Remove unused fixtures in tests
+  ([#858](https://github.com/Python-roborock/python-roborock/pull/858),
+  [`e3c97c6`](https://github.com/Python-roborock/python-roborock/commit/e3c97c68ce5cf38022241bf85d68977c223b8922))
+
+
+## v5.23.0 (2026-07-03)
+
+### Features
+
+- Add Q10 (B01/ss07) clean-record history trait
+  ([#857](https://github.com/Python-roborock/python-roborock/pull/857),
+  [`79a996d`](https://github.com/Python-roborock/python-roborock/commit/79a996de463a59ff4de875579a417d157e8cc2e8))
+
+- Q10 (B01/ss07) clean-record history trait
+  ([#857](https://github.com/Python-roborock/python-roborock/pull/857),
+  [`79a996d`](https://github.com/Python-roborock/python-roborock/commit/79a996de463a59ff4de875579a417d157e8cc2e8))
+
+### Refactoring
+
+- Call the static parse_record via the class, not self
+  ([#857](https://github.com/Python-roborock/python-roborock/pull/857),
+  [`79a996d`](https://github.com/Python-roborock/python-roborock/commit/79a996de463a59ff4de875579a417d157e8cc2e8))
+
+- Widen parse_record's parameter type to Any | None
+  ([#857](https://github.com/Python-roborock/python-roborock/pull/857),
+  [`79a996d`](https://github.com/Python-roborock/python-roborock/commit/79a996de463a59ff4de875579a417d157e8cc2e8))
+
+
+## v5.22.0 (2026-06-28)
+
+### Bug Fixes
+
+- Avoid Q10 Consumable/NetworkInfo shadowing v1 in roborock.data
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Correct Q10 vacuum command payloads, verified against ss07 hardware
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Keep Q10 CLIFF_RESTRICTED_AREA_UP (103); ss07 pushes it
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Show all Q10 read-model traits in status, wait for fresh push
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Stop unmapped Q10 data points from logging "not a valid code" warnings
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+### Features
+
+- Add Q10 (B01/ss07) settings writers
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Add Q10 dust-collection frequency writer
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Decode Q10 add_clean_state as a bool
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Decode Q10 carpet/area/mop/floor-direction status into enums+bools
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Expand Q10 (B01/ss07) status support and add device info
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Q10 (B01/ss07) room/segment cleaning
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Q10 (B01/ss07) room/segment cleaning (clean_segments)
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+### Refactoring
+
+- Split Q10 status/settings into per-concern traits
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+- Use YXDeviceCleanTask.ELECTORAL and inline misspelling note
+  ([#851](https://github.com/Python-roborock/python-roborock/pull/851),
+  [`e71611b`](https://github.com/Python-roborock/python-roborock/commit/e71611b2b57f2ca1dc1d2c42d6fce0d3f1b6169b))
+
+
 ## v5.21.0 (2026-06-25)
 
 ### Bug Fixes

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.21.0"
+version = "5.25.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/cli.py

@@ -1482,6 +1482,39 @@ async def q10_vacuum_spot(ctx: click.Context, device_id: str) -> None:
         click.echo(f"Error: {e}")
 
 
+@session.command()
+@click.option("--device_id", required=True, help="Device ID")
+@click.option(
+    "--segments",
+    required=True,
+    help="Comma-separated room/segment ids to clean (see the `rooms` command), e.g. 9,2",
+)
+@click.pass_context
+@async_command
+async def q10_clean_segments(ctx: click.Context, device_id: str, segments: str) -> None:
+    """Start a room / segment clean on a Q10 device.
+
+    Room ids come from the `rooms` command (the device's map rooms).
+    """
+    context: RoborockContext = ctx.obj
+    try:
+        segment_ids = [int(s) for s in segments.split(",") if s.strip()]
+    except ValueError:
+        click.echo("--segments must be comma-separated integers, e.g. 9,2")
+        return
+    if not segment_ids:
+        click.echo("No segment ids provided")
+        return
+    try:
+        trait = await _q10_vacuum_trait(context, device_id)
+        await trait.clean_segments(segment_ids)
+        click.echo(f"Starting room clean of segments {segment_ids}...")
+    except RoborockUnsupportedFeature:
+        click.echo("Device does not support B01 Q10 protocol. Is it a Q10?")
+    except RoborockException as e:
+        click.echo(f"Error: {e}")
+
+
 async def _q10_set(ctx: click.Context, device_id: str, apply: Callable[[Any], Any], message: str) -> None:
     """Run a Q10 settings write and report the result."""
     context: RoborockContext = ctx.obj

roborock/data/__init__.py

@@ -5,5 +5,6 @@
 from .code_mappings import *
 from .containers import *
 from .dyad import *
+from .mower import *
 from .v1 import *
 from .zeo import *

roborock/data/b01_q10/b01_q10_code_mappings.py

@@ -226,6 +226,43 @@ class YXDeviceCleanTask(RoborockModeEnum):
     PART = "part", 5
 
 
+class YXCleanScope(RoborockModeEnum):
+    """Clean scope/type as stored in a *clean record* (``dpCleanRecord``, field 7).
+
+    This is the same conceptual axis as the live :class:`YXDeviceCleanTask`, but the
+    persisted record uses a different integer encoding -- e.g. a full clean records
+    ``0`` here vs ``1`` (``smart``) live, and a select-rooms clean records ``1`` here
+    vs ``2`` (``electoral``) live. Ground-truthed against the app's History labels;
+    code ``2`` was never observed on ss07 and is intentionally unmapped (so it
+    resolves to ``None`` rather than a guessed label).
+    """
+
+    UNKNOWN = "unknown", -1
+    FULL = "full", 0
+    SELECTIVE_ROOM = "selective_room", 1
+    ZONE = "zone", 3
+    SPOT = "spot", 4
+
+
+class YXCleaningResult(RoborockModeEnum):
+    """How a clean ended, as stored in a clean record (``dpCleanRecord``, field 9)."""
+
+    UNKNOWN = "unknown", -1
+    INTERRUPTED = "interrupted", 0  # ended on a fault
+    COMPLETED = "completed", 1
+    STOPPED = "stopped", 2  # ended early without a fault
+
+
+class YXStartMethod(RoborockModeEnum):
+    """What initiated a clean, as stored in a clean record (``dpCleanRecord``, field 10)."""
+
+    UNKNOWN = "unknown", -1
+    REMOTE = "remote", 0
+    APP = "app", 1
+    TIMER = "timer", 2  # schedule / timer
+    BUTTON = "button", 3  # device button
+
+
 class YXDeviceDustCollectionFrequency(RoborockModeEnum):
     # The app exposes "regular" (code 0) vs "frequent", where "frequent" selects
     # one of the every-N-cleans intervals below.

roborock/data/b01_q10/b01_q10_containers.py

@@ -6,6 +6,7 @@
 automatically update objects from raw device responses.
 """
 
+import datetime
 from dataclasses import dataclass, field
 
 from ..containers import RoborockBase
@@ -14,12 +15,15 @@
     YXAreaUnit,
     YXBackType,
     YXCarpetCleanType,
+    YXCleaningResult,
     YXCleanLine,
+    YXCleanScope,
     YXCleanType,
     YXDeviceCleanTask,
     YXDeviceDustCollectionFrequency,
     YXDeviceState,
     YXFanLevel,
+    YXStartMethod,
     YXWaterLevel,
 )
 
@@ -32,6 +36,52 @@ class dpCleanRecord(RoborockBase):
     data: list
 
 
+@dataclass
+class Q10CleanRecord(RoborockBase):
+    """A single Q10 (ss07) clean record decoded from a ``dpCleanRecord`` (DP 52) entry.
+
+    The device returns each record as a 12-field underscore-delimited string in the
+    ``data`` list of a ``{"op": "list"}`` query (or the ``id`` of an ``{"op": "notify"}``
+    push). The ``*_len`` values are internal blob-length metrics whose units aren't
+    confirmed; the original ``raw`` string is always retained. The enum fields resolve
+    an unmapped/unset code to ``None`` rather than guessing.
+    """
+
+    raw: str
+    record_id: str | None = None
+    start_time: int | None = None
+    """Clean start time, Unix seconds."""
+    clean_time: int | None = None
+    """Cleaning time, minutes."""
+    clean_area: int | None = None
+    """Cleaned area in square meters."""
+    map_len: int | None = None
+    """Length of the saved map blob for this record (0 = none stored)."""
+    path_len: int | None = None
+    """Length of the saved path blob for this record (0 = none stored)."""
+    virtual_len: int | None = None
+    """Length of the saved virtual-restriction blob for this record (0 = none stored)."""
+    clean_mode: YXCleanScope | None = None
+    """Clean scope/type (full / selective-room / zone / spot). Same axis as the live
+    :class:`YXDeviceCleanTask` but a different record encoding -- see :class:`YXCleanScope`."""
+    work_mode: YXCleanType | None = None
+    """Actual work performed (vac+mop / vacuum / mop) -- the same enum :class:`Q10Status`
+    uses for the live clean-mode DP. Records only ever carry 1/2/3 here."""
+    cleaning_result: YXCleaningResult | None = None
+    """How the clean ended: 0 interrupted (fault), 1 completed, 2 stopped (no fault)."""
+    start_method: YXStartMethod | None = None
+    """What initiated the clean: 0 remote, 1 app, 2 timer, 3 button."""
+    collect_dust_count: int | None = None
+    """Number of dock auto-empties during the clean."""
+
+    @property
+    def start_datetime(self) -> datetime.datetime | None:
+        """The start time as a timezone-aware (UTC) datetime."""
+        if self.start_time is not None:
+            return datetime.datetime.fromtimestamp(self.start_time).astimezone(datetime.UTC)
+        return None
+
+
 @dataclass
 class dpMultiMap(RoborockBase):
     op: str

roborock/data/mower/__init__.py

@@ -0,0 +1,3 @@
+"""Dataclasses for Roborock mower devices."""
+
+from .mower_containers import *

roborock/data/mower/mower_containers.py

@@ -0,0 +1,43 @@
+"""Data containers for Roborock mower devices."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from roborock.data.containers import RoborockBase
+from roborock.roborock_message import RoborockMowerDataProtocol
+
+
+@dataclass
+class MowerStatus(RoborockBase):
+    """Core mower status backed by mower DPS updates."""
+
+    error_code: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.ERROR_CODE})
+    battery: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.BATTERY})
+    mow_type: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_TYPE})
+    mow_state: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_STATE})
+    mapping_type: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MAPPING_TYPE})
+    mapping_state: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MAPPING_STATE})
+    ota_state: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.OTA_STATE})
+    charge_state: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.CHARGE_STATE})
+    dock_state: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.DOCK_STATE})
+    charge_type: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.CHARGE_TYPE})
+    pend_type: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.PEND_TYPE})
+    remote_state: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.REMOTE_STATE})
+    mow_start_type: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_START_TYPE})
+    mow_eff_mode: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_EFF_MODE})
+    mow_height: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_HEIGHT})
+    mow_direction_angle: int | None = field(
+        default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_DIRECTION_ANGLE}
+    )
+    mow_pattern: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_PATTERN})
+    mow_conf_mode: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_CONF_MODE})
+    offline_status: Any | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.OFFLINE_STATUS})
+    mow_progress: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.MOW_PROGRESS})
+    blade_lifespan: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.BLADE_LIFESPAN})
+    fc_state: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.FC_STATE})
+    gps_coordinate: Any | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.GPS_COORDINATE})
+    off_dock_no_task_status: int | None = field(
+        default=None, metadata={"dps": RoborockMowerDataProtocol.OFF_DOCK_NO_TASK_STATUS}
+    )
+    afs_status: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.AFS_STATUS})
+    network_channel: int | None = field(default=None, metadata={"dps": RoborockMowerDataProtocol.NETWORK_CHANNEL})