Merge branch 'main' into dynamic_status_trait

Author: Lash-L

CHANGELOG.md

@@ -2,6 +2,143 @@
 
 <!-- version list -->
 
+## v4.4.0 (2026-01-12)
+
+### Features
+
+- Iterate possible iot domains on 3030 error
+  ([#733](https://github.com/Python-roborock/python-roborock/pull/733),
+  [`f2e1d51`](https://github.com/Python-roborock/python-roborock/commit/f2e1d5156dd905e296d5ed38605d4fd6f97bfbb4))
+
+
+## v4.3.0 (2026-01-10)
+
+### Chores
+
+- Add function to create field metadata
+  ([#740](https://github.com/Python-roborock/python-roborock/pull/740),
+  [`bdc1591`](https://github.com/Python-roborock/python-roborock/commit/bdc159192cfb2afa02199171288a20b228abb7f6))
+
+- Simplify supported_schema_codes
+  ([#740](https://github.com/Python-roborock/python-roborock/pull/740),
+  [`bdc1591`](https://github.com/Python-roborock/python-roborock/commit/bdc159192cfb2afa02199171288a20b228abb7f6))
+
+- Update pydoc for DeviceFeaturesTrait
+  ([#740](https://github.com/Python-roborock/python-roborock/pull/740),
+  [`bdc1591`](https://github.com/Python-roborock/python-roborock/commit/bdc159192cfb2afa02199171288a20b228abb7f6))
+
+- Update test descrition ([#740](https://github.com/Python-roborock/python-roborock/pull/740),
+  [`bdc1591`](https://github.com/Python-roborock/python-roborock/commit/bdc159192cfb2afa02199171288a20b228abb7f6))
+
+- Update to use StrEnum ([#740](https://github.com/Python-roborock/python-roborock/pull/740),
+  [`bdc1591`](https://github.com/Python-roborock/python-roborock/commit/bdc159192cfb2afa02199171288a20b228abb7f6))
+
+### Features
+
+- Add an approach for determining if a dataclass field is supported
+  ([#740](https://github.com/Python-roborock/python-roborock/pull/740),
+  [`bdc1591`](https://github.com/Python-roborock/python-roborock/commit/bdc159192cfb2afa02199171288a20b228abb7f6))
+
+
+## v4.2.2 (2026-01-09)
+
+### Bug Fixes
+
+- Decrease home data rate limits
+  ([#741](https://github.com/Python-roborock/python-roborock/pull/741),
+  [`29eb984`](https://github.com/Python-roborock/python-roborock/commit/29eb984d22494b08f26ec6e220b7c823b67d3242))
+
+### Chores
+
+- Add additional Home data to diagnostics
+  ([#723](https://github.com/Python-roborock/python-roborock/pull/723),
+  [`c29dfc8`](https://github.com/Python-roborock/python-roborock/commit/c29dfc81f4de1bb293b2918482cf681197ef3698))
+
+- Add CONTRIBUTING.md ([#734](https://github.com/Python-roborock/python-roborock/pull/734),
+  [`881b7d6`](https://github.com/Python-roborock/python-roborock/commit/881b7d687789c57eec20bf9011a195b4befff129))
+
+- Add CONTRIBUTINGmd ([#734](https://github.com/Python-roborock/python-roborock/pull/734),
+  [`881b7d6`](https://github.com/Python-roborock/python-roborock/commit/881b7d687789c57eec20bf9011a195b4befff129))
+
+- Add s5e device and product data examples
+  ([#737](https://github.com/Python-roborock/python-roborock/pull/737),
+  [`586bb3f`](https://github.com/Python-roborock/python-roborock/commit/586bb3f77e4655d4aae2d201746980b1c227160d))
+
+- Add Saros 10R API response data
+  ([#726](https://github.com/Python-roborock/python-roborock/pull/726),
+  [`fafc8d8`](https://github.com/Python-roborock/python-roborock/commit/fafc8d86833a2aac3ee69c7a1f353f83551eeb6f))
+
+- Fix diagnostic lint issues ([#723](https://github.com/Python-roborock/python-roborock/pull/723),
+  [`c29dfc8`](https://github.com/Python-roborock/python-roborock/commit/c29dfc81f4de1bb293b2918482cf681197ef3698))
+
+- Fix mock data lint ([#726](https://github.com/Python-roborock/python-roborock/pull/726),
+  [`fafc8d8`](https://github.com/Python-roborock/python-roborock/commit/fafc8d86833a2aac3ee69c7a1f353f83551eeb6f))
+
+- Fix schema redaction ([#723](https://github.com/Python-roborock/python-roborock/pull/723),
+  [`c29dfc8`](https://github.com/Python-roborock/python-roborock/commit/c29dfc81f4de1bb293b2918482cf681197ef3698))
+
+- Improve redaction logic to support more complex paths
+  ([#723](https://github.com/Python-roborock/python-roborock/pull/723),
+  [`c29dfc8`](https://github.com/Python-roborock/python-roborock/commit/c29dfc81f4de1bb293b2918482cf681197ef3698))
+
+- Remove duplicate data in test_q7_device
+  ([#736](https://github.com/Python-roborock/python-roborock/pull/736),
+  [`cd6cbbe`](https://github.com/Python-roborock/python-roborock/commit/cd6cbbe1be22a619a88d76783c60c936dbbc744d))
+
+- Update device snapshots and lint errors
+  ([#723](https://github.com/Python-roborock/python-roborock/pull/723),
+  [`c29dfc8`](https://github.com/Python-roborock/python-roborock/commit/c29dfc81f4de1bb293b2918482cf681197ef3698))
+
+- Update e2e tests for q7 to use different product data
+  ([#736](https://github.com/Python-roborock/python-roborock/pull/736),
+  [`cd6cbbe`](https://github.com/Python-roborock/python-roborock/commit/cd6cbbe1be22a619a88d76783c60c936dbbc744d))
+
+- Update end to end q7 tests ([#736](https://github.com/Python-roborock/python-roborock/pull/736),
+  [`cd6cbbe`](https://github.com/Python-roborock/python-roborock/commit/cd6cbbe1be22a619a88d76783c60c936dbbc744d))
+
+- Update steps to activate virtual environment
+  ([#734](https://github.com/Python-roborock/python-roborock/pull/734),
+  [`881b7d6`](https://github.com/Python-roborock/python-roborock/commit/881b7d687789c57eec20bf9011a195b4befff129))
+
+- Use built-in as_dict method for creating diagnostic data
+  ([#723](https://github.com/Python-roborock/python-roborock/pull/723),
+  [`c29dfc8`](https://github.com/Python-roborock/python-roborock/commit/c29dfc81f4de1bb293b2918482cf681197ef3698))
+
+
+## v4.2.1 (2026-01-05)
+
+### Bug Fixes
+
+- Bump aiomqtt ([#730](https://github.com/Python-roborock/python-roborock/pull/730),
+  [`21af4f3`](https://github.com/Python-roborock/python-roborock/commit/21af4f30412d96eb5ac53f372b74b0e03ca6580e))
+
+### Chores
+
+- Add a01 and b01 q7 byte level tests
+  ([#724](https://github.com/Python-roborock/python-roborock/pull/724),
+  [`f20ade9`](https://github.com/Python-roborock/python-roborock/commit/f20ade97843241aa286405c4eacbb9f1939cbdf3))
+
+- Add docs for v1 device features
+  ([#727](https://github.com/Python-roborock/python-roborock/pull/727),
+  [`f031acf`](https://github.com/Python-roborock/python-roborock/commit/f031acffa2381c2eb9e4af6fbf7967ae22b1d7dc))
+
+- Documentation cleanup and updates
+  ([#725](https://github.com/Python-roborock/python-roborock/pull/725),
+  [`bbeb0d9`](https://github.com/Python-roborock/python-roborock/commit/bbeb0d95e11274bd024cfac23988f01acf814888))
+
+- Remove empty line in device features documentation
+  ([#727](https://github.com/Python-roborock/python-roborock/pull/727),
+  [`f031acf`](https://github.com/Python-roborock/python-roborock/commit/f031acffa2381c2eb9e4af6fbf7967ae22b1d7dc))
+
+- Remove some information from the summart
+  ([#727](https://github.com/Python-roborock/python-roborock/pull/727),
+  [`f031acf`](https://github.com/Python-roborock/python-roborock/commit/f031acffa2381c2eb9e4af6fbf7967ae22b1d7dc))
+
+- Restructure the channel modules
+  ([#728](https://github.com/Python-roborock/python-roborock/pull/728),
+  [`9fcc0a8`](https://github.com/Python-roborock/python-roborock/commit/9fcc0a8ca075097b7d903a57cc0fc33ed149bd97))
+
+
 ## v4.2.0 (2025-12-30)
 
 ### Chores

CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to python-roborock
+
+Thank you for your interest in contributing to `python-roborock`! We welcome contributions from the community.
+
+## Getting Started
+
+1.  **Fork the repository** on GitHub.
+2.  **Clone your fork** locally:
+    ```bash
+    git clone https://github.com/your-username/python-roborock.git
+    cd python-roborock
+    ```
+3.  **Set up your environment**. This project typically tries to stay on the most recent python versions (e.g. latest 2 or 3 versions). We use `uv` for dependency management:
+    ```bash
+    # Create virtual environment and install dependencies
+    uv venv
+    uv sync
+    ```
+4.  **Activate the virtual environment**. This is required for running `pre-commit` hooks and `pytest`:
+    ```bash
+    source .venv/bin/activate
+    ```
+
+5.  **Install pre-commit hooks**. This ensures your code meets our quality standards. Once installed, these hooks run automatically on staged files when you commit:
+    ```bash
+    pre-commit install
+    ```
+
+## Development Workflow
+
+### Code Style
+
+We use several tools to enforce code quality and consistency. These are configured via `pre-commit` and generally run automatically.
+
+*   **Ruff**: Used for linting and formatting.
+*   **Mypy**: Used for static type checking.
+*   **Codespell**: Checks for common misspellings.
+
+You can verify your changes manually before committing (checks all files):
+
+```bash
+# Run all pre-commit hooks
+pre-commit run --all-files
+```
+
+### Testing
+
+We use `pytest` for testing. Please ensure all tests pass and add new tests for your changes.
+
+```bash
+# Run tests
+pytest
+```
+
+## Pull Requests
+
+1.  **Create a branch** for your changes.
+2.  **Make your changes**. Keep your changes focused and atomic.
+3.  **Commit your changes**.
+    *   **Important**: We use [Conventional Commits](https://www.conventionalcommits.org/). Please format your commit messages accordingly (e.g., `feat: add new vacuum model`, `fix: handle connection timeout`). This is required for our automated release process.
+    *   Allowed types: `chore`, `docs`, `feat`, `fix`, `refactor`.
+4.  **Push to your fork** and submit a **Pull Request**.
+
+## Adding New Devices or Features
+
+If you are adding support for a new device or feature, please follow these steps:
+
+1.  **Update Device Info**: Use the CLI to discover and fetch device features.
+    ```bash
+    roborock get-device-info
+    ```
+    Arguments and output will be printed to the console. **Manually copy the YAML output** from this command into the `device_info.yaml` file.
+
+2.  **Add Test Data**:
+    *   **Home API Data**: Capture device information from Home API responses and save as `tests/testdata/home_data_<device>.json`. This helps test device discovery and initialization.
+    *   **Protocol/Feature Data**: Capture actual device responses or protocol data. You can often see these messages in the DEBUG logs when interacting with the device. Create JSON files in `tests/protocols/testdata/` that reflect these responses. This ensures protocol parsing works correctly against real-world data.
+
+## Code of Conduct
+
+Please be respectful and considerate in your interactions.

docs/DEVICES.md

@@ -564,30 +564,40 @@ The new design:
 ```
 roborock/
 ├── devices/                    # Device management and channels
-│   ├── device_manager.py      # High-level device lifecycle
-│   ├── channel.py             # Base Channel interface
-│   ├── mqtt_channel.py        # MQTT channel implementation
-│   ├── local_channel.py       # Local TCP channel implementation
-│   ├── v1_channel.py          # V1 protocol channel with RPC strategies
-│   ├── a01_channel.py         # A01 protocol helpers
-│   ├── b01_q7_channel.py      # B01 Q7 protocol helpers
-│   └── traits/                # Device-specific command traits
-│       └── v1/                # V1 device traits
-│           ├── __init__.py    # Trait initialization
-│           ├── clean.py       # Cleaning commands
-│           ├── map.py         # Map management
+│   ├── device_manager.py       # High-level device lifecycle
+│   ├── transport/              # Module for network connections to devices
+│   |   ├── channel.py          # Base Channel interface
+│   |   ├── mqtt_channel.py     # MQTT channel implementation
+│   |   ├── local_channel.py    # Local TCP channel implementation
+│   |   └── ...
+│   ├── rpc/                    # Application-level protocol/device-specific glue
+│   |   ├── v1_channel.py       # V1 protocol channel with RPC strategies
+│   |   ├── a01_channel.py      # A01 protocol helpers
+│   |   ├── b01_q7_channel.py   # B01 Q7 protocol helpers
+│   |   ├── b01_q10_channel.py  # B01 Q10 protocol helpers
+│   |   └── ...
+│   └── traits/                 # High-level device-specific command traits
+│       └── v1/                 # V1 device traits
+│           ├── __init__.py     # Trait initialization
+│           ├── clean.py        # Cleaning commands
+│           ├── map.py          # Map management
 │           └── ...
-├── mqtt/                       # MQTT session management
+├── mqtt/                      # MQTT session management
 │   ├── session.py             # Base session interface
 │   └── roborock_session.py    # MQTT session with idle timeout
-├── protocols/                  # Protocol encoders/decoders
+├── protocols/                 # Low level protocol encoders/decoders
 │   ├── v1_protocol.py         # V1 JSON RPC protocol
 │   ├── a01_protocol.py        # A01 protocol
 │   ├── b01_q7_protocol.py     # B01 Q7 protocol
 │   └── ...
-└── data/                       # Data containers and mappings
+└── data/                      # Data containers and mappings
     ├── containers.py          # Status, HomeData, etc.
-    └── v1/                    # V1-specific data structures
+    ├── v1/                    # V1-specific data structures
+    ├── dyad/                  # Dyad-specific data structures
+    ├── zeo/                   # Zeo-specific data structures
+    ├── b01_q7/                # B01 Q7-specific data structures
+    ├── b01_q10/               # B01 Q10-specific data structures
+    └── ...
 ```
 
 ### Threading Model

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "4.2.0"
+version = "4.4.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"
@@ -27,7 +27,7 @@ dependencies = [
     "construct>=2.10.57,<3",
     "vacuum-map-parser-roborock",
     "pyrate-limiter>=3.7.0,<4",
-    "aiomqtt>=2.3.2,<3",
+    "aiomqtt>=2.5.0,<3",
     "click-shell~=2.1",
 ]
 

roborock/data/containers.py

@@ -232,6 +232,13 @@ def summary_info(self) -> str:
         """Return a string with key product information for logging purposes."""
         return f"{self.name} (model={self.model}, category={self.category})"
 
+    @cached_property
+    def supported_schema_codes(self) -> set[str]:
+        """Return a set of fields that are supported by the device."""
+        if self.schema is None:
+            return set()
+        return {schema.code for schema in self.schema if schema.code is not None}
+
 
 @dataclass
 class HomeDataDevice(RoborockBase):

roborock/data/v1/v1_containers.py

@@ -1,6 +1,7 @@
 import datetime
 import logging
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from enum import StrEnum
 from typing import Any
 
 from roborock.const import (
@@ -91,14 +92,41 @@
 _LOGGER = logging.getLogger(__name__)
 
 
+class FieldNameBase(StrEnum):
+    """A base enum class that represents a field name in a RoborockBase dataclass."""
+
+
+class StatusField(FieldNameBase):
+    """An enum that represents a field in the `Status` 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 `requires_schema_code` metadata to map the field to a schema
+    code in the product schema, which may have a different name than the field/attribute name.
+    """
+
+    STATE = "state"
+    BATTERY = "battery"
+    FAN_POWER = "fan_power"
+    WATER_BOX_MODE = "water_box_mode"
+    CHARGE_STATUS = "charge_status"
+    DRY_STATUS = "dry_status"
+
+
+def _requires_schema_code(requires_schema_code: str, default=None) -> Any:
+    return field(metadata={"requires_schema_code": requires_schema_code}, default=default)
+
+
 @dataclass
 class Status(RoborockBase):
     """This status will be depreciated in favor of StatusV2."""
 
     msg_ver: int | None = None
     msg_seq: int | None = None
-    state: RoborockStateCode | None = None
-    battery: int | None = None
+    state: RoborockStateCode | None = _requires_schema_code("state", default=None)
+    battery: int | None = _requires_schema_code("battery", default=None)
     clean_time: int | None = None
     clean_area: int | None = None
     error_code: RoborockErrorCode | None = None
@@ -111,12 +139,12 @@ class Status(RoborockBase):
     back_type: int | None = None
     wash_phase: int | None = None
     wash_ready: int | None = None
-    fan_power: RoborockFanPowerCode | None = None
+    fan_power: RoborockFanPowerCode | None = _requires_schema_code("fan_power", default=None)
     dnd_enabled: int | None = None
     map_status: int | None = None
     is_locating: int | None = None
     lock_status: int | None = None
-    water_box_mode: RoborockMopIntensityCode | None = None
+    water_box_mode: RoborockMopIntensityCode | None = _requires_schema_code("water_box_mode", default=None)
     water_box_carriage_status: int | None = None
     mop_forbidden_enable: int | None = None
     camera_status: int | None = None
@@ -134,13 +162,13 @@ 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 = None
+    charge_status: int | None = _requires_schema_code("charge_status", default=None)
     unsave_map_reason: int | None = None
     unsave_map_flag: int | None = None
     wash_status: int | None = None
     distance_off: int | None = None
     in_warmup: int | None = None
-    dry_status: int | None = None
+    dry_status: int | None = _requires_schema_code("drying_status", default=None)
     rdt: int | None = None
     clean_percent: int | None = None
     rss: int | None = None