diff --git a/docs/DEVICES.md b/docs/DEVICES.md new file mode 100644 index 00000000..9d31df1b --- /dev/null +++ b/docs/DEVICES.md @@ -0,0 +1,669 @@ +# Roborock Devices & Discovery + +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. + +## 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:** + +### Protocol Summary + +| Protocol | Device Examples | MQTT | Local TCP | Channel Type | Notes | +|----------|----------------|------|-----------|--------------|-------| +| **V1** (`pv=1.0`) | Most vacuum robots (S7, S8, Q5, Q7, etc.) | ✅ | ✅ | `V1Channel` with `RpcChannel` | Prefers local, falls back to MQTT | +| **A01** (`pv=A01`) | Dyad, Zeo washers | ✅ | ❌ | `MqttChannel` + helpers | MQTT only, DPS protocol | +| **B01** (`pv=B01`) | Some newer models | ✅ | ❌ | `MqttChannel` + helpers | MQTT only, DPS protocol | + +**Key Point:** The `DeviceManager` automatically detects the protocol version and creates the appropriate channel type. You don't need to handle this manually. + +## Internal Architecture + +The library is organized into distinct layers, each with a specific responsibility. **Different device protocols use different channel implementations:** + +```mermaid +graph TB + subgraph "Application Layer" + User[Application Code] + end + + subgraph "Device Management Layer" + DM[DeviceManager
Detects protocol version] + end + + subgraph "Device Types by Protocol" + V1Dev[V1 Devices
pv=1.0
Most vacuums] + A01Dev[A01 Devices
pv=A01
Dyad, Zeo] + B01Dev[B01 Devices
pv=B01
Some models] + end + + subgraph "Traits Layer" + V1Traits[V1 Traits
Clean, Map, etc.] + A01Traits[A01 Traits
DPS-based] + B01Traits[B01 Traits
DPS-based] + end + + subgraph "Channel Layer" + V1C[V1Channel
MQTT + Local] + A01C[A01 send_decoded_command
MQTT only] + B01C[B01 send_decoded_command
MQTT only] + RPC[RpcChannel
Multi-strategy] + MC[MqttChannel
Per-device wrapper] + LC[LocalChannel
TCP :58867] + end + + subgraph "Session Layer" + MS[MqttSession
SHARED by all devices
Idle timeout] + LS[LocalSession
Factory] + end + + subgraph "Protocol Layer" + V1P[V1 Protocol
JSON RPC + AES] + A01P[A01 Protocol
DPS format] + B01P[B01 Protocol
DPS format] + end + + subgraph "Transport Layer" + MQTT[MQTT Broker
Roborock Cloud] + TCP[TCP Socket
Direct to device] + end + + User --> DM + DM -->|pv=1.0| V1Dev + DM -->|pv=A01| A01Dev + DM -->|pv=B01| B01Dev + + V1Dev --> V1Traits + A01Dev --> A01Traits + B01Dev --> B01Traits + + V1Traits --> V1C + A01Traits --> A01C + B01Traits --> B01C + + V1C --> RPC + RPC -->|Strategy 1| LC + RPC -->|Strategy 2| MC + A01C --> MC + B01C --> MC + + MC --> MS + LC --> LS + + MC --> V1P + MC --> A01P + MC --> B01P + LC --> V1P + + MS --> MQTT + LC --> TCP + MQTT <--> TCP + + style User fill:#e1f5ff + style DM fill:#fff4e1 + style V1C fill:#ffe1e1 + style RPC fill:#ffe1e1 + style MS fill:#e1ffe1 + style V1P fill:#f0e1ff + style A01P fill:#f0e1ff + style B01P fill:#f0e1ff +``` + +### Layer Responsibilities + +1. **Device Management Layer**: Detects protocol version (`pv` field) and creates appropriate channels +2. **Device Types**: Different devices based on protocol version (V1, A01, B01) +3. **Traits Layer**: Protocol-specific device capabilities and commands +4. **Channel Layer**: Protocol-specific communication patterns + - **V1**: Full RPC channel with local + MQTT fallback + - **A01/B01**: Helper functions wrapping MqttChannel (MQTT only) + - **MqttChannel**: Per-device wrapper that uses shared `MqttSession` +5. **Session Layer**: Connection pooling and subscription management + - **MqttSession**: **Shared single connection** for all devices + - **LocalSession**: Factory for creating device-specific local connections +6. **Protocol Layer**: Message encoding/decoding for different device versions +7. **Transport Layer**: Low-level MQTT and TCP communication + +**Important:** All `MqttChannel` instances share the same `MqttSession`, which maintains a single MQTT connection to the broker. This means: +- Only one TCP connection to the MQTT broker regardless of device count +- Subscription management is centralized with idle timeout optimization +- All devices communicate through device-specific MQTT topics on the shared connection + +### Protocol-Specific Architecture + +| Protocol | Channel Type | Local Support | RPC Strategy | Use Case | +|----------|-------------|---------------|--------------|----------| +| **V1** (`pv=1.0`) | `V1Channel` with `RpcChannel` | ✅ Yes | Multi-strategy (Local → MQTT) | Most vacuum robots | +| **A01** (`pv=A01`) | `MqttChannel` + helpers | ❌ No | Direct MQTT | Dyad, Zeo washers | +| **B01** (`pv=B01`) | `MqttChannel` + helpers | ❌ No | Direct MQTT | Some newer models | + +## Account Setup Internals + +### Login + +- Login can happen with either email and password or email and sending a code. We + currently prefer email with sending a code -- however the roborock no longer + supports this method of login. In the future we may want to migrate to password + if this login method is no longer supported. +- The Login API provides a `userData` object with information on connecting to the cloud APIs +- This `rriot` data contains per-session information, unique each time you login. + - 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 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 +that a newer version of the API should be used. + +- `products`: This is a list of all of the products you have on your account. These objects are always the same (i.e. a s7 maxv is always the exact same.) + - It only shows the products for devices available on your account +- `devices` and `received_devices`: + - These both share the same objects, but one is for devices that have been shared with you and one is those that are on your account. + - The big things here are (MOST are static): + - `duid`: A unique identifier for your device (this is always the same i think) + - `name`: The name of the device in your app + - `local_key`: The local key that is needed for encoding and decoding messages for the device. This stays the same unless someone sets their vacuum back up. + - `pv`: the protocol version (i.e. 1.0 or A1 or B1) + - `product_id`: The id of the product from the above products list. + - `device_status`: An initial status for some of the data we care about, though this changes on each update. +- `rooms`: The rooms in the home. + - This changes if the user adds a new room or changes its name. + - We have to combine this with the room numbers from `GET_ROOM_MAPPING` on the device + - 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 + +## Connection Implementation + +### Connection Flow by Protocol + +The connection flow differs based on the device protocol version: + +#### V1 Devices (Most Vacuums) - MQTT + Local + +```mermaid +sequenceDiagram + participant App as Application + participant DM as DeviceManager + participant V1C as V1Channel + participant RPC as RpcChannel + participant MC as MqttChannel + participant LC as LocalChannel + participant MS as MqttSession + participant Broker as MQTT Broker + participant Device as V1 Vacuum + + App->>DM: create_device_manager() + DM->>MS: Create MQTT Session + MS->>Broker: Connect + Broker-->>MS: Connected + + App->>DM: get_devices() + Note over DM: Detect pv=1.0 + DM->>V1C: Create V1Channel + V1C->>MC: Create MqttChannel + V1C->>LC: Create LocalChannel (deferred) + + Note over V1C: Subscribe to device topics + V1C->>MC: subscribe() + MC->>MS: subscribe(topic, callback) + MS->>Broker: SUBSCRIBE + + Note over V1C: Fetch network info via MQTT + V1C->>RPC: send_command(GET_NETWORK_INFO) + RPC->>MC: publish(request) + MC->>MS: publish(topic, message) + MS->>Broker: PUBLISH + Broker->>Device: Command + Device->>Broker: Response + Broker->>MS: Message + MS->>MC: callback(message) + MC->>RPC: decoded message + RPC-->>V1C: NetworkInfo + + Note over V1C: Connect locally using IP + V1C->>LC: connect() + LC->>Device: TCP Connect :58867 + Device-->>LC: Connected + + Note over App: Commands prefer local + App->>V1C: send_command(GET_STATUS) + V1C->>RPC: send_command() + RPC->>LC: publish(request) [Try local first] + LC->>Device: Command via TCP + Device->>LC: Response + LC->>RPC: decoded message + RPC-->>App: Status +``` + +#### A01/B01 Devices (Dyad, Zeo) - MQTT Only + +```mermaid +sequenceDiagram + participant App as Application + participant DM as DeviceManager + participant A01 as A01 Traits + participant Helper as send_decoded_command + participant MC as MqttChannel + participant MS as MqttSession + participant Broker as MQTT Broker + participant Device as A01 Device + + App->>DM: create_device_manager() + DM->>MS: Create MQTT Session + MS->>Broker: Connect + Broker-->>MS: Connected + + App->>DM: get_devices() + Note over DM: Detect pv=A01 + DM->>MC: Create MqttChannel + DM->>A01: Create A01 Traits + + Note over A01: Subscribe to device topics + A01->>MC: subscribe() + MC->>MS: subscribe(topic, callback) + MS->>Broker: SUBSCRIBE + + Note over App: All commands via MQTT + App->>A01: set_power(True) + A01->>Helper: send_decoded_command() + Helper->>MC: subscribe(find_response) + Helper->>MC: publish(request) + MC->>MS: publish(topic, message) + MS->>Broker: PUBLISH + Broker->>Device: Command + Device->>Broker: Response + Broker->>MS: Message + MS->>MC: callback(message) + MC->>Helper: decoded message + Helper-->>App: Result +``` + +### Key Differences + +| Aspect | V1 Devices | A01/B01 Devices | +|--------|------------|-----------------| +| **Protocols** | V1 Protocol (JSON RPC) | DPS Protocol | +| **Transports** | MQTT + Local TCP | MQTT only | +| **Channel Type** | `V1Channel` with `RpcChannel` | `MqttChannel` with helpers | +| **Local Support** | ✅ Yes, preferred | ❌ No | +| **Fallback** | Local → MQTT | N/A | +| **Connection** | Requires network info fetch | Direct MQTT | +| **Examples** | Most vacuum robots | Dyad washers, Zeo models | + +### MQTT Connection (All Devices) + +- Initial device information must be obtained from MQTT +- For V1 devices, we set up the MQTT device connection before the local device connection + - The `NetworkingInfo` needs to be fetched to get additional information about connecting to the device (e.g., Local IP Address) + - This networking info can be cached to reduce network calls + - MQTT is also the only way to get the device Map +- Incoming and outgoing messages are decoded/encoded using the device `local_key` +- For A01/B01 devices, MQTT is the only transport + +### Local Connection (V1 Devices Only) + +- We use the `ip` from the `NetworkingInfo` to find the device +- The local connection is preferred for improved latency and reducing load on the cloud servers to avoid rate limiting +- Connections are made using a normal TCP socket on port `58867` +- Incoming and outgoing messages are decoded/encoded using the device `local_key` +- Messages received on the stream may be partially received, so we keep a running buffer as messages are partially decoded +- **Not available for A01/B01 devices** + +### RPC Pattern (V1 Devices) + +V1 devices use a publish/subscribe model for both MQTT and local connections, with an RPC abstraction on top: + +```mermaid +graph LR + subgraph "RPC Layer" + A[send_command] -->|1. Create request| B[Encoder] + B -->|2. Subscribe for response| C[Channel.subscribe] + B -->|3. Publish request| D[Channel.publish] + C -->|4. Wait for match| E[find_response callback] + E -->|5. Match request_id| F[Future.set_result] + F -->|6. Return| G[Command Result] + end + + subgraph "Channel Layer" + C --> H[Subscription Map] + D --> I[Transport] + I --> J[Device] + J --> K[Incoming Messages] + K --> H + H --> E + end +``` + +**Key Design Points:** + +1. **Temporary Subscriptions**: Each RPC creates a temporary subscription that matches the request ID +2. **Subscription Reuse**: `MqttSession` keeps subscriptions alive for 60 seconds (or idle timeout) to enable reuse during command bursts +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 + +## Class Design & Components + +### Current Architecture + +The current design separates concerns into distinct layers: + +```mermaid +classDiagram + class Channel { + <> + +subscribe(callback) Callable + +publish(message) + +is_connected() bool + } + + class MqttChannel { + -MqttSession session + -duid: str + -local_key: str + +subscribe(callback) + +publish(message) + } + + class LocalChannel { + -host: str + -transport: Transport + -local_key: str + +connect() + +subscribe(callback) + +publish(message) + +close() + } + + class V1Channel { + -MqttChannel mqtt_channel + -LocalChannel local_channel + -RpcChannel rpc_channel + +send_command(method, params) + +subscribe(callback) + } + + class RpcChannel { + -List~RpcStrategy~ strategies + +send_command(method, params) + } + + class RpcStrategy { + +name: str + +channel: Channel + +encoder: Callable + +decoder: Callable + +health_manager: HealthManager + } + + class MqttSession { + -Client client + -dict listeners + -dict idle_timers + +subscribe(topic, callback) + +publish(topic, payload) + +close() + } + + Channel <|-- MqttChannel + Channel <|-- LocalChannel + Channel <|-- V1Channel + MqttChannel --> MqttSession + V1Channel --> MqttChannel + V1Channel --> LocalChannel + V1Channel --> RpcChannel + RpcChannel --> RpcStrategy + RpcStrategy --> Channel +``` + +### Key Components + +#### Channel Interface + +The `Channel` abstraction provides a uniform interface for both MQTT and local connections: + +- **`subscribe(callback)`**: Register a callback for incoming messages +- **`publish(message)`**: Send a message to the device +- **`is_connected`**: Check connection status + +This abstraction allows the RPC layer to work identically over both transports. + +#### MqttSession (Shared Across All Devices) + +The `MqttSession` manages a **single shared MQTT connection** for all devices: + +- **Single Connection**: Only one TCP connection to the MQTT broker, regardless of device count +- **Per-Device Topics**: Each device communicates via its own MQTT topics (e.g., `rr/m/i/{user}/{username}/{duid}`) +- **Subscription Pooling**: Multiple callbacks can subscribe to the same topic +- **Idle Timeout**: Keeps subscriptions alive for 10 seconds after the last callback unsubscribes (enables reuse during command bursts) +- **Reconnection**: Automatically reconnects and re-establishes all subscriptions on connection loss +- **Thread-Safe**: Uses asyncio primitives for safe concurrent access + +**Efficiency**: Creating 5 devices means 5 `MqttChannel` instances but only 1 `MqttSession` and 1 MQTT broker connection. + +#### MqttChannel (Per-Device Wrapper) + +Each device gets its own `MqttChannel` instance that: +- Wraps the shared `MqttSession` +- Manages device-specific topics (publish to `rr/m/i/.../duid`, subscribe to `rr/m/o/.../duid`) +- Handles protocol-specific encoding/decoding with the device's `local_key` +- Provides the same `Channel` interface as `LocalChannel` + +#### RpcChannel with Multiple Strategies (V1 Only) + +The `RpcChannel` implements the request/response pattern over pub/sub channels and is **only used by V1 devices**: + +```python +# Example: V1Channel tries local first, then MQTT +strategies = [ + RpcStrategy(name="local", channel=local_channel, ...), + RpcStrategy(name="mqtt", channel=mqtt_channel, ...), +] +rpc_channel = RpcChannel(strategies) +``` + +For each V1 command: +1. Try the first strategy (local) +2. If it fails, try the next strategy (MQTT) +3. Return the first successful result + +**A01/B01 devices** don't use `RpcChannel`. Instead, they use helper functions (`send_decoded_command`) that directly wrap `MqttChannel`. + +#### Protocol-Specific Channel Architecture + +| Component | V1 Devices | A01/B01 Devices | +|-----------|------------|-----------------| +| **Channel Class** | `V1Channel` | `MqttChannel` directly | +| **RPC Abstraction** | `RpcChannel` with strategies | Helper functions | +| **Strategy Pattern** | ✅ Multi-strategy (Local → MQTT) | ❌ Direct MQTT only | +| **Health Manager** | ✅ Tracks local/MQTT health | ❌ Not needed | +| **Code Location** | `v1_channel.py` | `a01_channel.py`, `b01_q7_channel.py` | + +#### Health Management (V1 Only) + +Each V1 RPC strategy can have a `HealthManager` that tracks success/failure: + +- **Exponential Backoff**: After failures, wait before retrying +- **Automatic Recovery**: Periodically attempt to restore failed connections +- **Network Info Refresh**: Refresh local IP addresses after extended periods + +A01/B01 devices don't need health management since they only use MQTT (no fallback). + +### Protocol Versions + +Different device models use different protocol versions: + +| Protocol | Devices | Encoding | +|----------|---------|----------| +| V1 | Most vacuum robots | JSON RPC with AES encryption | +| A01 | Dyad, Zeo | DPS-based protocol | +| B01 | Some newer models | DPS-based protocol | +| L01 | Local protocol variant | Binary protocol negotiation | + +The protocol layer handles encoding/decoding transparently based on the device's `pv` field. + +### Prior API Issues + +- Complex Inheritance Hierarchy: Multiple inheritance with classes like RoborockMqttClientV1 inheriting from both RoborockMqttClient and RoborockClientV1 + +- Callback-Heavy Design: Heavy reliance on callbacks and listeners in RoborockClientV1.on_message_received and the ListenerModel system + +- Version Fragmentation: Separate v1 and A01 APIs with different patterns and abstractions + +- Mixed Concerns: Classes handle both communication protocols (MQTT/local) and device-specific logic + +- Complex Caching: The AttributeCache system with RepeatableTask adds complexity + +- Manual Connection Management: Users need to manually set up both MQTT and local clients as shown in the README example + +### Design Goals + +- Prefer a single unified client that handles both MQTT and local connections internally. + +- Home and device discovery (fetching home data and device setup) will be behind a single API. + +- Asyncio First: Everything should be asyncio as much as possible, with fewer callbacks. + +- The clients should be working in terms of devices. We need to detect capabilities for each device and not expose details about API versions. + +- Reliability issues: The current Home Assistant integration has issues with reliability and needs to be simplified. It may be that there are bugs with the exception handling and it's too heavy on the cloud APIs and could benefit from more seamless caching. + +### Migration from Legacy APIs + +The library previously had: +- Separate `RoborockMqttClientV1` and `RoborockLocalClientV1` classes +- Manual connection management +- Callback-heavy design with `on_message_received` +- Complex inheritance hierarchies + +The new design: +- `DeviceManager` handles all connection management +- `V1Channel` automatically manages both MQTT and local +- Asyncio-first with minimal callbacks +- Clear separation of concerns through layers +- Users work with devices, not raw clients + + +## Implementation Details + +### Code Organization + +``` +roborock/ +├── devices/ # Device management and channels +│ ├── device_manager.py # High-level device lifecycle +│ ├── channel.py # Base Channel interface +│ ├── mqtt_channel.py # MQTT channel implementation +│ ├── local_channel.py # Local TCP channel implementation +│ ├── v1_channel.py # V1 protocol channel with RPC strategies +│ ├── a01_channel.py # A01 protocol helpers +│ ├── b01_q7_channel.py # B01 Q7 protocol helpers +│ └── traits/ # Device-specific command traits +│ └── v1/ # V1 device traits +│ ├── __init__.py # Trait initialization +│ ├── clean.py # Cleaning commands +│ ├── map.py # Map management +│ └── ... +├── mqtt/ # MQTT session management +│ ├── session.py # Base session interface +│ └── roborock_session.py # MQTT session with idle timeout +├── protocols/ # Protocol encoders/decoders +│ ├── v1_protocol.py # V1 JSON RPC protocol +│ ├── a01_protocol.py # A01 protocol +│ ├── b01_q7_protocol.py # B01 Q7 protocol +│ └── ... +└── data/ # Data containers and mappings + ├── containers.py # Status, HomeData, etc. + └── v1/ # V1-specific data structures +``` + +### Threading Model + +The library is **asyncio-only** with no threads: + +- All I/O is non-blocking using `asyncio` +- No thread synchronization needed (single event loop) +- Callbacks are executed in the event loop +- Use `asyncio.create_task()` for background work + +### Error Handling + +```mermaid +graph TD + A[send_command] --> B{Local Available?} + B -->|Yes| C[Try Local] + B -->|No| D[Try MQTT] + C --> E{Success?} + E -->|Yes| F[Return Result] + E -->|No| G{Timeout?} + G -->|Yes| H[Update Health Manager] + H --> D + G -->|No| I{Connection Error?} + I -->|Yes| J[Mark Connection Failed] + J --> D + I -->|No| D + D --> K{Success?} + K -->|Yes| F + K -->|No| L[Raise RoborockException] +``` + +**Exception Types:** + +- `RoborockException`: Base exception for all library errors +- `RoborockConnectionException`: Connection-related failures +- `RoborockTimeout`: Command timeout (10 seconds) + +### Caching Strategy + +To reduce API calls and improve reliability: + +1. **Home Data**: Cached on disk, refreshed periodically +2. **Network Info**: Cached for 12 hours +3. **Device Capabilities**: Detected once and cached +4. **MQTT Subscriptions**: Kept alive for 60 seconds (idle timeout) + +### Testing + +Test structure mirrors the python module structure. For example, +the module `roborock.devices.traits.v1.maps` is tested in the file +`tests/devices/traits/v1/test_maps.py`. Each test file corresponds to a python +module. + +The test suite uses mocking extensively to avoid real devices: + +- `Mock` and `AsyncMock` for channels and sessions +- Fake message generators (`mqtt_packet.gen_publish()`) +- Snapshot testing for complex data structures +- Time-based tests use small timeouts (10-50ms) for speed + + +Example test structure: +```python +@pytest.fixture +def mock_mqtt_channel(): + """Mock MQTT channel that simulates responses.""" + channel = AsyncMock(spec=MqttChannel) + channel.response_queue = [] + + async def publish_side_effect(message): + # Simulate device response + if channel.response_queue: + response = channel.response_queue.pop(0) + await callback(response) + + channel.publish.side_effect = publish_side_effect + return channel +``` diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..607219af --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Roborock Documentation + +This directory contains lower level documentation for developers interested in: + +- Details about the lower level transport protocols used by the library +- Undocumented or unsupported device commands or RPCs +- The internal design of components of the library + +For details about using the library see the higher level documentation at https://python-roborock.github.io/python-roborock/ diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md new file mode 100644 index 00000000..d59317e1 --- /dev/null +++ b/docs/V1_API_COMMANDS.md @@ -0,0 +1,1762 @@ +# Api commands + +This page is still under construction. All of the following are the commands we have reverse engineered. It is not an exhaustive list of all the possible commands. + +Commands do not immediately make it to this page. You can find more commands [here](https://github.com/humbertogontijo/python-roborock/blob/main/roborock/roborock_typing.py#L18) + +Commands can have multiple parameters that can change from one model to another. + +* [app_charge](#app_charge) +* [app_get_dryer_setting](#app_get_dryer_setting) +* [app_get_init_status](#app_get_init_status) +* [app_pause](#app_pause) +* [app_rc_end](#app_rc_end) +* [app_rc_move](#app_rc_move) +* [app_rc_start](#app_rc_start) +* [app_rc_stop](#app_rc_stop) +* [app_segment_clean](#app_segment_clean) +* [app_set_dryer_setting](#app_set_dryer_setting) +* [app_start_collect_dust](#app_start_collect_dust) +* [app_start_wash](#app_start_wash) +* [app_start](#app_start) +* [app_stop_collect_dust](#app_stop_collect_dust) +* [app_stop_wash](#app_stop_wash) +* [app_stop](#app_stop) +* [change_sound_volume](#change_sound_volume) +* [close_dnd_timer](#close_dnd_timer) +* [del_server_timer](#del_server_timer) +* [dnld_install_sound](#dnld_install_sound) +* [get_clean_sequence](#get_clean_sequence) +* [get_consumable](#get_consumable) +* [get_custom_mode](#get_custom_mode) +* [get_customize_clean_mode](#get_customize_clean_mode) +* [get_dnd_timer](#get_dnd_timer) +* [get_dust_collection_mode](#get_dust_collection_mode) +* [get_clean_follow_ground_material_status](#get_clean_follow_ground_material_status) +* [get_identify_furniture_status](#get_identify_furniture_status) +* [get_identify_ground_material_status](#get_identify_ground_material_status) +* [get_led_status](#get_led_status) +* [get_map_v1](#get_map_v1) +* [get_multi_map](#get_multi_map) +* [get_multi_maps_list](#get_multi_maps_list) +* [get_network_info](#get_network_info) +* [get_prop](#get_prop) +* [get_room_mapping](#get_room_mapping) +* [get_scenes_valid_tids](#get_scenes_valid_tids) +* [get_serial_number](#get_serial_number) +* [get_smart_wash_params](#get_smart_wash_params) +* [get_sound_progress](#get_sound_progress) +* [get_status](#get_status) +* [get_timezone](#get_timezone) +* [get_turn_server](#get_turn_server) +* [get_valley_electricity_timer](#get_valley_electricity_timer) +* [get_wash_towel_mode](#get_wash_towel_mode) +* [load_multi_map](#load_multi_map) +* [name_segment](#name_segment) +* [reset_consumable](#reset_consumable) +* [resume_segment_clean](#resume_segment_clean) +* [resume_zoned_clean](#resume_zoned_clean) +* [retry_request](#retry_request) +* [reunion_scenes](#reunion_scenes) +* [save_map](#save_map) +* [send_ice_to_robot](#send_ice_to_robot) +* [send_sdp_to_robot](#send_sdp_to_robot) +* [set_server_timer](#set_server_timer) +* [set_clean_motor_mode](#set_clean_motor_mode) +* [set_customize_clean_mode](#set_customize_clean_mode) +* [set_dnd_timer](#set_dnd_timer) +* [set_dust_collection_mode](#set_dust_collection_mode) +* [set_fds_endpoint](#set_fds_endpoint) +* [set_identify_furniture_status](#set_identify_furniture_status) +* [set_identify_ground_material_status](#set_identify_ground_material_status) +* [set_led_status](#set_led_status) +* [set_mop_mode](#set_mop_mode) +* [set_scenes_segments](#set_scenes_segments) +* [set_scenes_zones](#set_scenes_zones) +* [set_segment_ground_material](#set_segment_ground_material) +* [set_smart_wash_params](#set_smart_wash_params) +* [set_timezone](#set_timezone) +* [set_valley_electricity_timer](#set_valley_electricity_timer) +* [set_wash_towel_mode](#set_wash_towel_mode) +* [set_water_box_custom_mode](#set_water_box_custom_mode) +* [start_camera_preview](#start_camera_preview) +* [start_edit_map](#start_edit_map) +* [start_voice_chat](#start_voice_chat) +* [start_wash_then_charge](#start_wash_then_charge) +* [stop_camera_preview](#stop_camera_preview) +* [stop_segment_clean](#stop_segment_clean) +* [test_sound_volume](#test_sound_volume) +* [upd_server_timer](#upd_server_timer) + + +## Robot status + +### get_status + +Description: Returns the current status of the vacuum + +Parameters: None + +Returns: + + msg_ver: + + msg_seq: + + state: + + battery: Battery level of your device. + + clean_time: Total clean time in hours. + + clean_area: Total clean area in meters. + + error_code: + + map_reset: + + in_cleaning: + + in_returning: + + in_fresh_state: + + lab_status: + + water_box_status: + + back_type: + + wash_phase: + + wash_ready: + + fan_power: + + dnd_enabled: + + map_status: + + is_locating: + + lock_status: + + water_box_mode: + + water_box_carriage_status: + + mop_forbidden_enable: + + camera_status: + + is_exploring: + + home_sec_status: + + home_sec_enable_password: + + adbumper_status: + + water_shortage_status: + + dock_type: + + dust_collection_status: + + auto_dust_collection: + + avoid_count: + + mop_mode: + + debug_mode: + + collision_avoid_status: + + switch_map_mode: + + dock_error_status: + + charge_status: + + unsave_map_reason: + + unsave_map_flag: + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + +## App vacuum control + +### app_start + +Description: + +Parameters: + +### app_pause + +Description: This pauses the vacuum's current task + +Parameters: None + +Returns ok or error + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### app_stop + +Description: + +Parameters: + + +### app_start_collect_dust + +Description: This empties the bin while docked + +Parameters: None + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### app_stop_collect_dust + +Description: This stops the emptying of the dust bin while docked + +Parameters: None + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### app_start_wash + +Description: This washes the mop while docked + +Parameters: None + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + + +### app_stop_wash + +Description: This stops washing the mop whiloe docked + +Parameters: None + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### app_goto_target + +Description: Got to target + +Parameters: + - X coordinate as integer (e.g.: 23450) + - Y coordinate as integer (e.g.: 16450) + +Returns ok or error + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### app_charge + +Description: This tells your vacuum to go back to the dock and charge. + +Parameters: None + +Returns : ok or error + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +## App status + +### app_get_init_status + +Description: Returns details on the app being used to interact with Roborock servers ?? In this case the app is backend supporting the HA integration ? + +Parameters: None + +Returns: + + local_info: + + name: Name of the app + + bom: Version of the app + + location: Location of the app + + language: Language of the app + + wifiplan: Wifi plan of the app + + timezone: Timezone of the app + + logserver: Log server of the app + + featureset: Featureset of the app + + feature_info: List of features + + new_feature_info: New feature info + +Return example: +```json + {'local_info': {'name': 'custom_A.03.0342_CE', 'bom': 'A.03.0342', 'location': 'de', 'language': 'en', 'wifiplan': '', 'timezone': 'Europe/Berlin', 'logserver': 'awsde0.fds.api.xiaomi.com', 'featureset': 3}, 'feature_info': [111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125], 'new_feature_info': 2247395306799103, 'new_feature_info_str': '00000008009EFFFE'} +``` + + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +## App dryer settings + +### app_get_dryer_setting + +Description: Get dock dryer settings. + +Parameters: None + +Returns: + + status: + + on: + + cliff_on: + + cliff_off + + count: + + dry_time: Duration dryer remains on in seconds. + + off: + + cliff_on: + + cliff_off: + + count: + +Return example: + +```json + {'status': 1, 'on': {'cliff_on': 1, 'cliff_off': 1, 'count': 10, 'dry_time': 7200}, 'off': {'cliff_on': 2, 'cliff_off': 1, 'count': 10}} +``` + +Source: Roborock S7 MaxV Ultra + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + +### app_set_dryer_setting + +Description: Set the time for the dryer to run + +Parameters: '{"status":1,"on":{"dry_time":14400}}' + +dry_time is the time in seconds the dryer will run for + +Returns ok or error + + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +## App remote control + +### app_rc_start + +Description: Starts remote control. + +Parameters: None + +Returns ok or error + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + + +### app_rc_move + +Description: Moves the robot in the direction specified + +Parameters: To be documented + +Returns ok or error + + + + +### app_rc_stop + +Description: Stops the remote control + +Parameters: None + +Returns ok or error + + + +### app_rc_end + +Description: Ends the remote control task + +Parameters: + +Returns ok or error + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + + + +## App other + +### app_set_smart_cliff_forbidden + +Description: + +Parameters: + + +### app_spot + +Description: + +Parameters: + + +### app_stat + +Description: This returns the current status of the vacuum + +Parameters: None + +Returns: ok or error + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### app_wakeup_robot + +Description: + +Parameters: + + +### app_zoned_clean + +Description: Starts a zone clean + +Parameters: + + + +Returns: ok or error + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +## Segments and Zones + +### app_segment_clean + +Description: This starts a segment clean and repeats it the number of times specified. + +Parameters: An array of segments to clean. Each segment is an integer with the segment id and the number of times to clean it. For example, to clean segment 18 twice, the parameter would be + + `[{'segments': [18], 'repeat': 2}]` + + + +Command: + `roborock -d command --device_id deviceIdRedacted --cmd app_segment_clean --params '[{"segments": [17,19], "repeat": 2}]'` + +Returns ok or error + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_segment_ground_material + +Description: Sets the groud material for the segment + +Parameters: "{'data':[[22,3,0]]}" + +Returns ok or error + +### name_segment + +Description: + +Parameters: To be determined + + + + +### resume_segment_clean + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### stop_segment_clean + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_scenes_zones + +Description: + +Parameters: + +### set_scenes_segments + +Description: + +Parameters: + + +### get_scenes_valid_tids + +Description: To be confirmed + +Parameters: None + + + +Returns: + +```json +[{'tid': '1699679077347', 'map_flag': 0, 'segs': [{'sid': 24}, {'sid': 20}, {'sid': 22}, {'sid': 18}]}, {'tid': '1699679236553', 'map_flag': 0, 'segs': [{'sid': 24}, {'sid': 20}, {'sid': 22}]}, {'tid': '1699679386045', 'map_flag': 0, 'segs': [{'sid': 16}, {'sid': 19}, {'sid': 17}]}, {'tid': '1699679335823', 'map_flag': 0, 'segs': [{'sid': 19}, {'sid': 16}, {'sid': 17}]}] +``` + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### resume_zoned_clean + +Description: + +Parameters: + +### reunion_scenes + +Description: + +Parameters: + +## Camera + +### start_camera_preview + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + +### stop_camera_preview + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + +### get_camera_status + +Description: Get camera status. + +Parameters: None + +Returns: 3457 +  387 Roborock S8 Pro Ultra + +Source: Roborock S7 MaxV Ultra + + +### set_camera_status + +Description: + +Parameters: + + + +### start_voice_chat + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + + +## Clean modes + +### get_carpet_clean_mode + +Description: Get carpet clean mode. + +Parameters: + +Returns: + + carpet_clean_mode: Enumeration for carpet clean mode. + +Return example: + +```json + {'carpet_clean_mode': 3} +``` + +Source: Roborock S7 MaxV Ultra + + +### set_carpet_clean_mode + +Description: + +Parameters: + +### get_carpet_mode + +Description: + +Parameters: None + +Returns: + + enable: + + current_integral: + + current_high: + + current_low: + + stall_time: + +Return example: + +```json + {'enable': 1, 'current_integral': 450, 'current_high': 500, 'current_low': 400, 'stall_time': 10} +``` + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + +### set_carpet_mode + +Description: + +Parameters: + +### get_smart_wash_params + +Description: Returns the smartwash parameters + +Parameters: None + + + +Returns: + + smart_wash: 0 is off, 1 is on + + wash_interval: The interval in seconds between washes + +Example: + +```json +{'smart_wash': 0, 'wash_interval': 1200} +``` + + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_smart_wash_params + +Description: Sets the smartwash parameters + +Parameters: + + smart_wash: 0 is off, 1 is on + + wash_interval: The interval in seconds between washes + + +`{'smart_wash': 0, 'wash_interval': 1200}` + + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +## Cleaning history + +### get_clean_record + +Description: + +Parameters: To be determined + + +### get_clean_record_map + +Description: + +Parameters: + + +### get_clean_sequence + +Description: + +Parameters: + + +### get_clean_summary + +Description: Get a summary of cleaning history. + +Parameters: None + +Returns: + + clean_time: + + clean_area: + + clean_count: + + dust_collection_count: + + records: + +Return example: + +```json + {'clean_time': 568146, 'clean_area': 8816865000, 'clean_count': 178, 'dust_collection_count': 172, 'records': [1689740211, 1689555788, 1689259450, 1688999113, 1688852350, 1688693213, 1688692357, 1688614354, 1688613280, 1688606676, 1688325265, 1688174717, 1688149381, 1688092832, 1688001593, 1687921414, 1687890618, 1687743256, 1687655018, 1687631444]} +``` + +Source: Roborock S7 MaxV Ultra + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +### get_mop_template_params_summary + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + +## Child lock + +### get_child_lock_status + +Description: This gets the child lock status of the device. 0 is off, 1 is on. + +Parameters: None + +Returns: + + lock_status: + +Return example: + +```json + {'lock_status': 0} +``` + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_child_lock_status + +Description: This sets the child lock status of the device. + +Parameters: '{"lock_status" :0}' + +Returns: ok + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + + + + +## Consumables + +### get_consumable + +Description: This gets the status of all of the consumables for your device. + +Parameters: None + +Returns: + + main_brush_work_time: This is the amount of time the main brush has been used in seconds since it was last replaced + + side_brush_work_time: This is the amount of time the side brush has been used in seconds since it was last replaced + + filter_work_time: This is the amount of time the air filter inside the vacuum has been used in seconds since it was last replaced + + filter_element_work_time: + + sensor_dirty_time: This is the amount of time since you have cleaned the sensors on the bottom of your vacuum. + + strainer_work_times: + + dust_collection_work_times: + + cleaning_brush_work_times: + +Return examples: + +```json + {'main_brush_work_time': 14151, 'side_brush_work_time': 41638, 'filter_work_time': 14151, 'filter_element_work_time': 0, 'sensor_dirty_time': 41522, 'strainer_work_times': 44, 'dust_collection_work_times': 19, 'cleaning_brush_work_times': 44} +``` + + +### reset_consumable + +Description: + +Parameters: List of consumables to reset. For example, to reset consumables 'strainer_work_times' and 'sensor_dirty_time' the parameter would be + + `['strainer_work_times', 'sensor_dirty_time']` + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +## Custom modes + +### get_custom_mode + +Description: It returns the current custom mode. + +Parameters: None + +Returns: + + integer value of the current custom mode + +Return example: + +``` + 102 +``` + + + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + +### set_custom_mode + +Description: + +Parameters: + +### get_customize_clean_mode + +Description: + +Parameters: + + +### set_customize_clean_mode + +Description: + +Parameters: + +## Furniture and ground material + +### get_identify_furniture_status + +Description: + +Parameters: + + + +### set_identify_furniture_status + +Description: + +Parameters: + + + + +### get_identify_ground_material_status + +Description: + +Parameters: + + + + +### set_identify_ground_material_status + +Description: + +Parameters: + + + + + +## LEDs + +### get_flow_led_status + +Description: + +Parameters: + + +### set_flow_led_status + +Description: + +Parameters: + +### get_led_status + +Description: Returns the LED status. If disabled the indicator light will turn off 1 minute after fully charged + +Parameters: + +Returns: + + led_status: 0 is off, 1 is on + + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_led_status + +Description: Sets the LED status. If disabled the indicator light will turn off 1 minute after fully charged + +Parameters: ???? + + + + + + +## Maps + +### get_multi_map + +Description: + +Parameters: + +Comment: Response timed out for S8 Pro Ultra + + + +### get_multi_maps_list + +Description: Returns a list of map information stored on the device. + +Parameters: None required + +Returns: + + max_multi_map: + max_bak_map: + multi_map_count: + map_info: + + mapFlag: + add_time: + length: + name: + bak_maps: + + mapFlag: + add_time: + + +Return example: + +```json + {'max_multi_map': 4, 'max_bak_map': 1, 'multi_map_count': 2, 'map_info': [{'mapFlag': 0, 'add_time': 1699919699, 'length': 4, 'name': 'Home', 'bak_maps': [{'mapFlag': 4, 'add_time': 1699823921}]}, {'mapFlag': 1, 'add_time': 1699828035, 'length': 13, 'name': 'Boys bathroom', 'bak_maps': [{'mapFlag': 5, 'add_time': 1699828035}]}]} +``` + +Source: S8 Pro Ultra + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### get_map_v1 + +Description: Returns the map + +Parameters: Unknown + +Comment: Returns a map in a format that is not yet understood by me + + + +### start_edit_map + +Description: + +Parameters: + + +### get_room_mapping + +Description: Returns a list of rooms, ids as discovered by + +Parameters: None + +Returns: + + room_id + +Return example: + +```json + [[16, '14731399', 12], [17, '2220009', 2], [18, '2219688', 12], [19, '2219685', 9], [20, '2219691', 12], [21, '2431758', 12], [22, '2219677', 13], [23, '2312548', 12], [24, '2219678', 14], [25, '2219686', 15], [26, '2219772', 12], [27, '14768755', 12]] +``` + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + +### load_multi_map + +Description: + +Parameters: number (the floor/map index) + + + + +### save_map + +Description: + +Parameters: + +## Operating modes + +### get_mop_mode + +Description: Get mop mode. + +Parameters: None + +Returns: Enumeration for mop mode. 300 + +Example for S8 Pro Ultra: + + standard = 300 + deep = 301 + deep_plus = 303 + fast = 304 + custom = 302 + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_mop_mode + +Description: Set mop mode. + +Parameters: mop_mode 300 + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_clean_motor_mode + +Description: + +Parameters: + +### get_dust_collection_mode + +Description: + +Parameters: None + +Returns: + + mode: + +Return example: + +```json + {'mode': 0} +``` + +Source: Roborock S7 MaxV Ultra + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +### set_dust_collection_mode + +Description: + +Parameters: + +### get_wash_towel_mode + +Description: + +Parameters: None + +Returns: + + wash_mode: + +Return example: + +```json + {'wash_mode': 1} +``` + +Source: Roborock S7 MaxV Ultra + + + unknown = -9999 + + light = 0 + + balanced = 1 + + deep = 2 + + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +### set_wash_towel_mode + +Description: Sets the wash wash_towel_mode + +Parameters: {'wash_mode': 2} + +Returns: ok or error + +Source: S8 Pro Ultra + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + +### get_collision_avoid_status + +Description: + +Parameters: None + +Returns: + + status: + +Return example: + +```json + {'status': 1} +``` + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +### set_collision_avoid_status + +Description: Update collision avoid status. + +Parameters: '{"status" :1}' + +Returns: + + ok + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +### start_wash_then_charge + +Description: + +Parameters: + + + +### switch_water_mark + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + + + +## System information + +### get_network_info + +Description: Get the device's network information. + +Parameters: None + +Returns: + + ssid: SSID of the wirelness network the device is connected to. + + ip: IP address of the device. + + mac: MAC address of the device. + + bssid: BSSID of the device. + + rssi: RSSI of the device. + +Return example: + +```json + {'ssid': 'My WiFi Network', 'ip': '192.168.1.29', 'mac': 'a0:2b:47:3d:24:51', 'bssid': '18:3b:1a:23:41:3c', 'rssi': -32} +``` + +Source: Roborock S7 MaxV Ultra + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +### get_serial_number + +Description: Get serial number of the vacuum. + +Parameters: None + +Returns: + + serial_number: Serial number of the vacuum. + +Return example: + +```json + {'serial_number': 'B16EVD12345678'} +``` + +Source: Roborock S7 MaxV Ultra + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + +### get_prop + +Description: Generic get property command + +Parameters: The property to get + +Example: + + roborock -d command --device_id aHiddenDeviceId --cmd get_prop --params '["battery"]' + + + +Comment : This example returns the same as get_status. Initial testing has shown that not all get commands are supported by this method + + +### get_turn_server + +Description: + +Parameters: + + + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + + +### enable_log_upload + +Description: + +Parameters: + + +### find_me + +Description: This makes your vacuum speak so you can find it. + +Parameters: None + +### upd_server_timer + +Description: + +Parameters: + +### get_homesec_connect_status + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + + +### set_fds_endpoint + +Description: + +Parameters: + +### send_ice_to_robot + +Description: + +Parameters: + + +### send_sdp_to_robot + +Description: + +Parameters: + +### get_device_ice + + + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + +### get_device_sdp + +Description: + +Parameters: + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❌ + +### retry_request + +Description: + +Parameters: + +## Timers + +### del_server_timer + +Description: + +Parameters: + + +### dnd_timer + +### get_dnd_timer + +Description: Gets the do not disturb timer + + start_hour: The hour you want dnd to start + + start_minute: The minute you want dnd to start + + end_hour: The hour you want dnd to be turned off + + end_minute: The minute you want dnd to be turned off + + enabled: If the switch is currently turned on in the app for DnD + +Parameters: None + + +### set_dnd_timer + +Description: + +Parameters: + + +### close_dnd_timer + +Description: This disables the dnd timer + +Parameters: None + +### get_server_timer + +Description: + +Parameters: + + +### set_server_timer + +Description: + +Parameters: + +### get_timezone + +Description: Get the device's time zone. + +Parameters: None + +Returns: Time zone by the TZ identifier (e.g., America/Los_Angeles) + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + + +### set_timezone + +Description: Sets the device's time zone + +Parameters: + + + + +## Sound + +### get_sound_volume + +Description: Returns the volume of the sound played by the vacuum + +Parameters: None + +Returns: + + volume: The volume of the sound played by the vacuum + +Example: + + 72 + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### change_sound_volume + +Description: Sets the volume of the sound played by the vacuum + +Parameters: volume + +Returns: ok or error + +`roborock -d command --device_id aHiddenDeviceId --cmd change_sound_volume --params 72` + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### test_sound_volume + +Description: Plays a sound on the vacumm to identity volume + +Parameters: None + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + + +### get_sound_progress + +Description: + +Parameters: + +Returns: + +```json +{'sid_in_progress': 0, 'progress': 0, 'state': 0, 'error': 0} +``` + + + + +### get_current_sound + + + +Description: + +Parameters: + +Return example: + +```json + {'sid_in_use': 122, 'sid_version': 1, 'sid_in_progress': 0, 'location': 'de', 'bom': 'A.03.0342', 'language': 'en', 'msg_ver': 2} +``` + +**Supported devices:** + +* Roborock S7 MaxV Ultra: ✅ +* Roborock S8 Pro Ultra: ✅ + +### dnld_install_sound + +Description: + +Parameters: + +## Off peak charging + +### get_valley_electricity_timer + +Description: Get valley electricity timer. + +Parameters: None + +Returns: + + start_hour: The hour you want valley electricity to start + + start_minute: The minute you want valley electricity to start + + end_hour: The hour you want valley electricity to be turned off + + end_minute: The minute you want valley electricity to be turned off + + enabled: If the switch is currently turned on in the app for valley electricity + + +```json +{'start_hour': 0, 'start_minute': 0, 'end_hour': 0, 'end_minute': 0, 'enabled': 0} +``` + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_valley_electricity_timer + +Description: Sets the valley electricity timer + +Parameters: + + start_hour: The hour you want valley electricity to start + + start_minute: The minute you want valley electricity to start + + end_hour: The hour you want valley electricity to be turned off + + end_minute: The minute you want valley electricity to be turned off + + enabled: If the switch is currently turned on in the app for valley electricity + +Example: + +```json +{'start_hour': 0, 'start_minute': 0, 'end_hour': 0, 'end_minute': 0, 'enabled': 0} +``` + + + + +**Supported devices:** + +* Roborock S8 Pro Ultra: ❓ + + + + +## Water box mode + +### get_water_box_custom_mode + +Description: Get water box mode. + +Parameters: None + +Returns: Enumeration for water box mode. 203 + + + + +### get_clean_follow_ground_material_status + +Description: + +Parameters: None + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ + +### set_water_box_custom_mode + +Description: Set the water box mode. + +Parameters: {'water_box_mode': 203} + +Returns: ok or error + + + +**Supported devices:** + +* Roborock S8 Pro Ultra: ✅ diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 9534b018..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index f023341c..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -sphinx - -sphinx_rtd_theme diff --git a/docs/source/_templates/footer.html b/docs/source/_templates/footer.html deleted file mode 100644 index 768ee7a9..00000000 --- a/docs/source/_templates/footer.html +++ /dev/null @@ -1,5 +0,0 @@ -{% extends "!footer.html" %} -{%- block contentinfo %} -{{ super() }} -

