Merge branch 'main' into agent/q7-map-layers

Author: tubededentifrice

CHANGELOG.md

@@ -2,6 +2,229 @@
 
 <!-- version list -->
 
+## v5.31.1 (2026-07-18)
+
+### Bug Fixes
+
+- Correct reset consumable parameters for strainer and cleaning brush
+  ([#879](https://github.com/Python-roborock/python-roborock/pull/879),
+  [`b11fc49`](https://github.com/Python-roborock/python-roborock/commit/b11fc4984445daa9a1837cef366d8543c3d1b7c8))
+
+### Chores
+
+- Add note about apache-II in CONTRIBUTING.md
+  ([#877](https://github.com/Python-roborock/python-roborock/pull/877),
+  [`a8a5821`](https://github.com/Python-roborock/python-roborock/commit/a8a582192b3ec1c74f9b56c83bda026bd6ec194b))
+
+
+## v5.31.0 (2026-07-15)
+
+### Features
+
+- Add Q10 integration test and support stream streaming on FakeChannel
+  ([#869](https://github.com/Python-roborock/python-roborock/pull/869),
+  [`502fa42`](https://github.com/Python-roborock/python-roborock/commit/502fa424c4a8fd36b759de8c8557c8665e4d0d13))
+
+- Implement Q10VacuumSimulator and export it
+  ([#869](https://github.com/Python-roborock/python-roborock/pull/869),
+  [`502fa42`](https://github.com/Python-roborock/python-roborock/commit/502fa424c4a8fd36b759de8c8557c8665e4d0d13))
+
+- Implement stateful Q10 device simulator and integration tests
+  ([#869](https://github.com/Python-roborock/python-roborock/pull/869),
+  [`502fa42`](https://github.com/Python-roborock/python-roborock/commit/502fa424c4a8fd36b759de8c8557c8665e4d0d13))
+
+
+## v5.30.0 (2026-07-13)
+
+### Bug Fixes
+
+- Gate dock_error_status on has_dock rather than is_collectable
+  ([#875](https://github.com/Python-roborock/python-roborock/pull/875),
+  [`86acd87`](https://github.com/Python-roborock/python-roborock/commit/86acd874e74c391d85c63483bee02a88b8a2debb))
+
+### Documentation
+
+- Document metadata keys in field_metadata and is_field_supported
+  ([#875](https://github.com/Python-roborock/python-roborock/pull/875),
+  [`86acd87`](https://github.com/Python-roborock/python-roborock/commit/86acd874e74c391d85c63483bee02a88b8a2debb))
+
+### Features
+
+- Implement device capability metadata for status computed property fields
+  ([#875](https://github.com/Python-roborock/python-roborock/pull/875),
+  [`86acd87`](https://github.com/Python-roborock/python-roborock/commit/86acd874e74c391d85c63483bee02a88b8a2debb))
+
+
+## v5.29.0 (2026-07-12)
+
+### Features
+
+- Truncate large payloads in RoborockMessage __repr__
+  ([#873](https://github.com/Python-roborock/python-roborock/pull/873),
+  [`95460d7`](https://github.com/Python-roborock/python-roborock/commit/95460d77a599613a0eddab3f4db7a36904f894d6))
+
+
+## v5.28.1 (2026-07-12)
+
+### Bug Fixes
+
+- Correct some dock mapping ([#872](https://github.com/Python-roborock/python-roborock/pull/872),
+  [`9e95992`](https://github.com/Python-roborock/python-roborock/commit/9e95992fcfceb70a0e73c86dc819cecc6dc572d1))
+
+### Refactoring
+
+- Use stateful fakes and fixtures in integration tests
+  ([#868](https://github.com/Python-roborock/python-roborock/pull/868),
+  [`89c8074`](https://github.com/Python-roborock/python-roborock/commit/89c80743e2c560f36f56e0c17c85c0d14544f406))
+
+
+## v5.28.0 (2026-07-08)
+
+### Features
+
+- Add better dock feature control
+  ([#867](https://github.com/Python-roborock/python-roborock/pull/867),
+  [`73ba2bf`](https://github.com/Python-roborock/python-roborock/commit/73ba2bf152d1c43b4d46d1e7f397043dd195d046))
+
+
+## v5.27.0 (2026-07-07)
+
+### Documentation
+
+- Add comment explaining dss field in v1_simulator
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+### Features
+
+- Add roborock.testing module for stateful integration testing
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Expose dock_type configuration in V1VacuumSimulator
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Expose in_cleaning, in_returning, charge_status, and dss on V1VacuumSimulator
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Honor publish_side_effect in simulator and raise NotImplementedError in base _handle_publish
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+### Refactoring
+
+- Decouple default product id from device duid and share DEFAULT_PRODUCT_ID constant
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Delete redundant properties from V1VacuumSimulator and update trigger_push_update
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Export and define all simulator state default constants at package level
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Expose raw status and app_init dataclasses on simulator for direct test manipulation
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Inherit FakeChannel from Channel Protocol
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Rename self.servers to self.simulated_devices and restore hardcoded qiCNieZa in mock_data
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Replace FakeUserState with library UserData dataclass on FakeRoborockCloud
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Type simulator consumables state using Consumable dataclass
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Type simulator dnd, clean summary and record using real dataclasses
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Type simulator status, network info and init status using real dataclasses
+  ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+- Update _handle_app_get_init_status to serialize self.app_init and dynamically resolve status_info
+  fields from self.status ([#860](https://github.com/Python-roborock/python-roborock/pull/860),
+  [`c963ad7`](https://github.com/Python-roborock/python-roborock/commit/c963ad79b7d7206dd1b97cd7f377305a67f90364))
+
+
+## v5.26.0 (2026-07-06)
+
+### Documentation
+
+- Add 569 back to the docstring's Q7-divergence list
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Mark fault 12 hw-confirmed (fired at 14% battery, corpus recount)
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Mark fault 2 hw-confirmed (bumper held during commanded motion)
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Mark fault 407 hw-confirmed (deterministically reproduced: due schedule ignored mid-clean)
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Mark fault 46 hw-confirmed (docked with dust bag removed)
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Mark fault 5 hw-confirmed (physically ground-truthed brush jams)
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Note fault 501 fires per completed task
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Note the error state can carry no fault code (observed live)
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Refer to the ss07 fault spec, not the app (review feedback)
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+### Features
+
+- Decode Q10 (B01/ss07) dpFault codes into a YXFault map
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Decode Q10 (B01/ss07) dpFault codes with a YXFault enum
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+- Re-add fault 569 as too_frequent_emptying, hw-confirmed (dock refuses a too-soon empty)
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+### Refactoring
+
+- Decouple B01 (Q7/Q10) protocol layer from transport layer
+  ([#859](https://github.com/Python-roborock/python-roborock/pull/859),
+  [`b00d60b`](https://github.com/Python-roborock/python-roborock/commit/b00d60b9f70d6a5da9089e470db60b04437c0b14))
+
+- Type Q10Status.fault as YXFault, mirroring the Q7 fault field
+  ([#863](https://github.com/Python-roborock/python-roborock/pull/863),
+  [`32f9747`](https://github.com/Python-roborock/python-roborock/commit/32f9747b368c4d58a78691a0106a8c9676a07e2c))
+
+
 ## v5.25.0 (2026-07-03)
 
 ### Chores

CONTRIBUTING.md

@@ -2,6 +2,16 @@
 
 Thank you for your interest in contributing to `python-roborock`! We welcome contributions from the community.
 
+## Licensing of Contributions
+
+By submitting a contribution to this repository, you agree that your contribution is
+licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0),
+and you certify that you have the right to submit it under that license.
+
+Note: the project is currently distributed under GPL-3.0 while we complete a planned
+migration to Apache 2.0. Apache 2.0 is GPL-compatible, so contributions made under
+Apache 2.0 can be included today and will carry over unchanged after the migration.
+
 ## Getting Started
 
 1.  **Fork the repository** on GitHub.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.25.0"
+version = "5.31.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"
@@ -52,6 +52,8 @@ dev = [
     # Pull in the CLI dependencies so maintainers can run the `roborock`
     # command and pdoc can import roborock.cli for docs generation.
     "python-roborock[cli]",
+    # aioresponses is not compatible with aiohttp 3.14 yet. https://github.com/pnuckowski/aioresponses/issues/289
+    "aiohttp>=3.8.2,<3.14",
     "pytest-asyncio>=1.1.0",
     "pytest",
     "pre-commit>=3.5,<5.0",

roborock/data/b01_q10/b01_q10_code_mappings.py

@@ -289,6 +289,70 @@ class YXCarpetCleanType(RoborockModeEnum):
     CROSS = "cross", 3
 
 
+class YXFault(RoborockModeEnum):
+    """Q10 (B01/ss07) ``dpFault`` (90) codes, from the ss07 fault spec.
+
+    ``dpFault`` is *overloaded*: several values are lifecycle/status rather than
+    errors (e.g. 400 = scheduled clean starting, 501 = returning to dock,
+    502 = recharge). A non-zero fault is not necessarily a blocking error.
+    The converse also holds: the device can sit in its error state (``dpStatus``
+    12) with ``dpFault`` still 0 (observed live with the dust-bin module
+    removed), so a ``None``/``NONE`` fault does not imply the absence of an
+    error condition.
+
+    These labels differ from the Q7 ``B01Fault`` for several shared numbers
+    (500, 501, 503, 569, 570) -- so this is a Q10-specific map, not a reuse of
+    ``B01Fault``. Codes marked "hw-confirmed" were observed firing live on a
+    physical ss07 in a context matching the label; the rest are from the spec
+    only, not yet observed live (single device).
+    """
+
+    UNKNOWN = "unknown", -1
+    NONE = "none", 0
+    LIDAR_BLOCKED = "lidar_blocked", 1
+    BUMPER_STUCK = "bumper_stuck", 2  # hw-confirmed (bumper held in during commanded motion)
+    ROBOT_SUSPENDED = "robot_suspended", 3  # hw-confirmed (wheels lifted off the floor mid-task)
+    CLIFF_SENSOR_ERROR = "cliff_sensor_error", 4  # hw-confirmed (one side lifted mid-task)
+    MAIN_BRUSH_STUCK = "main_brush_stuck", 5  # hw-confirmed (two physical brush jams)
+    MAIN_WHEELS_STUCK = "main_wheels_stuck", 7
+    ROBOT_TRAPPED = "robot_trapped", 8  # hw-confirmed
+    CHECK_DUSTBIN_FILTER = "check_dustbin_filter", 9
+    LOW_BATTERY = "low_battery", 12  # hw-confirmed (fired at 14% mid clean)
+    TEMPERATURE_THRESHOLD = "temperature_threshold", 14
+    ROBOT_TILTED = "robot_tilted", 16
+    LIDAR_COVER_OBSTRUCTED = "lidar_cover_obstructed", 21
+    NO_GO_ZONE_DETECTED = "no_go_zone_detected", 24
+    MOPPING_MODULE_STUCK = "mopping_module_stuck", 27
+    CARPET_AVOIDANCE = "carpet_avoidance", 28
+    CANNOT_CROSS_CARPET = "cannot_cross_carpet", 29
+    INSTALL_DUST_BAG = "install_dust_bag", 46  # hw-confirmed (docked with bag removed; fires at dock contact)
+    MOP_MOUNT_FELL_OFF = "mop_mount_fell_off", 54
+    LIDAR_DIRTY = "lidar_dirty", 58
+    FILTER_SERVICE_LIFE = "filter_service_life", 301
+    MAIN_BRUSH_SERVICE_LIFE = "main_brush_service_life", 302
+    SIDE_BRUSH_SERVICE_LIFE = "side_brush_service_life", 303
+    SENSOR_NEEDS_CLEANING = "sensor_needs_cleaning", 304  # hw-confirmed (fired during auto-empty)
+    DUST_BAG_FULL = "dust_bag_full", 310  # inferred from auto-empty context; not hw-confirmed
+    STARTING_SCHEDULED_CLEAN = "starting_scheduled_clean", 400  # hw-confirmed x3; lifecycle, not an error
+    # hw-confirmed (a due scheduled clean fired mid-clean and was ignored); lifecycle, not an error
+    CLEANING_IN_PROGRESS = "cleaning_in_progress", 407
+    EMPTY_DUSTBIN = "empty_dustbin", 500  # ss07 != Q7 B01Fault (lidar_blocked); spec-only
+    # hw-confirmed, fires per completed task; ss07 != Q7 (robot_suspended)
+    CLEANING_COMPLETED_RETURNING = "cleaning_completed_returning", 501
+    LOW_BATTERY_RESUME = "low_battery_resume", 502  # hw-confirmed; lifecycle
+    DOCKING_ERROR = "docking_error", 503  # hw-confirmed; ss07 != Q7 (dustbin_not_installed)
+    POSITIONING_FAILED = "positioning_failed", 556  # hw-confirmed; relocalization
+    # hw-confirmed (3rd auto-empty in ~15 min: dock refuses to run the cycle); ss07 != Q7 (main_wheels_entangled)
+    TOO_FREQUENT_EMPTYING = "too_frequent_emptying", 569
+    CANNOT_REACH_TARGET = "cannot_reach_target", 570  # hw-confirmed; ss07 != Q7 (main_brush_entangled)
+    OFFLINE_WARNING_ASLEEP = "offline_warning_asleep", 588
+    OFFLINE_WARNING_LOW_BATTERY = "offline_warning_low_battery", 589
+    DND_AUTO_TOPUP_DISABLED = "dnd_auto_topup_disabled", 591
+    CLEAN_CARPET_ULTRASONIC_SENSORS = "clean_carpet_ultrasonic_sensors", 707
+    ROBOT_ERROR_RESET = "robot_error_reset", 1002
+    VOICE_PACK_UPDATE_AVAILABLE = "voice_pack_update_available", 3001
+
+
 class RemoteCommand(IntEnum):
     FORWARD = 0
     LEFT = 2

roborock/data/b01_q10/b01_q10_containers.py

@@ -23,6 +23,7 @@
     YXDeviceDustCollectionFrequency,
     YXDeviceState,
     YXFanLevel,
+    YXFault,
     YXStartMethod,
     YXWaterLevel,
 )
@@ -165,7 +166,7 @@ class Q10Status(RoborockBase):
     clean_task_type: YXDeviceCleanTask | None = field(default=None, metadata={"dps": B01_Q10_DP.CLEAN_TASK_TYPE})
     back_type: YXBackType | None = field(default=None, metadata={"dps": B01_Q10_DP.BACK_TYPE})
     cleaning_progress: int | None = field(default=None, metadata={"dps": B01_Q10_DP.CLEAN_PROGRESS})
-    fault: int | None = field(default=None, metadata={"dps": B01_Q10_DP.FAULT})
+    fault: YXFault | None = field(default=None, metadata={"dps": B01_Q10_DP.FAULT})
 
     # Additional state reported in the device's full status dump.
     clean_line: YXCleanLine | None = field(default=None, metadata={"dps": B01_Q10_DP.CLEAN_LINE})
@@ -203,6 +204,11 @@ class Q10Status(RoborockBase):
     filter_life: int | None = field(default=None, metadata={"dps": B01_Q10_DP.FILTER_LIFE})
     sensor_life: int | None = field(default=None, metadata={"dps": B01_Q10_DP.SENSOR_LIFE})
 
+    @property
+    def fault_name(self) -> str | None:
+        """Returns the name of the current fault."""
+        return self.fault.value if self.fault is not None else None
+
 
 @dataclass
 class SoundVolume(RoborockBase):

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."""