python-roborock 3.7.4__tar.gz → 3.8.0__tar.gz

{python_roborock-3.7.4 → python_roborock-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 3.7.4
+Version: 3.8.0
 Summary: A package to control Roborock vacuums.
 Project-URL: Repository, https://github.com/humbertogontijo/python-roborock
 Project-URL: Documentation, https://python-roborock.readthedocs.io/
@@ -49,16 +49,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")
@@ -69,30 +67,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

{python_roborock-3.7.4 → python_roborock-3.8.0}/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

{python_roborock-3.7.4 → python_roborock-3.8.0}/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"

{python_roborock-3.7.4 → python_roborock-3.8.0}/roborock/__init__.py

@@ -11,6 +11,7 @@ from . import (
     cloud_api,
     const,
     data,
+    devices,
     exceptions,
     roborock_typing,
     version_1_apis,
@@ -19,13 +20,11 @@ from . import (
 )
 
 __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",
 ]

{python_roborock-3.7.4 → python_roborock-3.8.0}/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
 

python_roborock-3.8.0/roborock/devices/__init__.py

@@ -0,0 +1,11 @@
+"""
+.. include:: ./README.md
+"""
+
+__all__ = [
+    "device",
+    "device_manager",
+    "cache",
+    "file_cache",
+    "traits",
+]

{python_roborock-3.7.4 → python_roborock-3.8.0}/roborock/devices/device.py

@@ -4,12 +4,15 @@ This interface is experimental and subject to breaking changes without notice
 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 @@ __all__ = [
     "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 @@ class RoborockDevice(ABC, TraitsMixin):
         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 @@ class RoborockDevice(ABC, TraitsMixin):
         """
         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 @@ class RoborockDevice(ABC, TraitsMixin):
 
     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

{python_roborock-3.7.4 → python_roborock-3.8.0}/roborock/devices/device_manager.py

@@ -86,7 +86,7 @@ class DeviceManager:
             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)

python_roborock-3.8.0/roborock/devices/file_cache.py

@@ -0,0 +1,70 @@
+"""This module implements a file-backed cache for device information.
+
+This module provides a `FileCache` class that implements the `Cache` protocol
+to store and retrieve cached device information from a file on disk. This allows
+persistent caching of device data across application restarts.
+"""
+
+import asyncio
+import pathlib
+import pickle
+from collections.abc import Callable
+from typing import Any
+
+from .cache import Cache, CacheData
+
+
+class FileCache(Cache):
+    """File backed cache implementation."""
+
+    def __init__(self, file_path: pathlib.Path, init_fn: Callable[[], CacheData] = CacheData) -> None:
+        """Initialize the file cache with the given file path."""
+        self._init_fn = init_fn
+        self._file_path = file_path
+        self._cache_data: CacheData | None = None
+
+    async def get(self) -> CacheData:
+        """Get cached value."""
+        if self._cache_data is not None:
+            return self._cache_data
+
+        data = await load_value(self._file_path)
+        if data is not None and not isinstance(data, CacheData):
+            raise TypeError(f"Invalid cache data loaded from {self._file_path}")
+
+        self._cache_data = data or self._init_fn()
+        return self._cache_data
+
+    async def set(self, value: CacheData) -> None:  # type: ignore[override]
+        """Set value in the cache."""
+        self._cache_data = value
+
+    async def flush(self) -> None:
+        """Flush the cache to disk."""
+        if self._cache_data is None:
+            return
+        await store_value(self._file_path, self._cache_data)
+
+
+async def store_value(file_path: pathlib.Path, value: Any) -> None:
+    """Store a value to the given file path."""
+
+    def _store_to_disk(file_path: pathlib.Path, value: Any) -> None:
+        with open(file_path, "wb") as f:
+            data = pickle.dumps(value)
+            f.write(data)
+
+    await asyncio.to_thread(_store_to_disk, file_path, value)
+
+
+async def load_value(file_path: pathlib.Path) -> Any | None:
+    """Load a value from the given file path."""
+
+    def _load_from_disk(file_path: pathlib.Path) -> Any | None:
+        if not file_path.exists():
+            return None
+        with open(file_path, "rb") as f:
+            data = f.read()
+            return pickle.loads(data)
+
+    return await asyncio.to_thread(_load_from_disk, file_path)

{python_roborock-3.7.4 → python_roborock-3.8.0}/roborock/devices/traits/b01/__init__.py

@@ -6,8 +6,7 @@ from roborock.devices.mqtt_channel import MqttChannel
 from roborock.devices.traits import Trait
 from roborock.roborock_message import RoborockB01Props
 
-__init__ = [
-    "create_b01_traits",
+__all__ = [
     "PropertiesApi",
 ]
 

{python_roborock-3.7.4 → python_roborock-3.8.0}/roborock/devices/traits/v1/__init__.py

@@ -67,27 +67,27 @@ from .wash_towel_mode import WashTowelModeTrait
 _LOGGER = logging.getLogger(__name__)
 
 __all__ = [
-    "create",
     "PropertiesApi",
-    "StatusTrait",
-    "DoNotDisturbTrait",
-    "CleanSummaryTrait",
-    "SoundVolumeTrait",
-    "MapsTrait",
-    "MapContentTrait",
-    "ConsumableTrait",
-    "HomeTrait",
-    "DeviceFeaturesTrait",
-    "CommandTrait",
-    "ChildLockTrait",
-    "FlowLedStatusTrait",
-    "LedStatusTrait",
-    "ValleyElectricityTimerTrait",
-    "DustCollectionModeTrait",
-    "WashTowelModeTrait",
-    "SmartWashParamsTrait",
-    "NetworkInfoTrait",
-    "RoutinesTrait",
+    "child_lock",
+    "clean_summary",
+    "common",
+    "consumeable",
+    "device_features",
+    "do_not_disturb",
+    "dust_collection_mode",
+    "flow_led_status",
+    "home",
+    "led_status",
+    "map_content",
+    "maps",
+    "network_info",
+    "rooms",
+    "routines",
+    "smart_wash_params",
+    "status",
+    "valley_electricity_timer",
+    "volume",
+    "wash_towel_mode",
 ]
 
 

python_roborock-3.8.0/roborock/protocols/__init__.py

@@ -0,0 +1,3 @@
+"""Protocols for communicating with Roborock devices."""
+
+__all__: list[str] = []

python_roborock-3.7.4/roborock/devices/__init__.py

@@ -1,7 +0,0 @@
-"""The devices module provides functionality to discover Roborock devices on the network."""
-
-__all__ = [
-    "device",
-    "device_manager",
-    "cache",
-]