We are looking for contributors to help with our documentation, if you are interested please contribute here. -{% endblock %} diff --git a/docs/source/api_commands.rst b/docs/source/api_commands.rst deleted file mode 100644 index 668f74e7..00000000 --- a/docs/source/api_commands.rst +++ /dev/null @@ -1,1950 +0,0 @@ -Api commands -============ -This page is still under construction. All of the following are the commands we have reverse engineered. It is not an exhaustive list of all the possible commands. - -Commands do not immediately make it to this page. You can find more commands [here](https://github.com/humbertogontijo/python-roborock/blob/main/roborock/roborock_typing.py#L18) - -Commands can have multiple parameters that can change from one model to another. - -* :ref:`app_charge` -* :ref:`app_get_dryer_setting` -* :ref:`app_get_init_status` -* :ref:`app_pause` -* :ref:`app_rc_end` -* :ref:`app_rc_move` -* :ref:`app_rc_start` -* :ref:`app_rc_stop` -* :ref:`app_segment_clean` -* :ref:`app_set_dryer_setting` -* :ref:`app_start_collect_dust` -* :ref:`app_start_wash` -* :ref:`app_start` -* :ref:`app_stop_collect_dust` -* :ref:`app_stop_wash` -* :ref:`app_stop` -* :ref:`change_sound_volume` -* :ref:`close_dnd_timer` -* :ref:`del_server_timer` -* :ref:`dnld_install_sound` -* :ref:`get_clean_sequence` -* :ref:`get_consumable` -* :ref:`get_custom_mode` -* :ref:`get_customize_clean_mode` -* :ref:`get_dnd_timer` -* :ref:`get_dust_collection_mode` -* :ref:`get_clean_follow_ground_material_status` -* :ref:`get_identify_furniture_status` -* :ref:`get_identify_ground_material_status` -* :ref:`get_led_status` -* :ref:`get_map_v1` -* :ref:`get_multi_map` -* :ref:`get_multi_maps_list` -* :ref:`get_network_info` -* :ref:`get_prop` -* :ref:`get_room_mapping` -* :ref:`get_scenes_valid_tids` -* :ref:`get_serial_number` -* :ref:`get_smart_wash_params` -* :ref:`get_sound_progress` -* :ref:`get_status` -* :ref:`get_timezone` -* :ref:`get_turn_server` -* :ref:`get_valley_electricity_timer` -* :ref:`get_wash_towel_mode` -* :ref:`load_multi_map` -* :ref:`name_segment` -* :ref:`reset_consumable` -* :ref:`resume_segment_clean` -* :ref:`resume_zoned_clean` -* :ref:`retry_request` -* :ref:`reunion_scenes` -* :ref:`save_map` -* :ref:`send_ice_to_robot` -* :ref:`send_sdp_to_robot` -* :ref:`set_server_timer` -* :ref:`set_clean_motor_mode` -* :ref:`set_customize_clean_mode` -* :ref:`set_dnd_timer` -* :ref:`set_dust_collection_mode` -* :ref:`set_fds_endpoint` -* :ref:`set_identify_furniture_status` -* :ref:`set_identify_ground_material_status` -* :ref:`set_led_status` -* :ref:`set_mop_mode` -* :ref:`set_scenes_segments` -* :ref:`set_scenes_zones` -* :ref:`set_segment_ground_material` -* :ref:`set_smart_wash_params` -* :ref:`set_timezone` -* :ref:`set_valley_electricity_timer` -* :ref:`set_wash_towel_mode` -* :ref:`set_water_box_custom_mode` -* :ref:`start_camera_preview` -* :ref:`start_edit_map` -* :ref:`start_voice_chat` -* :ref:`start_wash_then_charge` -* :ref:`stop_camera_preview` -* :ref:`stop_segment_clean` -* :ref:`test_sound_volume` -* :ref:`upd_server_timer` - - -Robot status ------------- - -get_status -~~~~~~~~~~ - -Description: Returns the current status of the vacuum - -Parameters: None - -Returns: - - msg_ver: - - msg_seq: - - state: - - battery: Battery level of your device. - - clean_time: Total clean time in hours. - - clean_area: Total clean area in meters. - - error_code: - - map_reset: - - in_cleaning: - - in_returning: - - in_fresh_state: - - lab_status: - - water_box_status: - - back_type: - - wash_phase: - - wash_ready: - - fan_power: - - dnd_enabled: - - map_status: - - is_locating: - - lock_status: - - water_box_mode: - - water_box_carriage_status: - - mop_forbidden_enable: - - camera_status: - - is_exploring: - - home_sec_status: - - home_sec_enable_password: - - adbumper_status: - - water_shortage_status: - - dock_type: - - dust_collection_status: - - auto_dust_collection: - - avoid_count: - - mop_mode: - - debug_mode: - - collision_avoid_status: - - switch_map_mode: - - dock_error_status: - - charge_status: - - unsave_map_reason: - - unsave_map_flag: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - -App vacuum control ------------------- - -app_start -~~~~~~~~~ - -Description: - -Parameters: - -app_pause -~~~~~~~~~ - -Description: This pauses the vacuum's current task - -Parameters: None - -Returns ok or error - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -app_stop -~~~~~~~~ - -Description: - -Parameters: - - -app_start_collect_dust -~~~~~~~~~~~~~~~~~~~~~~ - -Description: This empties the bin while docked - -Parameters: None - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -app_stop_collect_dust -~~~~~~~~~~~~~~~~~~~~~~ - -Description: This stops the emptying of the dust bin while docked - -Parameters: None - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -app_start_wash -~~~~~~~~~~~~~~ - -Description: This washes the mop while docked - -Parameters: None - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - - -app_stop_wash -~~~~~~~~~~~~~ - -Description: This stops washing the mop whiloe docked - -Parameters: None - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -app_goto_target -~~~~~~~~~~~~~~~ - -Description: Got to target - -Parameters: - - X coordinate as integer (e.g.: 23450) - - Y coordinate as integer (e.g.: 16450) - -Returns ok or error - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -app_charge -~~~~~~~~~~ - -Description: This tells your vacuum to go back to the dock and charge. - -Parameters: None - -Returns : ok or error - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -App status ----------- - -app_get_init_status -~~~~~~~~~~~~~~~~~~~ - -Description: Returns details on the app being used to interact with Roborock servers ?? In this case the app is backend supporting the HA integration ? - -Parameters: None - -Returns: - - local_info: - - name: Name of the app - - bom: Version of the app - - location: Location of the app - - language: Language of the app - - wifiplan: Wifi plan of the app - - timezone: Timezone of the app - - logserver: Log server of the app - - featureset: Featureset of the app - - feature_info: List of features - - new_feature_info: New feature info - -Return example:: - {'local_info': {'name': 'custom_A.03.0342_CE', 'bom': 'A.03.0342', 'location': 'de', 'language': 'en', 'wifiplan': '', 'timezone': 'Europe/Berlin', 'logserver': 'awsde0.fds.api.xiaomi.com', 'featureset': 3}, 'feature_info': [111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125], 'new_feature_info': 2247395306799103, 'new_feature_info_str': '00000008009EFFFE'} - - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -App dryer settings ------------------- - -app_get_dryer_setting -~~~~~~~~~~~~~~~~~~~~~ - -Description: Get dock dryer settings. - -Parameters: None - -Returns: - - status: - - on: - - cliff_on: - - cliff_off - - count: - - dry_time: Duration dryer remains on in seconds. - - off: - - cliff_on: - - cliff_off: - - count: - -Return example:: - - {'status': 1, 'on': {'cliff_on': 1, 'cliff_off': 1, 'count': 10, 'dry_time': 7200}, 'off': {'cliff_on': 2, 'cliff_off': 1, 'count': 10}} - -Source: Roborock S7 MaxV Ultra - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - -app_set_dryer_setting -~~~~~~~~~~~~~~~~~~~~~ - -Description: Set the time for the dryer to run - -Parameters: '{"status":1,"on":{"dry_time":14400}}' - -dry_time is the time in seconds the dryer will run for - -Returns ok or error - - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -App remote control ------------------- - -app_rc_start -~~~~~~~~~~~~ - -Description: Starts remote control. - -Parameters: None - -Returns ok or error - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - - -app_rc_move -~~~~~~~~~~~ - -Description: Moves the robot in the direction specified - -Parameters: To be documented - -Returns ok or error - -.. - Need to document the parameters - will need to explore the app to find out what they are - - -app_rc_stop -~~~~~~~~~~~ - -Description: Stops the remote control - -Parameters: None - -Returns ok or error - -.. - Assume stop stops a move ?? Need to check - -app_rc_end -~~~~~~~~~~ - -Description: Ends the remote control task - -Parameters: - -Returns ok or error - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - - - -App other ---------- - -app_set_smart_cliff_forbidden -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -app_spot -~~~~~~~~ - -Description: - -Parameters: - - -app_stat -~~~~~~~~ - -Description: This returns the current status of the vacuum - -Parameters: None - -Returns: ok or error - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -app_wakeup_robot -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -app_zoned_clean -~~~~~~~~~~~~~~~ - -Description: Starts a zone clean - -Parameters: - -.. - Us this the last known zone - -Returns: ok or error - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -Segments and Zones ------------------- - -app_segment_clean -~~~~~~~~~~~~~~~~~ - -Description: This starts a segment clean and repeats it the number of times specified. - -Parameters: An array of segments to clean. Each segment is an integer with the segment id and the number of times to clean it. For example, to clean segment 18 twice, the parameter would be - - [{'segments': [18], 'repeat': 2}] - -.. Comment: The segment id can be obtained from the initial data returned on login - -Command: - roborock -d command --device_id deviceIdRedacted --cmd app_segment_clean --params '[{"segments": [17,19], "repeat": 2}]' - -Returns ok or error - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_segment_ground_material -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: Sets the groud material for the segment - -Parameters: "{'data':[[22,3,0]]}" - -Returns ok or error - -name_segment -~~~~~~~~~~~~ - -Description: - -Parameters: To be determined - -.. - Need to work out parameter format - Does this allow us to name a segment ? - - -resume_segment_clean -~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -stop_segment_clean -~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_scenes_zones -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -set_scenes_segments -~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -get_scenes_valid_tids -~~~~~~~~~~~~~~~~~~~~~ - -Description: To be confirmed - -Parameters: None - -.. - Appears to be associated with rooms ?? - -Returns:: - -[{'tid': '1699679077347', 'map_flag': 0, 'segs': [{'sid': 24}, {'sid': 20}, {'sid': 22}, {'sid': 18}]}, {'tid': '1699679236553', 'map_flag': 0, 'segs': [{'sid': 24}, {'sid': 20}, {'sid': 22}]}, {'tid': '1699679386045', 'map_flag': 0, 'segs': [{'sid': 16}, {'sid': 19}, {'sid': 17}]}, {'tid': '1699679335823', 'map_flag': 0, 'segs': [{'sid': 19}, {'sid': 16}, {'sid': 17}]}] - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -resume_zoned_clean -~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -reunion_scenes -~~~~~~~~~~~~~~ - -Description: - -Parameters: - -Camera ------- - -start_camera_preview -~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - -stop_camera_preview -~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - -get_camera_status -~~~~~~~~~~~~~~~~~ - -Description: Get camera status. - -Parameters: None - -Returns: 3457 -  387 Roborock S8 Pro Ultra - -Source: Roborock S7 MaxV Ultra - - -set_camera_status -~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - - -start_voice_chat -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - - -Clean modes ------------------ - -get_carpet_clean_mode -~~~~~~~~~~~~~~~~~~~~~ - -Description: Get carpet clean mode. - -Parameters: - -Returns: - - carpet_clean_mode: Enumeration for carpet clean mode. - -Return example:: - - {'carpet_clean_mode': 3} - -Source: Roborock S7 MaxV Ultra - - -set_carpet_clean_mode -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_carpet_mode -~~~~~~~~~~~~~~~ - -Description: - -Parameters: None - -Returns: - - enable: - - current_integral: - - current_high: - - current_low: - - stall_time: - -Return example:: - - {'enable': 1, 'current_integral': 450, 'current_high': 500, 'current_low': 400, 'stall_time': 10} - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - -set_carpet_mode -~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_smart_wash_params -~~~~~~~~~~~~~~~~~~~~~ - -Description: Returns the smartwash parameters - -Parameters: None - -.. - Not clear what this does - -Returns: - - smart_wash: 0 is off, 1 is on - - wash_interval: The interval in seconds between washes - -Example:: - -{'smart_wash': 0, 'wash_interval': 1200} - - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_smart_wash_params -~~~~~~~~~~~~~~~~~~~~~ - -Description: Sets the smartwash parameters - -Parameters: - - smart_wash: 0 is off, 1 is on - - wash_interval: The interval in seconds between washes - - -{'smart_wash': 0, 'wash_interval': 1200} - - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -Cleaning history ----------------- - -get_clean_record -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: To be determined - - -get_clean_record_map -~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -get_clean_sequence -~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -get_clean_summary -~~~~~~~~~~~~~~~~~ - -Description: Get a summary of cleaning history. - -Parameters: None - -Returns: - - clean_time: - - clean_area: - - clean_count: - - dust_collection_count: - - records: - -Return example:: - - {'clean_time': 568146, 'clean_area': 8816865000, 'clean_count': 178, 'dust_collection_count': 172, 'records': [1689740211, 1689555788, 1689259450, 1688999113, 1688852350, 1688693213, 1688692357, 1688614354, 1688613280, 1688606676, 1688325265, 1688174717, 1688149381, 1688092832, 1688001593, 1687921414, 1687890618, 1687743256, 1687655018, 1687631444]} - -Source: Roborock S7 MaxV Ultra - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -get_mop_template_params_summary -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - -Child lock ----------- - -get_child_lock_status -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: This gets the child lock status of the device. 0 is off, 1 is on. - -Parameters: None - -Returns: - - lock_status: - -Return example:: - - {'lock_status': 0} - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_child_lock_status -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: This sets the child lock status of the device. - -Parameters: '{"lock_status" :0}' - -Returns: ok - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - - - - -Consumables ------------ - -get_consumable -~~~~~~~~~~~~~~ - -Description: This gets the status of all of the consumables for your device. - -Parameters: None - -Returns: - - main_brush_work_time: This is the amount of time the main brush has been used in seconds since it was last replaced - - side_brush_work_time: This is the amount of time the side brush has been used in seconds since it was last replaced - - filter_work_time: This is the amount of time the air filter inside the vacuum has been used in seconds since it was last replaced - - filter_element_work_time: - - sensor_dirty_time: This is the amount of time since you have cleaned the sensors on the bottom of your vacuum. - - strainer_work_times: - - dust_collection_work_times: - - cleaning_brush_work_times: - -Return examples:: - - {'main_brush_work_time': 14151, 'side_brush_work_time': 41638, 'filter_work_time': 14151, 'filter_element_work_time': 0, 'sensor_dirty_time': 41522, 'strainer_work_times': 44, 'dust_collection_work_times': 19, 'cleaning_brush_work_times': 44} - - -reset_consumable -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: List of consumables to reset. For example, to reset consumables 'strainer_work_times' and 'sensor_dirty_time' the parameter would be - - ['strainer_work_times', 'sensor_dirty_time'] - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -Custom modes ------------- - -get_custom_mode -~~~~~~~~~~~~~~~~~~~~ - -Description: It returns the current custom mode. - -Parameters: None - -Returns: - - integer value of the current custom mode - -Return example:: - - 102 - -.. - Not clear what a custom mode is = will explore - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - -set_custom_mode -~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_customize_clean_mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -set_customize_clean_mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -Furniture and ground material ------------------------------ - -get_identify_furniture_status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -.. - Does not return anything for S8 Pro Ultra when docked may require vacumm to be cleaning - -set_identify_furniture_status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -.. - Method not known for S8 Pro Ultra - - -get_identify_ground_material_status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -.. - Does not return anything for S8 Pro Ultra when docked may require vacumm to be cleaning - - -set_identify_ground_material_status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -.. - Method not known for S8 Pro Ultra - - - -LEDs ----- - -get_flow_led_status -~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -set_flow_led_status -~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_led_status -~~~~~~~~~~~~~~~~~~~ - -Description: Returns the LED status. If disabled the indicator light will turn off 1 minute after fully charged - -Parameters: - -Returns: - - led_status: 0 is off, 1 is on - - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_led_status -~~~~~~~~~~~~~~ - -Description: Sets the LED status. If disabled the indicator light will turn off 1 minute after fully charged - -Parameters: ???? - -.. - Need to work out parameter format - - - - -Maps ----- - -get_multi_map -~~~~~~~~~~~~~ - -Description: - -Parameters: - -Comment: Response timed out for S8 Pro Ultra - -.. - times out after 4 secs - -get_multi_maps_list -~~~~~~~~~~~~~~~~~~~ - -Description: Returns a list of map information stored on the device. - -Parameters: None required - -Returns: - - max_multi_map: - max_bak_map: - multi_map_count: - map_info:: - - mapFlag: - add_time: - length: - name: - bak_maps:: - - mapFlag: - add_time: - - -Return example:: - - {'max_multi_map': 4, 'max_bak_map': 1, 'multi_map_count': 2, 'map_info': [{'mapFlag': 0, 'add_time': 1699919699, 'length': 4, 'name': 'Home', 'bak_maps': [{'mapFlag': 4, 'add_time': 1699823921}]}, {'mapFlag': 1, 'add_time': 1699828035, 'length': 13, 'name': 'Boys bathroom', 'bak_maps': [{'mapFlag': 5, 'add_time': 1699828035}]}]} - -Source: S8 Pro Ultra - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -get_map_v1 -~~~~~~~~~~ - -Description: Returns the map - -Parameters: Unknown - -Comment: Returns a map in a format that is not yet understood by me - -.. - Explore what parameters it may take - Extend code to return byte stream ? - -start_edit_map -~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -get_room_mapping -~~~~~~~~~~~~~~~~ - -Description: Returns a list of rooms, ids as discovered by - -Parameters: None - -Returns: - - room_id - -Return example:: - - [[16, '14731399', 12], [17, '2220009', 2], [18, '2219688', 12], [19, '2219685', 9], [20, '2219691', 12], [21, '2431758', 12], [22, '2219677', 13], [23, '2312548', 12], [24, '2219678', 14], [25, '2219686', 15], [26, '2219772', 12], [27, '14768755', 12]] - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - -load_multi_map -~~~~~~~~~~~~~~ - -Description: - -Parameters: number (the floor/map index) - -.. - Need to work out parameter format - - -save_map -~~~~~~~~ - -Description: - -Parameters: - -Operating modes ---------------- - -get_mop_mode -~~~~~~~~~~~~ - -Description: Get mop mode. - -Parameters: None - -Returns: Enumeration for mop mode. 300 - -Example for S8 Pro Ultra:: - - standard = 300 - deep = 301 - deep_plus = 303 - fast = 304 - custom = 302 - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_mop_mode -~~~~~~~~~~~~ - -Description: Set mop mode. - -Parameters: mop_mode 300 - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_clean_motor_mode -~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_dust_collection_mode -~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: None - -Returns: - - mode: - -Return example:: - - {'mode': 0} - -Source: Roborock S7 MaxV Ultra - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -set_dust_collection_mode -~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_wash_towel_mode -~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: None - -Returns: - - wash_mode: - -Return example:: - - {'wash_mode': 1} - -Source: Roborock S7 MaxV Ultra - - - unknown = -9999 - - light = 0 - - balanced = 1 - - deep = 2 - - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -set_wash_towel_mode -~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: Sets the wash wash_towel_mode - -Parameters: {'wash_mode': 2} - -Returns: ok or error - -Source: S8 Pro Ultra - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - -get_collision_avoid_status -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: None - -Returns: - - status: - -Return example:: - - {'status': 1} - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -set_collision_avoid_status -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: Update collision avoid status. - -Parameters: '{"status" :1}' - -Returns: - - ok - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -start_wash_then_charge -~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -.. - While this returns ok on the S8 Pro Ultra it does not appear to do anything - -switch_water_mark -~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - -.. - Not found for S8 Pro Ultra - -System information ------------------- - -get_network_info -~~~~~~~~~~~~~~~~ - -Description: Get the device's network information. - -Parameters: None - -Returns: - - ssid: SSID of the wirelness network the device is connected to. - - ip: IP address of the device. - - mac: MAC address of the device. - - bssid: BSSID of the device. - - rssi: RSSI of the device. - -Return example:: - - {'ssid': 'My WiFi Network', 'ip': '192.168.1.29', 'mac': 'a0:2b:47:3d:24:51', 'bssid': '18:3b:1a:23:41:3c', 'rssi': -32} - -Source: Roborock S7 MaxV Ultra - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -get_serial_number -~~~~~~~~~~~~~~~~~ - -Description: Get serial number of the vacuum. - -Parameters: None - -Returns:: - - serial_number: Serial number of the vacuum. - -Return example:: - - {'serial_number': 'B16EVD12345678'} - -Source: Roborock S7 MaxV Ultra - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - -get_prop -~~~~~~~~ - -Description: Generic get property command - -Parameters: The property to get - -Example:: - - roborock -d command --device_id aHiddenDeviceId --cmd get_prop --params '["battery"]' - - - -Comment : This example returns the same as get_status. Initial testing has shown that not all get commands are supported by this method - - -get_turn_server -~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -.. - Not found for S8 Pro Ultra - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - - -enable_log_upload -~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -find_me -~~~~~~~ - -Description: This makes your vacuum speak so you can find it. - -Parameters: None - -upd_server_timer -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_homesec_connect_status -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - - -set_fds_endpoint -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -send_ice_to_robot -~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -send_sdp_to_robot -~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_device_ice -~~~~~~~~~~~~~~ - -.. - This doeas not appear to be supported on S8 Pro Ultra - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - -get_device_sdp -~~~~~~~~~~~~~~ - -Description: - -Parameters: - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra No -====================== ========= - -retry_request -~~~~~~~~~~~~~ - -Description: - -Parameters: - -Timers ------- - -del_server_timer -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -dnd_timer -~~~~~~~~~ - -get_dnd_timer -~~~~~~~~~~~~~ - -Description: Gets the do not disturb timer - - start_hour: The hour you want dnd to start - - start_minute: The minute you want dnd to start - - end_hour: The hour you want dnd to be turned off - - end_minute: The minute you want dnd to be turned off - - enabled: If the switch is currently turned on in the app for DnD - -Parameters: None - - -set_dnd_timer -~~~~~~~~~~~~~ - -Description: - -Parameters: - - -close_dnd_timer -~~~~~~~~~~~~~~~ - -Description: This disables the dnd timer - -Parameters: None - -get_server_timer -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - - -set_server_timer -~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -get_timezone -~~~~~~~~~~~~~~~~~ - -Description: Get the device's time zone. - -Parameters: None - -Returns: Time zone by the TZ identifier (e.g., America/Los_Angeles) - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - - -set_timezone -~~~~~~~~~~~~~~~~~ - -Description: Sets the device's time zone - -Parameters: - - - - - -Sound ------------- - -get_sound_volume -~~~~~~~~~~~~~~~~ - -Description: Returns the volume of the sound played by the vacuum - -Parameters: None - -Returns: - - volume: The volume of the sound played by the vacuum - -Example:: - - 72 - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -change_sound_volume -~~~~~~~~~~~~~~~~~~~ - -Description: Sets the volume of the sound played by the vacuum - -Parameters: volume - -Returns: ok or error - -roborock -d command --device_id aHiddenDeviceId --cmd change_sound_volume --params 72 - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -test_sound_volume -~~~~~~~~~~~~~~~~~ - -Description: Plays a sound on the vacumm to identity volume - -Parameters: None - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - - -get_sound_progress -~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -Returns:: - -{'sid_in_progress': 0, 'progress': 0, 'state': 0, 'error': 0} - -.. - Is this where the vacumm is currently located ? - - -get_current_sound -~~~~~~~~~~~~~~~~~ - -.. - Is this an app setting ? - -Description: - -Parameters: - -Return example:: - - {'sid_in_use': 122, 'sid_version': 1, 'sid_in_progress': 0, 'location': 'de', 'bom': 'A.03.0342', 'language': 'en', 'msg_ver': 2} - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S7 MaxV Ultra Yes -Roborock S8 Pro Ultra Yes -====================== ========= - -dnld_install_sound -~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: - -Off peak charging ------------------ - -get_valley_electricity_timer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: Get valley electricity timer. - -Parameters: None - -Returns: - - start_hour: The hour you want valley electricity to start - - start_minute: The minute you want valley electricity to start - - end_hour: The hour you want valley electricity to be turned off - - end_minute: The minute you want valley electricity to be turned off - - enabled: If the switch is currently turned on in the app for valley electricity - - -``` -{'start_hour': 0, 'start_minute': 0, 'end_hour': 0, 'end_minute': 0, 'enabled': 0} -``` - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_valley_electricity_timer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: Sets the valley electricity timer - -Parameters: - - start_hour: The hour you want valley electricity to start - - start_minute: The minute you want valley electricity to start - - end_hour: The hour you want valley electricity to be turned off - - end_minute: The minute you want valley electricity to be turned off - - enabled: If the switch is currently turned on in the app for valley electricity - -Example:: - -{'start_hour': 0, 'start_minute': 0, 'end_hour': 0, 'end_minute': 0, 'enabled': 0} - - -.. - This does not appear to have any effect on the S8 Pro Ultra - Params accepted however no affect ?? - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra ??? -====================== ========= - - - - -Water box mode --------------- - -get_water_box_custom_mode -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: Get water box mode. - -Parameters: None - -Returns: Enumeration for water box mode. 203 - -.. - Not clear what this does - require Enumeration - - -get_clean_follow_ground_material_status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: - -Parameters: None -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= - -set_water_box_custom_mode -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Description: Set the water box mode. - -Parameters: {'water_box_mode': 203} - -Returns: ok or error - -.. - Not clear what this does - require Enumeration - -====================== ========= -Vacuum Model Supported -====================== ========= -Roborock S8 Pro Ultra Yes -====================== ========= diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 6b0e423c..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,36 +0,0 @@ -# Configuration file for the Sphinx documentation builder. - -# -- Project information - -project = "Python Roborock" -author = "Humberto gontijo & Lash-L" - -release = "0.1" -version = "0.1.0" - -# -- General configuration - -extensions = [ - "sphinx.ext.duration", - "sphinx.ext.doctest", - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "sphinx.ext.intersphinx", - "sphinx.ext.autosectionlabel", - "sphinx_rtd_theme", -] - -intersphinx_mapping = { - "python": ("https://docs.python.org/3/", None), - "sphinx": ("https://www.sphinx-doc.org/en/master/", None), -} -intersphinx_disabled_domains = ["std"] - -templates_path = ["_templates"] - -# -- Options for HTML output - -html_theme = "sphinx_rtd_theme" - -# -- Options for EPUB output -epub_show_urls = "footnote" diff --git a/docs/source/error.rst b/docs/source/error.rst deleted file mode 100644 index b8db415a..00000000 --- a/docs/source/error.rst +++ /dev/null @@ -1,78 +0,0 @@ -Error -===== - -Dock Errors ------------ - -These are the potential errors your dock can have and their corresponding number: - ok = 0 - - duct_blockage = 34 - - water_empty = 38 - - waste_water_tank_full = 39 - - dirty_tank_latch_open = 44 - - no_dustbin = 46 - - cleaning_tank_full_or_blocked = 53 - - -Vacuum Errors -------------- - -These are the potential errors your vacuum can have and their corresponding code - - lidar_blocked = 1 - - bumper_stuck = 2 - - wheels_suspended = 3 - - cliff_sensor_error = 4 - - main_brush_jammed = 5 - - side_brush_jammed = 6 - - wheels_jammed = 7 - - robot_trapped = 8 - - no_dustbin = 9 - - low_battery = 12 - - charging_error = 13 - - battery_error = 14 - - wall_sensor_dirty = 15 - - robot_tilted = 16 - - side_brush_error = 17 - - fan_error = 18 - - vertical_bumper_pressed = 21 - - dock_locator_error = 22 - - return_to_dock_fail = 23 - - nogo_zone_detected = 24 - - vibrarise_jammed = 27 - - robot_on_carpet = 28 - - filter_blocked = 29 - - invisible_wall_detected = 30 - - cannot_cross_carpet = 31 - - internal_error = 32 diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index d7384e18..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -Welcome to Roborock's documentation! -==================================== - -**Roborock** is a Python library for controlling your Roborock vacuum - -.. note:: - - This project is under active development. - -You can get a Home Assistant integration for Roborock in core -`here `__ or as a custom integration -`here `__ - -Contents --------- - -.. toctree:: - - usage - status - error - api_commands - supported_devices diff --git a/docs/source/status.rst b/docs/source/status.rst deleted file mode 100644 index d3a44863..00000000 --- a/docs/source/status.rst +++ /dev/null @@ -1,107 +0,0 @@ -Status -====== -Status is a core piece of information for our system. It is used to get a wide variety of data about the vacuum and is broadcasted. - - msg_ver: - - msg_seq: - - state: - - battery: The battery percentage of the vacuum - - clean_time: How long (total) this vacuum has cleaned for - - clean_area: How much area (total) this vacuum has cleaned in micrometers - - error_code: The error code of the vacuum - - map_present: - - in_cleaning: If the vacuum is currently cleaning - - in_returning: If the vacuum is currently returning to the dock. - - in_fresh_state: - - lab_status: - - water_box_status: - - back_type: - - wash_phase: - - wash_ready: - - fan_power: The strength of the fan suction. Listed as an integer that corresponds to a enum value. - - dnd_enabled: 0 or 1 that states if there is a dnd time enabled (does not mean that dnd is on now) - - map_status: - - is_locating: - - lock_status: - - water_box_mode: - - water_box_carriage_status: - - mop_forbidden_enable: - - camera_status: - - is_exploring: - - home_sec_status: - - home_sec_enable_password: - - adbumper_status: - - water_shortage_status: - - dock_type: - - dust_collection_status: - - auto_dust_collection: - - avoid_count: - - mop_mode: - - debug_mode: - - collision_avoid_status: - - switch_map_mode: - - dock_error_status: - - charge_status: - - unsave_map_reason: - - unsave_map_flag: - - wash_status: - - distance_off: - - in_warmup: - - dry_status: - - rdt: - - clean_percent: - - rss: - - dss: - - common_status: - - corner_clean_mode: diff --git a/docs/source/supported_devices.rst b/docs/source/supported_devices.rst deleted file mode 100644 index 0ab68fd9..00000000 --- a/docs/source/supported_devices.rst +++ /dev/null @@ -1,78 +0,0 @@ -Supported Devices -================== - -Note: These links are tracking links with Amazon or Roborock. This allows us to get some analytics and helps us get -'negotiation' power with Roborock. We would like to be able to open a channel of communication with Roborock, and -getting information like this is a great first step. - -Note, I have only added links to the new devices, older devices are no longer sold directly by roborock, so to buy them -you have to find them used. - -.. list-table:: Robot Vacuums - :widths: 30 20 20 - :header-rows: 1 - - * - Vacuum Model - - Amazon - - Roborock - * - Roborock S4 - - - - - * - Roborock S4 Max - - - - - * - Roborock S5 Max - - - - - * - Roborock S6 - - - - - * - Roborock S6 Pure - - - - - * - Roborock S6 Max - - - - - * - Roborock S6 MaxV - - - - - * - Roborock S7 - - - - - * - Roborock S7 MaxV - - - - - * - Roborock S7 Max Ultra - - `Link `__ - - `Link `__ - * - Roborock S8 - - `Link `__ - - `Link `__ - * - Roborock S8 Pro Ultra - - `Link `__ - - `Link `__ - * - Roborock Q5 - - `Link `__ - - `Link `__ - * - Roborock Q5 Pro - - `Link `__ - - `Link `__ - * - Roborock Q7 - - `Link `__ - - `Link `__ - * - Roborock Q7 Max - - `Link `__ - - `Link `__ - * - Roborock Q8 Max - - `Link `__ - - `Link `__ - * - Roborock Q Revo - - `Link `__ - - `Link `__ - - -Roborock has recently added two other categories of devices, handheld vacuums, and washing machines. -Neither are supported at this time. - -There are plans to support the handheld ones, but it uses a newer version of the api that I am still trying to reverse -engineer. diff --git a/docs/source/usage.rst b/docs/source/usage.rst deleted file mode 100755 index 6f8a87a1..00000000 --- a/docs/source/usage.rst +++ /dev/null @@ -1,41 +0,0 @@ -Usage -===== - -Installation ------------- - -To use Python-Roborock, first install it using pip: - -.. code-block:: console - - (.venv) $ pip install python-roborock - -Login ------ - -.. code-block:: console - - (.venv) $ roborock login --email username --password password - -List devices ------------- - -This will list all devices associated with the account: - -.. code-block:: console - - (.venv) $ roborock list-devices - - Known devices MyRobot: 7kI9d66UoPXd6sd9gfd75W - - -The deviceId 7kI9d66UoPXd6sd9gfd75W can be used to run commands on the device. - -Run a command -------------- - -To run a command: - -.. code-block:: console - - (.venv) $ roborock -d command --device_id 7kI9d66UoPXd6sd9gfd75W --cmd get_status diff --git a/roborock/devices/README.md b/roborock/devices/README.md index 9d31df1b..54cd2b25 100644 --- a/roborock/devices/README.md +++ b/roborock/devices/README.md @@ -1,669 +1,41 @@ -# Roborock Devices & Discovery +# Roborock Device Manager -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. +This library provides a high-level interface for discovering and controlling Roborock devices. It abstracts the underlying communication protocols (MQTT, Local TCP) and provides a unified `DeviceManager` for interacting with your devices. -## Usage TL;DR +For internal architecture details, protocol specifications, and design documentation, please refer to [docs/DEVICES.md](https://github.com/python-roborock/python-roborock/docs/DEVICES.md). -* **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. +## Getting Started -## Background: Understanding Device Protocols +### Credentials -**The library supports three device protocol versions, each with different capabilities:** +To connect to your devices, you first need to obtain your user data (including the `rriot` token) from the Roborock Cloud. This is handled via the `RoborockApiClient`. -### Protocol Summary +## Usage Guide -| Protocol | Device Examples | MQTT | Local TCP | Channel Type | Notes | -|----------|----------------|------|-----------|--------------|-------| -| **V1** (`pv=1.0`) | Most vacuum robots (S7, S8, Q5, Q7, etc.) | ✅ | ✅ | `V1Channel` with `RpcChannel` | Prefers local, falls back to MQTT | -| **A01** (`pv=A01`) | Dyad, Zeo washers | ✅ | ❌ | `MqttChannel` + helpers | MQTT only, DPS protocol | -| **B01** (`pv=B01`) | Some newer models | ✅ | ❌ | `MqttChannel` + helpers | MQTT only, DPS protocol | +The core entry point for the library is the `DeviceManager`. It handles: +1. **Device Discovery**: Fetching the list of devices associated with your account. +2. **Connection Management**: Automatically determining the best connection method (Local vs MQTT) and protocol version (V1 vs A01/B01). +3. **Command Execution**: Sending commands and query status. -**Key Point:** The `DeviceManager` automatically detects the protocol version and creates the appropriate channel type. You don't need to handle this manually. +### Example -## Internal Architecture +See [examples/example.py](https://github.com/python-roborock/python-roborock/examples/example.py) for a complete example of how to login, create a device manager, and list the status of your vacuums. -The library is organized into distinct layers, each with a specific responsibility. **Different device protocols use different channel implementations:** +### Device Properties -```mermaid -graph TB - subgraph "Application Layer" - User[Application Code] - end +Different devices support different property sets: - subgraph "Device Management Layer" - DM[DeviceManager
Detects protocol version] - end +* **`v1_properties`**: Primarily for Vacuum Robots (S7, S8, Q5, etc.). Supports traits like `status`, `consumables`, `fan_power`, `water_box`. +* **`a01_properties`**: For Washer/Dryers and handheld Wet/Dry Vacuums (Dyad, Zeo) that use another newer protocol. +* **`b01_q7_properties`** and **`b01_q10_properties`**: For newer Vacuum/Mop devices using newer protocol instead of v1. - subgraph "Device Types by Protocol" - V1Dev[V1 Devices
pv=1.0
Most vacuums] - A01Dev[A01 Devices
pv=A01
Dyad, Zeo] - B01Dev[B01 Devices
pv=B01
Some models] - end +You can check if a property set is available by checking if the property on the device object is not `None` (e.g. `if device.v1_properties:`). - subgraph "Traits Layer" - V1Traits[V1 Traits
Clean, Map, etc.] - A01Traits[A01 Traits
DPS-based] - B01Traits[B01 Traits
DPS-based] - end +### Caching - subgraph "Channel Layer" - V1C[V1Channel
MQTT + Local] - A01C[A01 send_decoded_command
MQTT only] - B01C[B01 send_decoded_command
MQTT only] - RPC[RpcChannel
Multi-strategy] - MC[MqttChannel
Per-device wrapper] - LC[LocalChannel
TCP :58867] - end +Use `FileCache` or your own `Cache` implementation to persist: +- `HomeData`: The list of your home's rooms and devices. +- `NetworkingInfo`: Device IP addresses and tokens. +- `Device Capabilities`: What features your specific model supports. - subgraph "Session Layer" - MS[MqttSession
SHARED by all devices
Idle timeout] - LS[LocalSession
Factory] - end - - subgraph "Protocol Layer" - V1P[V1 Protocol
JSON RPC + AES] - A01P[A01 Protocol
DPS format] - B01P[B01 Protocol
DPS format] - end - - subgraph "Transport Layer" - MQTT[MQTT Broker
Roborock Cloud] - TCP[TCP Socket
Direct to device] - end - - User --> DM - DM -->|pv=1.0| V1Dev - DM -->|pv=A01| A01Dev - DM -->|pv=B01| B01Dev - - V1Dev --> V1Traits - A01Dev --> A01Traits - B01Dev --> B01Traits - - V1Traits --> V1C - A01Traits --> A01C - B01Traits --> B01C - - V1C --> RPC - RPC -->|Strategy 1| LC - RPC -->|Strategy 2| MC - A01C --> MC - B01C --> MC - - MC --> MS - LC --> LS - - MC --> V1P - MC --> A01P - MC --> B01P - LC --> V1P - - MS --> MQTT - LC --> TCP - MQTT <--> TCP - - style User fill:#e1f5ff - style DM fill:#fff4e1 - style V1C fill:#ffe1e1 - style RPC fill:#ffe1e1 - style MS fill:#e1ffe1 - style V1P fill:#f0e1ff - style A01P fill:#f0e1ff - style B01P fill:#f0e1ff -``` - -### Layer Responsibilities - -1. **Device Management Layer**: Detects protocol version (`pv` field) and creates appropriate channels -2. **Device Types**: Different devices based on protocol version (V1, A01, B01) -3. **Traits Layer**: Protocol-specific device capabilities and commands -4. **Channel Layer**: Protocol-specific communication patterns - - **V1**: Full RPC channel with local + MQTT fallback - - **A01/B01**: Helper functions wrapping MqttChannel (MQTT only) - - **MqttChannel**: Per-device wrapper that uses shared `MqttSession` -5. **Session Layer**: Connection pooling and subscription management - - **MqttSession**: **Shared single connection** for all devices - - **LocalSession**: Factory for creating device-specific local connections -6. **Protocol Layer**: Message encoding/decoding for different device versions -7. **Transport Layer**: Low-level MQTT and TCP communication - -**Important:** All `MqttChannel` instances share the same `MqttSession`, which maintains a single MQTT connection to the broker. This means: -- Only one TCP connection to the MQTT broker regardless of device count -- Subscription management is centralized with idle timeout optimization -- All devices communicate through device-specific MQTT topics on the shared connection - -### Protocol-Specific Architecture - -| Protocol | Channel Type | Local Support | RPC Strategy | Use Case | -|----------|-------------|---------------|--------------|----------| -| **V1** (`pv=1.0`) | `V1Channel` with `RpcChannel` | ✅ Yes | Multi-strategy (Local → MQTT) | Most vacuum robots | -| **A01** (`pv=A01`) | `MqttChannel` + helpers | ❌ No | Direct MQTT | Dyad, Zeo washers | -| **B01** (`pv=B01`) | `MqttChannel` + helpers | ❌ No | Direct MQTT | Some newer models | - -## Account Setup Internals - -### Login - -- Login can happen with either email and password or email and sending a code. We - currently prefer email with sending a code -- however the roborock no longer - supports this method of login. In the future we may want to migrate to password - if this login method is no longer supported. -- The Login API provides a `userData` object with information on connecting to the cloud APIs -- This `rriot` data contains per-session information, unique each time you login. - - 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 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 -that a newer version of the API should be used. - -- `products`: This is a list of all of the products you have on your account. These objects are always the same (i.e. a s7 maxv is always the exact same.) - - It only shows the products for devices available on your account -- `devices` and `received_devices`: - - These both share the same objects, but one is for devices that have been shared with you and one is those that are on your account. - - The big things here are (MOST are static): - - `duid`: A unique identifier for your device (this is always the same i think) - - `name`: The name of the device in your app - - `local_key`: The local key that is needed for encoding and decoding messages for the device. This stays the same unless someone sets their vacuum back up. - - `pv`: the protocol version (i.e. 1.0 or A1 or B1) - - `product_id`: The id of the product from the above products list. - - `device_status`: An initial status for some of the data we care about, though this changes on each update. -- `rooms`: The rooms in the home. - - This changes if the user adds a new room or changes its name. - - We have to combine this with the room numbers from `GET_ROOM_MAPPING` on the device - - 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 - -## Connection Implementation - -### Connection Flow by Protocol - -The connection flow differs based on the device protocol version: - -#### V1 Devices (Most Vacuums) - MQTT + Local - -```mermaid -sequenceDiagram - participant App as Application - participant DM as DeviceManager - participant V1C as V1Channel - participant RPC as RpcChannel - participant MC as MqttChannel - participant LC as LocalChannel - participant MS as MqttSession - participant Broker as MQTT Broker - participant Device as V1 Vacuum - - App->>DM: create_device_manager() - DM->>MS: Create MQTT Session - MS->>Broker: Connect - Broker-->>MS: Connected - - App->>DM: get_devices() - Note over DM: Detect pv=1.0 - DM->>V1C: Create V1Channel - V1C->>MC: Create MqttChannel - V1C->>LC: Create LocalChannel (deferred) - - Note over V1C: Subscribe to device topics - V1C->>MC: subscribe() - MC->>MS: subscribe(topic, callback) - MS->>Broker: SUBSCRIBE - - Note over V1C: Fetch network info via MQTT - V1C->>RPC: send_command(GET_NETWORK_INFO) - RPC->>MC: publish(request) - MC->>MS: publish(topic, message) - MS->>Broker: PUBLISH - Broker->>Device: Command - Device->>Broker: Response - Broker->>MS: Message - MS->>MC: callback(message) - MC->>RPC: decoded message - RPC-->>V1C: NetworkInfo - - Note over V1C: Connect locally using IP - V1C->>LC: connect() - LC->>Device: TCP Connect :58867 - Device-->>LC: Connected - - Note over App: Commands prefer local - App->>V1C: send_command(GET_STATUS) - V1C->>RPC: send_command() - RPC->>LC: publish(request) [Try local first] - LC->>Device: Command via TCP - Device->>LC: Response - LC->>RPC: decoded message - RPC-->>App: Status -``` - -#### A01/B01 Devices (Dyad, Zeo) - MQTT Only - -```mermaid -sequenceDiagram - participant App as Application - participant DM as DeviceManager - participant A01 as A01 Traits - participant Helper as send_decoded_command - participant MC as MqttChannel - participant MS as MqttSession - participant Broker as MQTT Broker - participant Device as A01 Device - - App->>DM: create_device_manager() - DM->>MS: Create MQTT Session - MS->>Broker: Connect - Broker-->>MS: Connected - - App->>DM: get_devices() - Note over DM: Detect pv=A01 - DM->>MC: Create MqttChannel - DM->>A01: Create A01 Traits - - Note over A01: Subscribe to device topics - A01->>MC: subscribe() - MC->>MS: subscribe(topic, callback) - MS->>Broker: SUBSCRIBE - - Note over App: All commands via MQTT - App->>A01: set_power(True) - A01->>Helper: send_decoded_command() - Helper->>MC: subscribe(find_response) - Helper->>MC: publish(request) - MC->>MS: publish(topic, message) - MS->>Broker: PUBLISH - Broker->>Device: Command - Device->>Broker: Response - Broker->>MS: Message - MS->>MC: callback(message) - MC->>Helper: decoded message - Helper-->>App: Result -``` - -### Key Differences - -| Aspect | V1 Devices | A01/B01 Devices | -|--------|------------|-----------------| -| **Protocols** | V1 Protocol (JSON RPC) | DPS Protocol | -| **Transports** | MQTT + Local TCP | MQTT only | -| **Channel Type** | `V1Channel` with `RpcChannel` | `MqttChannel` with helpers | -| **Local Support** | ✅ Yes, preferred | ❌ No | -| **Fallback** | Local → MQTT | N/A | -| **Connection** | Requires network info fetch | Direct MQTT | -| **Examples** | Most vacuum robots | Dyad washers, Zeo models | - -### MQTT Connection (All Devices) - -- Initial device information must be obtained from MQTT -- For V1 devices, we set up the MQTT device connection before the local device connection - - The `NetworkingInfo` needs to be fetched to get additional information about connecting to the device (e.g., Local IP Address) - - This networking info can be cached to reduce network calls - - MQTT is also the only way to get the device Map -- Incoming and outgoing messages are decoded/encoded using the device `local_key` -- For A01/B01 devices, MQTT is the only transport - -### Local Connection (V1 Devices Only) - -- We use the `ip` from the `NetworkingInfo` to find the device -- The local connection is preferred for improved latency and reducing load on the cloud servers to avoid rate limiting -- Connections are made using a normal TCP socket on port `58867` -- Incoming and outgoing messages are decoded/encoded using the device `local_key` -- Messages received on the stream may be partially received, so we keep a running buffer as messages are partially decoded -- **Not available for A01/B01 devices** - -### RPC Pattern (V1 Devices) - -V1 devices use a publish/subscribe model for both MQTT and local connections, with an RPC abstraction on top: - -```mermaid -graph LR - subgraph "RPC Layer" - A[send_command] -->|1. Create request| B[Encoder] - B -->|2. Subscribe for response| C[Channel.subscribe] - B -->|3. Publish request| D[Channel.publish] - C -->|4. Wait for match| E[find_response callback] - E -->|5. Match request_id| F[Future.set_result] - F -->|6. Return| G[Command Result] - end - - subgraph "Channel Layer" - C --> H[Subscription Map] - D --> I[Transport] - I --> J[Device] - J --> K[Incoming Messages] - K --> H - H --> E - end -``` - -**Key Design Points:** - -1. **Temporary Subscriptions**: Each RPC creates a temporary subscription that matches the request ID -2. **Subscription Reuse**: `MqttSession` keeps subscriptions alive for 60 seconds (or idle timeout) to enable reuse during command bursts -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 - -## Class Design & Components - -### Current Architecture - -The current design separates concerns into distinct layers: - -```mermaid -classDiagram - class Channel { - <> - +subscribe(callback) Callable - +publish(message) - +is_connected() bool - } - - class MqttChannel { - -MqttSession session - -duid: str - -local_key: str - +subscribe(callback) - +publish(message) - } - - class LocalChannel { - -host: str - -transport: Transport - -local_key: str - +connect() - +subscribe(callback) - +publish(message) - +close() - } - - class V1Channel { - -MqttChannel mqtt_channel - -LocalChannel local_channel - -RpcChannel rpc_channel - +send_command(method, params) - +subscribe(callback) - } - - class RpcChannel { - -List~RpcStrategy~ strategies - +send_command(method, params) - } - - class RpcStrategy { - +name: str - +channel: Channel - +encoder: Callable - +decoder: Callable - +health_manager: HealthManager - } - - class MqttSession { - -Client client - -dict listeners - -dict idle_timers - +subscribe(topic, callback) - +publish(topic, payload) - +close() - } - - Channel <|-- MqttChannel - Channel <|-- LocalChannel - Channel <|-- V1Channel - MqttChannel --> MqttSession - V1Channel --> MqttChannel - V1Channel --> LocalChannel - V1Channel --> RpcChannel - RpcChannel --> RpcStrategy - RpcStrategy --> Channel -``` - -### Key Components - -#### Channel Interface - -The `Channel` abstraction provides a uniform interface for both MQTT and local connections: - -- **`subscribe(callback)`**: Register a callback for incoming messages -- **`publish(message)`**: Send a message to the device -- **`is_connected`**: Check connection status - -This abstraction allows the RPC layer to work identically over both transports. - -#### MqttSession (Shared Across All Devices) - -The `MqttSession` manages a **single shared MQTT connection** for all devices: - -- **Single Connection**: Only one TCP connection to the MQTT broker, regardless of device count -- **Per-Device Topics**: Each device communicates via its own MQTT topics (e.g., `rr/m/i/{user}/{username}/{duid}`) -- **Subscription Pooling**: Multiple callbacks can subscribe to the same topic -- **Idle Timeout**: Keeps subscriptions alive for 10 seconds after the last callback unsubscribes (enables reuse during command bursts) -- **Reconnection**: Automatically reconnects and re-establishes all subscriptions on connection loss -- **Thread-Safe**: Uses asyncio primitives for safe concurrent access - -**Efficiency**: Creating 5 devices means 5 `MqttChannel` instances but only 1 `MqttSession` and 1 MQTT broker connection. - -#### MqttChannel (Per-Device Wrapper) - -Each device gets its own `MqttChannel` instance that: -- Wraps the shared `MqttSession` -- Manages device-specific topics (publish to `rr/m/i/.../duid`, subscribe to `rr/m/o/.../duid`) -- Handles protocol-specific encoding/decoding with the device's `local_key` -- Provides the same `Channel` interface as `LocalChannel` - -#### RpcChannel with Multiple Strategies (V1 Only) - -The `RpcChannel` implements the request/response pattern over pub/sub channels and is **only used by V1 devices**: - -```python -# Example: V1Channel tries local first, then MQTT -strategies = [ - RpcStrategy(name="local", channel=local_channel, ...), - RpcStrategy(name="mqtt", channel=mqtt_channel, ...), -] -rpc_channel = RpcChannel(strategies) -``` - -For each V1 command: -1. Try the first strategy (local) -2. If it fails, try the next strategy (MQTT) -3. Return the first successful result - -**A01/B01 devices** don't use `RpcChannel`. Instead, they use helper functions (`send_decoded_command`) that directly wrap `MqttChannel`. - -#### Protocol-Specific Channel Architecture - -| Component | V1 Devices | A01/B01 Devices | -|-----------|------------|-----------------| -| **Channel Class** | `V1Channel` | `MqttChannel` directly | -| **RPC Abstraction** | `RpcChannel` with strategies | Helper functions | -| **Strategy Pattern** | ✅ Multi-strategy (Local → MQTT) | ❌ Direct MQTT only | -| **Health Manager** | ✅ Tracks local/MQTT health | ❌ Not needed | -| **Code Location** | `v1_channel.py` | `a01_channel.py`, `b01_q7_channel.py` | - -#### Health Management (V1 Only) - -Each V1 RPC strategy can have a `HealthManager` that tracks success/failure: - -- **Exponential Backoff**: After failures, wait before retrying -- **Automatic Recovery**: Periodically attempt to restore failed connections -- **Network Info Refresh**: Refresh local IP addresses after extended periods - -A01/B01 devices don't need health management since they only use MQTT (no fallback). - -### Protocol Versions - -Different device models use different protocol versions: - -| Protocol | Devices | Encoding | -|----------|---------|----------| -| V1 | Most vacuum robots | JSON RPC with AES encryption | -| A01 | Dyad, Zeo | DPS-based protocol | -| B01 | Some newer models | DPS-based protocol | -| L01 | Local protocol variant | Binary protocol negotiation | - -The protocol layer handles encoding/decoding transparently based on the device's `pv` field. - -### Prior API Issues - -- Complex Inheritance Hierarchy: Multiple inheritance with classes like RoborockMqttClientV1 inheriting from both RoborockMqttClient and RoborockClientV1 - -- Callback-Heavy Design: Heavy reliance on callbacks and listeners in RoborockClientV1.on_message_received and the ListenerModel system - -- Version Fragmentation: Separate v1 and A01 APIs with different patterns and abstractions - -- Mixed Concerns: Classes handle both communication protocols (MQTT/local) and device-specific logic - -- Complex Caching: The AttributeCache system with RepeatableTask adds complexity - -- Manual Connection Management: Users need to manually set up both MQTT and local clients as shown in the README example - -### Design Goals - -- Prefer a single unified client that handles both MQTT and local connections internally. - -- Home and device discovery (fetching home data and device setup) will be behind a single API. - -- Asyncio First: Everything should be asyncio as much as possible, with fewer callbacks. - -- The clients should be working in terms of devices. We need to detect capabilities for each device and not expose details about API versions. - -- Reliability issues: The current Home Assistant integration has issues with reliability and needs to be simplified. It may be that there are bugs with the exception handling and it's too heavy on the cloud APIs and could benefit from more seamless caching. - -### Migration from Legacy APIs - -The library previously had: -- Separate `RoborockMqttClientV1` and `RoborockLocalClientV1` classes -- Manual connection management -- Callback-heavy design with `on_message_received` -- Complex inheritance hierarchies - -The new design: -- `DeviceManager` handles all connection management -- `V1Channel` automatically manages both MQTT and local -- Asyncio-first with minimal callbacks -- Clear separation of concerns through layers -- Users work with devices, not raw clients - - -## Implementation Details - -### Code Organization - -``` -roborock/ -├── devices/ # Device management and channels -│ ├── device_manager.py # High-level device lifecycle -│ ├── channel.py # Base Channel interface -│ ├── mqtt_channel.py # MQTT channel implementation -│ ├── local_channel.py # Local TCP channel implementation -│ ├── v1_channel.py # V1 protocol channel with RPC strategies -│ ├── a01_channel.py # A01 protocol helpers -│ ├── b01_q7_channel.py # B01 Q7 protocol helpers -│ └── traits/ # Device-specific command traits -│ └── v1/ # V1 device traits -│ ├── __init__.py # Trait initialization -│ ├── clean.py # Cleaning commands -│ ├── map.py # Map management -│ └── ... -├── mqtt/ # MQTT session management -│ ├── session.py # Base session interface -│ └── roborock_session.py # MQTT session with idle timeout -├── protocols/ # Protocol encoders/decoders -│ ├── v1_protocol.py # V1 JSON RPC protocol -│ ├── a01_protocol.py # A01 protocol -│ ├── b01_q7_protocol.py # B01 Q7 protocol -│ └── ... -└── data/ # Data containers and mappings - ├── containers.py # Status, HomeData, etc. - └── v1/ # V1-specific data structures -``` - -### Threading Model - -The library is **asyncio-only** with no threads: - -- All I/O is non-blocking using `asyncio` -- No thread synchronization needed (single event loop) -- Callbacks are executed in the event loop -- Use `asyncio.create_task()` for background work - -### Error Handling - -```mermaid -graph TD - A[send_command] --> B{Local Available?} - B -->|Yes| C[Try Local] - B -->|No| D[Try MQTT] - C --> E{Success?} - E -->|Yes| F[Return Result] - E -->|No| G{Timeout?} - G -->|Yes| H[Update Health Manager] - H --> D - G -->|No| I{Connection Error?} - I -->|Yes| J[Mark Connection Failed] - J --> D - I -->|No| D - D --> K{Success?} - K -->|Yes| F - K -->|No| L[Raise RoborockException] -``` - -**Exception Types:** - -- `RoborockException`: Base exception for all library errors -- `RoborockConnectionException`: Connection-related failures -- `RoborockTimeout`: Command timeout (10 seconds) - -### Caching Strategy - -To reduce API calls and improve reliability: - -1. **Home Data**: Cached on disk, refreshed periodically -2. **Network Info**: Cached for 12 hours -3. **Device Capabilities**: Detected once and cached -4. **MQTT Subscriptions**: Kept alive for 60 seconds (idle timeout) - -### Testing - -Test structure mirrors the python module structure. For example, -the module `roborock.devices.traits.v1.maps` is tested in the file -`tests/devices/traits/v1/test_maps.py`. Each test file corresponds to a python -module. - -The test suite uses mocking extensively to avoid real devices: - -- `Mock` and `AsyncMock` for channels and sessions -- Fake message generators (`mqtt_packet.gen_publish()`) -- Snapshot testing for complex data structures -- Time-based tests use small timeouts (10-50ms) for speed - - -Example test structure: -```python -@pytest.fixture -def mock_mqtt_channel(): - """Mock MQTT channel that simulates responses.""" - channel = AsyncMock(spec=MqttChannel) - channel.response_queue = [] - - async def publish_side_effect(message): - # Simulate device response - if channel.response_queue: - response = channel.response_queue.pop(0) - await callback(response) - - channel.publish.side_effect = publish_side_effect - return channel -``` +This speeds up startup time and reduces load on the Roborock cloud APIs.