chore: Update documentation to point to the newer device APIs (#589)

* Update documentation to point to the newer device APIs

* chore: Update roborock/devices/traits/b01/__init__.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore: Update roborock/devices/traits/v1/__init__.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore: Update README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* feat: add examples that show how to use the cache and implement a file cache

* chore: fix lint

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: allenporter

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())

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/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)

roborock/devices/traits/b01/__init__.py

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

roborock/devices/traits/v1/__init__.py

@@ -67,27 +67,27 @@
 _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",
 ]
 
 

roborock/protocols/__init__.py

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