Improve library user documentation (#685)

* chore: Improve library user documentation

Update the documentation to answer basic questions from a first time library user perspective. Given the deeper submodules, it may be harder to find so we add details so users can understand the bigger picture.
Some existing documentation was focused more on design details for deeper implementation issues, so this clarifies what is lower level vs higher level.

* chore: fix typo in README.md

Author: allenporter

README.md

@@ -20,11 +20,13 @@ Install this via pip (or your favourite package manager):
 
 `pip install python-roborock`
 
-## Functionality
+## Example Usage
 
-You can see all of the commands supported [here](https://python-roborock.readthedocs.io/en/latest/api_commands.html)
+See [examples/example.py](examples/example.py) for a more full featured example,
+or the [API documentation](https://python-roborock.github.io/python-roborock/)
+for more details.
 
-## Example Usage
+Here is a basic example:
 
 ```python
 import asyncio
@@ -34,38 +36,45 @@ from roborock.devices.device_manager import create_device_manager, UserParams
 
 
 async def main():
-    web_api = RoborockApiClient(username="youremailhere")
-    # Login via your password
-    user_data = await web_api.pass_login(password="pass_here")
-    # Or login via a code
+    email_address = "youremailhere@example.com"
+    web_api = RoborockApiClient(username=email_address)
+    # Send a login code to the above email address
     await web_api.request_code()
+    # Prompt the user to enter the code
     code = input("What is the code?")
     user_data = await web_api.code_login(code)
 
     # Create a device manager that can discover devices.
-    user_params = UserParams(
-        username="youremailhere",
-        user_data=user_data,
-    )
+    user_params = UserParams(username=email_address, 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
+    # Get all vacuum devices. Each device generation has different capabilities
+    # and APIs available so to find vacuums we filter by the v1 PropertiesApi.
     for device in devices:
         if not device.v1_properties:
             continue
 
-        # Refresh the current device status
+        # The PropertiesAPI has traits different device commands such as getting
+        # status, sending clean commands, etc. For this example we send a
+        # command to 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.
+
+## Functionality
+
+The library interacts with devices through specific API properties based on the device protocol:
+
+*   **Standard Vacuums (V1 Protocol)**: Most robot vacuums use this. Interaction is done through `device.v1_properties`, which contains traits like `status`, `consumables`, and `maps`. Use the `command` trait for actions like starting or stopping cleaning.
+*   **Wet/Dry Vacuums & Washing Machines (A01 Protocol)**: Devices like the Dyad and Zeo use this. Interaction is done through `device.a01_properties` using `query_values()` and `set_value()`.
+
+You can find detailed documentation for [Devices](https://python-roborock.github.io/python-roborock/roborock/devices/device.html) and [Traits](https://python-roborock.github.io/python-roborock/roborock/devices/traits.html).
+
 
 ## Supported devices
 
@@ -74,6 +83,7 @@ You can find what devices are supported
 Please note this may not immediately contain the latest devices.
 
 
-## Credits
+## Acknowledgements
 
-Thanks @rovo89 for https://gist.github.com/rovo89/dff47ed19fca0dfdda77503e66c2b7c7 And thanks @PiotrMachowski for https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor
+* Thanks to [@rovo89](https://github.com/rovo89) for [Login APIs gist](https://gist.github.com/rovo89/dff47ed19fca0dfdda77503e66c2b7c7).
+* Thanks to [@PiotrMachowski](https://github.com/PiotrMachowski) for [Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor](https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor).

roborock/devices/README.md

@@ -4,7 +4,19 @@ 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.
 
-## Quick Start: Understanding Device Protocols
+## Usage TL;DR
+
+*   **Discovery**: Use `roborock.devices.device_manager.DeviceManager` to get device instances.
+    *   Call `create_device_manager(user_params)` then `await device_manager.get_devices()`.
+*   **Control**:
+    *   **Vacuums (V1)**: Use `device.v1_properties` to access traits like `status` or `consumables`.
+        *   Call `await trait.refresh()` to update state.
+        *   Use `device.v1_properties.command.send()` for raw commands (start/stop).
+    *   **Washers (A01)**: Use `device.a01_properties` for Dyad/Zeo devices.
+        *   Use `await device.a01_properties.query_values([...])` to get state.
+        *   Use `await device.a01_properties.set_value(protocol, value)` to control.
+
+## Background: Understanding Device Protocols
 
 **The library supports three device protocol versions, each with different capabilities:**
 
@@ -18,7 +30,7 @@ Cloud and Network.
 
 **Key Point:** The `DeviceManager` automatically detects the protocol version and creates the appropriate channel type. You don't need to handle this manually.
 
-## Architecture Overview
+## Internal Architecture
 
 The library is organized into distinct layers, each with a specific responsibility. **Different device protocols use different channel implementations:**
 
@@ -138,7 +150,7 @@ graph TB
 | **A01** (`pv=A01`) | `MqttChannel` + helpers | ❌ No | Direct MQTT | Dyad, Zeo washers |
 | **B01** (`pv=B01`) | `MqttChannel` + helpers | ❌ No | Direct MQTT | Some newer models |
 
-## Init account setup
+## Account Setup Internals
 
 ### Login
 
@@ -151,7 +163,7 @@ graph TB
   - This contains information used to connect to MQTT
   - You get an `-eu` suffix in the API URLs if you are in the eu and `-us` if you are in the us
 
-## Home Data
+## Home Data Internals
 
 The `HomeData` includes information about the various devices in the home. We use `v3`
 and it is notable that if devices don't show up in the `home_data` response it is likely
@@ -174,7 +186,7 @@ that a newer version of the API should be used.
   - There is another REST request `get_rooms` that will do the same thing.
   - Note: If we cache home_data, we likely need to use `get_rooms` to get rooms fresh
 
-## Device Connections
+## Connection Implementation
 
 ### Connection Flow by Protocol
 
@@ -343,7 +355,7 @@ graph LR
 3. **Timeout Handling**: Commands timeout after 10 seconds if no response is received
 4. **Multiple Strategies**: `V1Channel` tries local first, then falls back to MQTT if local fails
 
-## Design
+## Class Design & Components
 
 ### Current Architecture
 

roborock/devices/traits/__init__.py

@@ -1,4 +1,17 @@
-"""Module for device traits."""
+"""Module for device traits.
+
+This package contains the trait definitions for different device protocols supported
+by Roborock devices.
+
+Submodules
+----------
+*   `v1`: Contains traits for standard Roborock vacuums (e.g., S-series, Q-series).
+    These devices use the V1 protocol and have rich feature sets split into
+    granular traits (e.g., `StatusTrait`, `ConsumableTrait`).
+*   `a01`: Contains APIs for A01 protocol devices, such as the Dyad (wet/dry vacuum)
+    and Zeo (washing machine). These devices use a different communication structure.
+*   `b01`: Contains APIs for B01 protocol devices.
+"""
 
 from abc import ABC
 

roborock/devices/traits/a01/__init__.py

@@ -1,3 +1,24 @@
+"""Create traits for A01 devices.
+
+This module provides the API implementations for A01 protocol devices, which include
+Dyad (Wet/Dry Vacuums) and Zeo (Washing Machines).
+
+Using A01 APIs
+--------------
+A01 devices expose a single API object that handles all device interactions. This API is
+available on the device instance (typically via `device.a01_properties`).
+
+The API provides two main methods:
+1.  **query_values(protocols)**: Fetches current state for specific data points.
+    You must pass a list of protocol enums (e.g. `RoborockDyadDataProtocol` or
+    `RoborockZeoProtocol`) to request specific data.
+2.  **set_value(protocol, value)**: Sends a command to the device to change a setting
+    or perform an action.
+
+Note that these APIs fetch data directly from the device upon request and do not
+cache state internally.
+"""
+
 import json
 from collections.abc import Callable
 from datetime import time

roborock/devices/traits/v1/__init__.py

@@ -2,17 +2,33 @@
 
 Traits are modular components that encapsulate specific features of a Roborock
 device. This module provides a factory function to create and initialize the
-appropriate traits for V1 devices based on their capabilities. They can also
-be considered groups of commands and parsing logic for that command.
-
-Traits have a `refresh()` method that can be called to update their state
-from the device. Some traits may also provide additional methods for modifying
-the device state.
-
-The most common pattern for a trait is to subclass `V1TraitMixin` and a `RoborockBase`
-dataclass, and define a `command` class variable that specifies the `RoborockCommand`
-used to fetch the trait data from the device. See `common.py` for more details
-on common patterns used across traits.
+appropriate traits for V1 devices based on their capabilities.
+
+Using Traits
+------------
+Traits are accessed via the `v1_properties` attribute on a device. Each trait
+represents a specific capability, such as `status`, `consumables`, or `rooms`.
+
+Traits serve two main purposes:
+1.  **State**: Traits are dataclasses that hold the current state of the device
+    feature. You can access attributes directly (e.g., `device.v1_properties.status.battery`).
+2.  **Commands**: Traits provide methods to control the device. For example,
+    `device.v1_properties.volume.set_volume()`.
+
+Additionally, the `command` trait provides a generic way to send any command to the
+device (e.g. `device.v1_properties.command.send("app_start")`). This is often used
+for basic cleaning operations like starting, stopping, or docking the vacuum.
+
+Most traits have a `refresh()` method that must be called to update their state
+from the device. The state is not updated automatically in real-time unless
+specifically implemented by the trait or via polling.
+
+Adding New Traits
+-----------------
+When adding a new trait, the most common pattern is to subclass `V1TraitMixin`
+and a `RoborockBase` dataclass. You must define a `command` class variable that
+specifies the `RoborockCommand` used to fetch the trait data from the device.
+See `common.py` for more details on common patterns used across traits.
 
 There are some additional decorators in `common.py` that can be used to specify which
 RPC channel to use for the trait (standard, MQTT/cloud, or map-specific).
@@ -43,6 +59,29 @@
 from roborock.protocols.v1_protocol import V1RpcChannel
 from roborock.web_api import UserWebApiClient
 
+from . import (
+    child_lock,
+    clean_summary,
+    command,
+    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,
+)
 from .child_lock import ChildLockTrait
 from .clean_summary import CleanSummaryTrait
 from .command import CommandTrait
@@ -71,6 +110,7 @@
     "PropertiesApi",
     "child_lock",
     "clean_summary",
+    "command",
     "common",
     "consumeable",
     "device_features",

roborock/devices/traits/v1/command.py

@@ -5,7 +5,17 @@
 
 
 class CommandTrait:
-    """Trait for sending commands to Roborock devices."""
+    """Trait for sending commands to Roborock devices.
+
+    This trait allows sending raw commands directly to the device. It is particularly
+    useful for:
+    1.  **Cleaning Control**: Sending commands like `app_start`, `app_stop`, `app_pause`,
+        or `app_charge` which don't belong to a specific state trait.
+    2.  **Unsupported Features**: Accessing device functionality that hasn't been
+        mapped to a specific trait yet.
+
+    See `roborock.roborock_typing.RoborockCommand` for a list of available commands.
+    """
 
     def __post_init__(self) -> None:
         """Post-initialization to set up the RPC channel.

roborock/roborock_typing.py

@@ -16,6 +16,12 @@
 
 
 class RoborockCommand(str, Enum):
+    """Enum of all known Roborock V1 protocol commands.
+
+    These commands can be sent to a device using the `CommandTrait`.
+    For example: `device.v1_properties.command.send(RoborockCommand.APP_START)`.
+    """
+
     ADD_MOP_TEMPLATE_PARAMS = "add_mop_template_params"
     APP_AMETHYST_SELF_CHECK = "app_amethyst_self_check"
     APP_CHARGE = "app_charge"