Merge branch 'main' into trait-updates

Author: allenporter

CHANGELOG.md

@@ -2,6 +2,62 @@
 
 <!-- version list -->
 
+## v3.8.0 (2025-11-15)
+
+### Bug Fixes
+
+- Update roborock/devices/device.py
+  ([#588](https://github.com/Python-roborock/python-roborock/pull/588),
+  [`3994110`](https://github.com/Python-roborock/python-roborock/commit/39941103fe5247a9764d38db5ee0915dd39e043d))
+
+### Chores
+
+- Fix lint ([#589](https://github.com/Python-roborock/python-roborock/pull/589),
+  [`fa69bf2`](https://github.com/Python-roborock/python-roborock/commit/fa69bf2d9d090bf8bc6cf89ead6ab122d5dbcd00))
+
+- Fix lint errors ([#588](https://github.com/Python-roborock/python-roborock/pull/588),
+  [`3994110`](https://github.com/Python-roborock/python-roborock/commit/39941103fe5247a9764d38db5ee0915dd39e043d))
+
+- Update comments to clarify close call
+  ([#588](https://github.com/Python-roborock/python-roborock/pull/588),
+  [`3994110`](https://github.com/Python-roborock/python-roborock/commit/39941103fe5247a9764d38db5ee0915dd39e043d))
+
+- Update documentation to point to the newer device APIs
+  ([#589](https://github.com/Python-roborock/python-roborock/pull/589),
+  [`fa69bf2`](https://github.com/Python-roborock/python-roborock/commit/fa69bf2d9d090bf8bc6cf89ead6ab122d5dbcd00))
+
+- Update pydoc and formatting ([#588](https://github.com/Python-roborock/python-roborock/pull/588),
+  [`3994110`](https://github.com/Python-roborock/python-roborock/commit/39941103fe5247a9764d38db5ee0915dd39e043d))
+
+- Update README.md ([#589](https://github.com/Python-roborock/python-roborock/pull/589),
+  [`fa69bf2`](https://github.com/Python-roborock/python-roborock/commit/fa69bf2d9d090bf8bc6cf89ead6ab122d5dbcd00))
+
+- Update roborock/devices/device.py
+  ([#588](https://github.com/Python-roborock/python-roborock/pull/588),
+  [`3994110`](https://github.com/Python-roborock/python-roborock/commit/39941103fe5247a9764d38db5ee0915dd39e043d))
+
+- Update roborock/devices/traits/b01/__init__.py
+  ([#589](https://github.com/Python-roborock/python-roborock/pull/589),
+  [`fa69bf2`](https://github.com/Python-roborock/python-roborock/commit/fa69bf2d9d090bf8bc6cf89ead6ab122d5dbcd00))
+
+- Update roborock/devices/traits/v1/__init__.py
+  ([#589](https://github.com/Python-roborock/python-roborock/pull/589),
+  [`fa69bf2`](https://github.com/Python-roborock/python-roborock/commit/fa69bf2d9d090bf8bc6cf89ead6ab122d5dbcd00))
+
+- Update typing ([#588](https://github.com/Python-roborock/python-roborock/pull/588),
+  [`3994110`](https://github.com/Python-roborock/python-roborock/commit/39941103fe5247a9764d38db5ee0915dd39e043d))
+
+### Features
+
+- Add examples that show how to use the cache and implement a file cache
+  ([#589](https://github.com/Python-roborock/python-roborock/pull/589),
+  [`fa69bf2`](https://github.com/Python-roborock/python-roborock/commit/fa69bf2d9d090bf8bc6cf89ead6ab122d5dbcd00))
+
+- Connect to devices asynchronously
+  ([#588](https://github.com/Python-roborock/python-roborock/pull/588),
+  [`3994110`](https://github.com/Python-roborock/python-roborock/commit/39941103fe5247a9764d38db5ee0915dd39e043d))
+
+
 ## v3.7.4 (2025-11-15)
 
 ### Bug Fixes

README.md

@@ -20,16 +20,14 @@ Install this via pip (or your favourite package manager):
 
 You can see all of the commands supported [here](https://python-roborock.readthedocs.io/en/latest/api_commands.html)
 
-## Sending Commands
+## Example Usage
 
-Here is an example that requires no manual intervention and can be done all automatically. You can skip some steps by
-caching values or looking at them and grabbing them manually.
 ```python
 import asyncio
 
-from roborock import HomeDataProduct, DeviceData, RoborockCommand
-from roborock.version_1_apis import RoborockMqttClientV1, RoborockLocalClientV1
 from roborock.web_api import RoborockApiClient
+from roborock.devices.device_manager import create_device_manager, UserParams
+
 
 async def main():
     web_api = RoborockApiClient(username="youremailhere")
@@ -40,30 +38,31 @@ async def main():
     code = input("What is the code?")
     user_data = await web_api.code_login(code)
 
-    # Get home data
-    home_data = await web_api.get_home_data_v2(user_data)
-
-    # Get the device you want
-    device = home_data.devices[0]
-
-    # Get product ids:
-    product_info: dict[str, HomeDataProduct] = {
-            product.id: product for product in home_data.products
-        }
-    # Create the Mqtt(aka cloud required) Client
-    device_data = DeviceData(device, product_info[device.product_id].model)
-    mqtt_client = RoborockMqttClientV1(user_data, device_data)
-    networking = await mqtt_client.get_networking()
-    local_device_data = DeviceData(device, product_info[device.product_id].model, networking.ip)
-    local_client = RoborockLocalClientV1(local_device_data)
-    # You can use the send_command to send any command to the device
-    status = await local_client.send_command(RoborockCommand.GET_STATUS)
-    # Or use existing functions that will give you data classes
-    status = await local_client.get_status()
+    # Create a device manager that can discover devices.
+    user_params = UserParams(
+        username="youremailhere",
+        user_data=user_data,
+    )
+    device_manager = await create_device_manager(user_params)
+    devices = await device_manager.get_devices()
+
+    # Get all vacuum devices that support the v1 PropertiesApi
+    for device in devices:
+        if not device.v1_properties:
+            continue
+
+        # Refresh the current device status
+        status_trait = device.v1_properties.status
+        await status_trait.refresh()
+        print(status_trait)
 
 asyncio.run(main())
 ```
 
+See [examples/example.py](examples/example.py) for a more full featured example
+that has performance improvements to cache cloud information to prefer
+connections over the local network.
+
 ## Supported devices
 
 You can find what devices are supported

examples/example.py

@@ -0,0 +1,85 @@
+"""Example script demonstrating how to connect to Roborock devices and print their status."""
+
+import asyncio
+import dataclasses
+import json
+import pathlib
+from typing import Any
+
+from roborock.devices.device_manager import UserParams, create_device_manager
+from roborock.devices.file_cache import FileCache, load_value, store_value
+from roborock.web_api import RoborockApiClient
+
+# We typically store the login credentials/information separately from other cached data.
+USER_PARAMS_PATH = pathlib.Path.home() / ".cache" / "roborock-user-params.pkl"
+
+# Device connection information is cached to speed up future connections.
+CACHE_PATH = pathlib.Path.home() / ".cache" / "roborock-cache-data.pkl"
+
+
+async def login_flow() -> UserParams:
+    """Perform the login flow to obtain UserData from the web API."""
+    username = input("Email: ")
+    web_api = RoborockApiClient(username=username)
+    print("Requesting login code sent to email...")
+    await web_api.request_code()
+    code = input("Code: ")
+    user_data = await web_api.code_login(code)
+    # We store the base_url to avoid future discovery calls.
+    base_url = await web_api.base_url
+    return UserParams(
+        username=username,
+        user_data=user_data,
+        base_url=base_url,
+    )
+
+
+async def get_or_create_session() -> UserParams:
+    """Initialize the session by logging in if necessary."""
+    user_params = await load_value(USER_PARAMS_PATH)
+    if user_params is None:
+        print("No cached login data found, please login.")
+        user_params = await login_flow()
+        print("Login successful, caching login data...")
+        await store_value(USER_PARAMS_PATH, user_params)
+        print(f"Cached login data to {USER_PARAMS_PATH}.")
+    return user_params
+
+
+def remove_none_values(data: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in data.items() if v is not None}
+
+
+async def main():
+    user_params = await get_or_create_session()
+    cache = FileCache(CACHE_PATH)
+
+    # Create a device manager that can discover devices.
+    device_manager = await create_device_manager(user_params, cache=cache)
+    devices = await device_manager.get_devices()
+
+    # Get all vacuum devices that support the v1 PropertiesApi
+    device_results = []
+    for device in devices:
+        if not device.v1_properties:
+            continue
+
+        # Refresh the current device status
+        status_trait = device.v1_properties.status
+        await status_trait.refresh()
+
+        # Print the device status as JSON
+        device_results.append(
+            {
+                "device": device.name,
+                "status": remove_none_values(dataclasses.asdict(status_trait)),
+            }
+        )
+
+    print(json.dumps(device_results, indent=2))
+
+    await cache.flush()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "3.7.4"
+version = "3.8.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"
@@ -44,7 +44,7 @@ dev = [
     "pytest",
     "pre-commit>=3.5,<5.0",
     "mypy",
-    "ruff==0.14.4",
+    "ruff==0.14.5",
     "codespell",
     "pyshark>=0.6,<0.7",
     "aioresponses>=0.7.7,<0.8",

roborock/__init__.py

@@ -11,6 +11,7 @@
     cloud_api,
     const,
     data,
+    devices,
     exceptions,
     roborock_typing,
     version_1_apis,
@@ -19,13 +20,11 @@
 )
 
 __all__ = [
+    "devices",
+    "data",
+    "map",
     "web_api",
-    "version_1_apis",
-    "version_a01_apis",
-    "const",
-    "cloud_api",
     "roborock_typing",
     "exceptions",
-    "data",
-    # Add new APIs here in the future when they are public e.g. devices/
+    "const",
 ]

roborock/devices/README.md

@@ -1,6 +1,8 @@
-# Roborock Device Discovery
+# Roborock Devices & Discovery
 
-This page documents the full lifecycle of device discovery across Cloud and Network.
+The devices module provides functionality to discover Roborock devices on the
+network. This section documents the full lifecycle of device discovery across
+Cloud and Network.
 
 ## Init account setup
 
@@ -61,7 +63,7 @@ that a newer version of the API should be used.
 
 ## Design
 
-### Current API Issues
+### Prior API Issues
 
 - Complex Inheritance Hierarchy: Multiple inheritance with classes like RoborockMqttClientV1 inheriting from both RoborockMqttClient and RoborockClientV1
 

roborock/devices/__init__.py

@@ -1,7 +1,11 @@
-"""The devices module provides functionality to discover Roborock devices on the network."""
+"""
+.. include:: ./README.md
+"""
 
 __all__ = [
     "device",
     "device_manager",
     "cache",
+    "file_cache",
+    "traits",
 ]

roborock/devices/device.py

@@ -4,12 +4,15 @@
 until the API is stable.
 """
 
+import asyncio
+import datetime
 import logging
 from abc import ABC
 from collections.abc import Callable, Mapping
 from typing import Any, TypeVar, cast
 
 from roborock.data import HomeDataDevice, HomeDataProduct
+from roborock.exceptions import RoborockException
 from roborock.roborock_message import RoborockMessage
 
 from .channel import Channel
@@ -22,6 +25,11 @@
     "RoborockDevice",
 ]
 
+# Exponential backoff parameters
+MIN_BACKOFF_INTERVAL = datetime.timedelta(seconds=10)
+MAX_BACKOFF_INTERVAL = datetime.timedelta(minutes=30)
+BACKOFF_MULTIPLIER = 1.5
+
 
 class RoborockDevice(ABC, TraitsMixin):
     """A generic channel for establishing a connection with a Roborock device.
@@ -54,6 +62,7 @@ def __init__(
         self._device_info = device_info
         self._product = product
         self._channel = channel
+        self._connect_task: asyncio.Task[None] | None = None
         self._unsub: Callable[[], None] | None = None
 
     @property
@@ -98,6 +107,38 @@ def is_local_connected(self) -> bool:
         """
         return self._channel.is_local_connected
 
+    def start_connect(self) -> None:
+        """Start a background task to connect to the device.
+
+        This will attempt to connect to the device using the appropriate protocol
+        channel. If the connection fails, it will retry with exponential backoff.
+
+        Once connected, the device will remain connected until `close()` is
+        called. The device will automatically attempt to reconnect if the connection
+        is lost.
+        """
+
+        async def connect_loop() -> None:
+            backoff = MIN_BACKOFF_INTERVAL
+            try:
+                while True:
+                    try:
+                        await self.connect()
+                        return
+                    except RoborockException as e:
+                        _LOGGER.info("Failed to connect to device %s: %s", self.name, e)
+                        _LOGGER.info(
+                            "Retrying connection to device %s in %s seconds", self.name, backoff.total_seconds()
+                        )
+                        await asyncio.sleep(backoff.total_seconds())
+                        backoff = min(backoff * BACKOFF_MULTIPLIER, MAX_BACKOFF_INTERVAL)
+            except asyncio.CancelledError:
+                _LOGGER.info("connect_loop for device %s was cancelled", self.name)
+                # Clean exit on cancellation
+                return
+
+        self._connect_task = asyncio.create_task(connect_loop())
+
     async def connect(self) -> None:
         """Connect to the device using the appropriate protocol channel."""
         if self._unsub:
@@ -107,6 +148,12 @@ async def connect(self) -> None:
 
     async def close(self) -> None:
         """Close all connections to the device."""
+        if self._connect_task:
+            self._connect_task.cancel()
+            try:
+                await self._connect_task
+            except asyncio.CancelledError:
+                pass
         if self._unsub:
             self._unsub()
             self._unsub = None

roborock/devices/device_manager.py

@@ -86,7 +86,7 @@ async def discover_devices(self) -> list[RoborockDevice]:
             if duid in self._devices:
                 continue
             new_device = self._device_creator(home_data, device, product)
-            await new_device.connect()
+            new_device.start_connect()
             new_devices[duid] = new_device
 
         self._devices.update(new_devices)