Update documentation to point to the newer device APIs

README.md

@@ -24,12 +24,13 @@ You can see all of the commands supported [here](https://python-roborock.readthe
 
 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,26 +41,23 @@ 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())
 ```

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,10 @@
-"""The devices module provides functionality to discover Roborock devices on the network."""
+"""
+.. include:: ./README.md
+"""
 
 __all__ = [
     "device",
     "device_manager",
     "cache",
+    "traits",
 ]

roborock/devices/traits/b01/__init__.py

@@ -7,7 +7,6 @@
 from roborock.roborock_message import RoborockB01Props
 
 __init__ = [
-    "create_b01_traits",
     "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",
+    "consumable",
+    "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] = []