python-roborock 4.1.1__tar.gz → 4.2.1__tar.gz

{python_roborock-4.1.1 → python_roborock-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 4.1.1
+Version: 4.2.1
 Summary: A package to control Roborock vacuums.
 Project-URL: Repository, https://github.com/humbertogontijo/python-roborock
 Project-URL: Documentation, https://python-roborock.readthedocs.io/
@@ -16,7 +16,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: <4,>=3.11
 Requires-Dist: aiohttp<4,>=3.8.2
-Requires-Dist: aiomqtt<3,>=2.3.2
+Requires-Dist: aiomqtt<3,>=2.5.0
 Requires-Dist: click-shell~=2.1
 Requires-Dist: click>=8
 Requires-Dist: construct<3,>=2.10.57

{python_roborock-4.1.1 → python_roborock-4.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "4.1.1"
+version = "4.2.1"
 description = "A package to control Roborock vacuums."
 authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
 requires-python = ">=3.11, <4"
@@ -27,7 +27,7 @@ dependencies = [
     "construct>=2.10.57,<3",
     "vacuum-map-parser-roborock",
     "pyrate-limiter>=3.7.0,<4",
-    "aiomqtt>=2.3.2,<3",
+    "aiomqtt>=2.5.0,<3",
     "click-shell~=2.1",
 ]
 

{python_roborock-4.1.1 → python_roborock-4.2.1}/roborock/cli.py

@@ -43,6 +43,7 @@ from pyshark.packet.packet import Packet  # type: ignore
 
 from roborock import RoborockCommand
 from roborock.data import RoborockBase, UserData
+from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
 from roborock.device_features import DeviceFeatures
 from roborock.devices.cache import Cache, CacheData
 from roborock.devices.device import RoborockDevice
@@ -745,6 +746,21 @@ async def network_info(ctx, device_id: str):
     await _display_v1_trait(context, device_id, lambda v1: v1.network_info)
 
 
+def _parse_b01_q10_command(cmd: str) -> B01_Q10_DP:
+    """Parse B01_Q10 command from either enum name or value."""
+    try:
+        return B01_Q10_DP(int(cmd))
+    except ValueError:
+        try:
+            return B01_Q10_DP.from_name(cmd)
+        except ValueError:
+            try:
+                return B01_Q10_DP.from_value(cmd)
+            except ValueError:
+                pass
+    raise RoborockException(f"Invalid command {cmd} for B01_Q10 device")
+
+
 @click.command()
 @click.option("--device_id", required=True)
 @click.option("--cmd", required=True)
@@ -755,12 +771,18 @@ async def command(ctx, cmd, device_id, params):
     context: RoborockContext = ctx.obj
     device_manager = await context.get_device_manager()
     device = await device_manager.get_device(device_id)
-    if device.v1_properties is None:
-        raise RoborockException(f"Device {device.name} does not support V1 protocol")
-    command_trait: Trait = device.v1_properties.command
-    result = await command_trait.send(cmd, json.loads(params) if params is not None else None)
-    if result:
-        click.echo(dump_json(result))
+    if device.v1_properties is not None:
+        command_trait: Trait = device.v1_properties.command
+        result = await command_trait.send(cmd, json.loads(params) if params is not None else None)
+        if result:
+            click.echo(dump_json(result))
+    elif device.b01_q10_properties is not None:
+        cmd_value = _parse_b01_q10_command(cmd)
+        command_trait: Trait = device.b01_q10_properties.command
+        await command_trait.send(cmd_value, json.loads(params) if params is not None else None)
+        click.echo("Command sent successfully; Enable debug logging (-d) to see responses.")
+        # Q10 commands don't have a specific time to respond, so wait a bit and log
+        await asyncio.sleep(5)
 
 
 @click.command()

python_roborock-4.2.1/roborock/devices/README.md

@@ -0,0 +1,41 @@
+# Roborock Device Manager
+
+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.
+
+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).
+
+## Getting Started
+
+### Credentials
+
+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`.
+
+## Usage Guide
+
+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.
+
+### Example
+
+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.
+
+### Device Properties
+
+Different devices support different property sets:
+
+*   **`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.
+
+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:`).
+
+### Caching
+
+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.
+
+This speeds up startup time and reduces load on the Roborock cloud APIs.

{python_roborock-4.1.1 → python_roborock-4.2.1}/roborock/devices/device.py

@@ -18,9 +18,9 @@ from roborock.exceptions import RoborockException
 from roborock.roborock_message import RoborockMessage
 from roborock.util import RoborockLoggerAdapter
 
-from .channel import Channel
 from .traits import Trait
 from .traits.traits_mixin import TraitsMixin
+from .transport.channel import Channel
 
 _LOGGER = logging.getLogger(__name__)
 

{python_roborock-4.1.1 → python_roborock-4.2.1}/roborock/devices/device_manager.py

@@ -25,10 +25,10 @@ from roborock.protocol import create_mqtt_params
 from roborock.web_api import RoborockApiClient, UserWebApiClient
 
 from .cache import Cache, DeviceCache, NoCache
-from .channel import Channel
-from .mqtt_channel import create_mqtt_channel
+from .rpc.v1_channel import create_v1_channel
 from .traits import Trait, a01, b01, v1
-from .v1_channel import create_v1_channel
+from .transport.channel import Channel
+from .transport.mqtt_channel import create_mqtt_channel
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -242,9 +242,7 @@ async def create_device_manager(
                 channel = create_mqtt_channel(user_data, mqtt_params, mqtt_session, device)
                 model_part = product.model.split(".")[-1]
                 if "ss" in model_part:
-                    raise UnsupportedDeviceError(
-                        f"Device {device.name} has unsupported version B01 product model {product.model}"
-                    )
+                    trait = b01.q10.create(channel)
                 elif "sc" in model_part:
                     # Q7 devices start with 'sc' in their model naming.
                     trait = b01.q7.create(channel)

python_roborock-4.2.1/roborock/devices/rpc/__init__.py

@@ -0,0 +1,14 @@
+"""Module for sending device specific commands to Roborock devices.
+
+This module provides a application-level interface for sending commands to Roborock
+devices. These modules can be used by traits (higher level APIs) to send commands.
+
+Each module may contain details that are common across all traits, and may depend
+on the transport level modules (e.g. MQTT, Local device) for issuing the
+commands.
+
+The lowest level protocol encoding is handled in `roborock.protocols` which
+have no dependencies on the transport level modules.
+"""
+
+__all__: list[str] = []

{python_roborock-4.1.1/roborock/devices → python_roborock-4.2.1/roborock/devices/rpc}/a01_channel.py

@@ -5,6 +5,7 @@ import logging
 from collections.abc import Callable
 from typing import Any, overload
 
+from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.exceptions import RoborockException
 from roborock.protocols.a01_protocol import (
     decode_rpc_response,
@@ -16,8 +17,6 @@ from roborock.roborock_message import (
     RoborockZeoProtocol,
 )
 
-from .mqtt_channel import MqttChannel
-
 _LOGGER = logging.getLogger(__name__)
 _TIMEOUT = 10.0
 

python_roborock-4.2.1/roborock/devices/rpc/b01_q10_channel.py

@@ -0,0 +1,36 @@
+"""Thin wrapper around the MQTT channel for Roborock B01 Q10 devices."""
+
+from __future__ import annotations
+
+import logging
+
+from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+from roborock.devices.transport.mqtt_channel import MqttChannel
+from roborock.exceptions import RoborockException
+from roborock.protocols.b01_q10_protocol import (
+    ParamsType,
+    encode_mqtt_payload,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+async def send_command(
+    mqtt_channel: MqttChannel,
+    command: B01_Q10_DP,
+    params: ParamsType,
+) -> None:
+    """Send a command on the MQTT channel, without waiting for a response"""
+    _LOGGER.debug("Sending B01 MQTT command: cmd=%s params=%s", command, params)
+    roborock_message = encode_mqtt_payload(command, params)
+    _LOGGER.debug("Sending MQTT message: %s", roborock_message)
+    try:
+        await mqtt_channel.publish(roborock_message)
+    except RoborockException as ex:
+        _LOGGER.debug(
+            "Error sending B01 decoded command (method=%s params=%s): %s",
+            command,
+            params,
+            ex,
+        )
+        raise

{python_roborock-4.1.1/roborock/devices → python_roborock-4.2.1/roborock/devices/rpc}/b01_q7_channel.py

@@ -1,4 +1,4 @@
-"""Thin wrapper around the MQTT channel for Roborock B01 devices."""
+"""Thin wrapper around the MQTT channel for Roborock B01 Q7 devices."""
 
 from __future__ import annotations
 
@@ -7,6 +7,7 @@ import json
 import logging
 from typing import Any
 
+from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.exceptions import RoborockException
 from roborock.protocols.b01_q7_protocol import (
     Q7RequestMessage,
@@ -15,8 +16,6 @@ from roborock.protocols.b01_q7_protocol import (
 )
 from roborock.roborock_message import RoborockMessage
 
-from .mqtt_channel import MqttChannel
-
 _LOGGER = logging.getLogger(__name__)
 _TIMEOUT = 10.0
 

{python_roborock-4.1.1/roborock/devices → python_roborock-4.2.1/roborock/devices/rpc}/v1_channel.py

@@ -12,6 +12,10 @@ from dataclasses import dataclass
 from typing import Any, TypeVar
 
 from roborock.data import HomeDataDevice, NetworkInfo, RoborockBase, UserData
+from roborock.devices.cache import DeviceCache
+from roborock.devices.transport.channel import Channel
+from roborock.devices.transport.local_channel import LocalChannel, LocalSession, create_local_session
+from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.exceptions import RoborockException
 from roborock.mqtt.health_manager import HealthManager
 from roborock.mqtt.session import MqttParams, MqttSession
@@ -32,11 +36,6 @@ from roborock.roborock_message import RoborockMessage, RoborockMessageProtocol
 from roborock.roborock_typing import RoborockCommand
 from roborock.util import RoborockLoggerAdapter
 
-from .cache import DeviceCache
-from .channel import Channel
-from .local_channel import LocalChannel, LocalSession, create_local_session
-from .mqtt_channel import MqttChannel
-
 _LOGGER = logging.getLogger(__name__)
 
 __all__ = [

{python_roborock-4.1.1 → python_roborock-4.2.1}/roborock/devices/traits/a01/__init__.py

@@ -48,9 +48,9 @@ from roborock.data.zeo.zeo_code_mappings import (
     ZeoState,
     ZeoTemperature,
 )
-from roborock.devices.a01_channel import send_decoded_command
-from roborock.devices.mqtt_channel import MqttChannel
+from roborock.devices.rpc.a01_channel import send_decoded_command
 from roborock.devices.traits import Trait
+from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.roborock_message import RoborockDyadDataProtocol, RoborockZeoProtocol
 
 __init__ = [

python_roborock-4.2.1/roborock/devices/traits/b01/__init__.py

@@ -0,0 +1,12 @@
+"""Traits for B01 devices."""
+
+from . import q7, q10
+from .q7 import Q7PropertiesApi
+from .q10 import Q10PropertiesApi
+
+__all__ = [
+    "Q7PropertiesApi",
+    "Q10PropertiesApi",
+    "q7",
+    "q10",
+]

python_roborock-4.2.1/roborock/devices/traits/b01/q10/__init__.py

@@ -0,0 +1,29 @@
+"""Traits for Q10 B01 devices."""
+
+from typing import Any
+
+from roborock.devices.rpc.b01_q7_channel import send_decoded_command
+from roborock.devices.traits import Trait
+from roborock.devices.transport.mqtt_channel import MqttChannel
+
+from .command import CommandTrait
+
+__all__ = [
+    "Q10PropertiesApi",
+]
+
+
+class Q10PropertiesApi(Trait):
+    """API for interacting with B01 devices."""
+
+    command: CommandTrait
+    """Trait for sending commands to Q10 devices."""
+
+    def __init__(self, channel: MqttChannel) -> None:
+        """Initialize the B01Props API."""
+        self.command = CommandTrait(channel)
+
+
+def create(channel: MqttChannel) -> Q10PropertiesApi:
+    """Create traits for B01 devices."""
+    return Q10PropertiesApi(channel)

python_roborock-4.2.1/roborock/devices/traits/b01/q10/command.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+from roborock.devices.rpc.b01_q10_channel import send_command
+from roborock.devices.transport.mqtt_channel import MqttChannel
+from roborock.protocols.b01_q10_protocol import ParamsType
+
+
+class CommandTrait:
+    """Trait for sending commands to Q10 Roborock devices.
+
+    This trait allows sending raw commands directly to the device. It is particularly
+    useful for accessing features that do not have their own traits. Generally
+    it is preferred to use specific traits for device functionality when
+    available.
+    """
+
+    def __init__(self, channel: MqttChannel) -> None:
+        """Initialize the CommandTrait."""
+        self._channel = channel
+
+    async def send(self, command: B01_Q10_DP, params: ParamsType = None) -> Any:
+        """Send a command to the device.
+
+        Sending a raw command to the device using this method does not update
+        the internal state of any other traits. It is the responsibility of the
+        caller to ensure that any traits affected by the command are refreshed
+        as needed.
+        """
+        if not self._channel:
+            raise ValueError("Device trait in invalid state")
+        return await send_command(self._channel, command, params=params)

{python_roborock-4.1.1 → python_roborock-4.2.1}/roborock/devices/traits/b01/q7/__init__.py

@@ -10,9 +10,9 @@ from roborock.data.b01_q7.b01_q7_code_mappings import (
     SCWindMapping,
     WaterLevelMapping,
 )
-from roborock.devices.b01_q7_channel import send_decoded_command
-from roborock.devices.mqtt_channel import MqttChannel
+from roborock.devices.rpc.b01_q7_channel import send_decoded_command
 from roborock.devices.traits import Trait
+from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.protocols.b01_q7_protocol import CommandType, ParamsType, Q7RequestMessage
 from roborock.roborock_message import RoborockB01Props
 from roborock.roborock_typing import RoborockB01Q7Methods

{python_roborock-4.1.1 → python_roborock-4.2.1}/roborock/devices/traits/traits_mixin.py

@@ -34,6 +34,9 @@ class TraitsMixin:
     b01_q7_properties: b01.Q7PropertiesApi | None = None
     """B01 Q7 properties trait, if supported."""
 
+    b01_q10_properties: b01.Q10PropertiesApi | None = None
+    """B01 Q10 properties trait, if supported."""
+
     def __init__(self, trait: Trait) -> None:
         """Initialize the TraitsMixin with the given trait.
 

python_roborock-4.2.1/roborock/devices/transport/__init__.py

@@ -0,0 +1,8 @@
+"""Module for handling network connections to Roborock devices.
+
+This is used internally by the device manager for creating connections to
+Roborock devices. These modules contain common code, not specific to a
+particular device or application level protocol.
+"""
+
+__all__: list[str] = []

{python_roborock-4.1.1/roborock/devices → python_roborock-4.2.1/roborock/devices/transport}/local_channel.py

@@ -8,10 +8,10 @@ from dataclasses import dataclass
 from roborock.callbacks import CallbackList, decoder_callback
 from roborock.exceptions import RoborockConnectionException, RoborockException
 from roborock.protocol import create_local_decoder, create_local_encoder
+from roborock.protocols.v1_protocol import LocalProtocolVersion
 from roborock.roborock_message import RoborockMessage, RoborockMessageProtocol
+from roborock.util import RoborockLoggerAdapter, get_next_int
 
-from ..protocols.v1_protocol import LocalProtocolVersion
-from ..util import RoborockLoggerAdapter, get_next_int
 from .channel import Channel
 
 _LOGGER = logging.getLogger(__name__)