roborock-cli 0.1.1__py3-none-any.whl

roborock_cli/_vendor/roborock/devices/traits/b01/q10/__init__.py

@@ -0,0 +1,76 @@
+"""Traits for Q10 B01 devices."""
+
+import asyncio
+import logging
+from typing import Any
+
+from roborock_cli._vendor.roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+from roborock_cli._vendor.roborock.devices.rpc.b01_q10_channel import stream_decoded_responses
+from roborock_cli._vendor.roborock.devices.traits import Trait
+from roborock_cli._vendor.roborock.devices.transport.mqtt_channel import MqttChannel
+
+from .command import CommandTrait
+from .status import StatusTrait
+from .vacuum import VacuumTrait
+
+__all__ = [
+    "Q10PropertiesApi",
+]
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Q10PropertiesApi(Trait):
+    """API for interacting with B01 devices."""
+
+    command: CommandTrait
+    """Trait for sending commands to Q10 devices."""
+
+    status: StatusTrait
+    """Trait for managing the status of Q10 devices."""
+
+    vacuum: VacuumTrait
+    """Trait for sending vacuum related commands to Q10 devices."""
+
+    def __init__(self, channel: MqttChannel) -> None:
+        """Initialize the B01Props API."""
+        self._channel = channel
+        self.command = CommandTrait(channel)
+        self.vacuum = VacuumTrait(self.command)
+        self.status = StatusTrait()
+        self._subscribe_task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        """Start any necessary subscriptions for the trait."""
+        self._subscribe_task = asyncio.create_task(self._subscribe_loop())
+
+    async def close(self) -> None:
+        """Close any resources held by the trait."""
+        if self._subscribe_task is not None:
+            self._subscribe_task.cancel()
+            try:
+                await self._subscribe_task
+            except asyncio.CancelledError:
+                pass  # ignore cancellation errors
+            self._subscribe_task = None
+
+    async def refresh(self) -> None:
+        """Refresh all traits."""
+        # Sending the REQUEST_DPS will cause the device to send all DPS values
+        # to the device. Updates will be received by the subscribe loop below.
+        await self.command.send(B01_Q10_DP.REQUEST_DPS, params={})
+
+    async def _subscribe_loop(self) -> None:
+        """Persistent loop to listen for status updates."""
+        async for decoded_dps in stream_decoded_responses(self._channel):
+            _LOGGER.debug("Received Q10 status update: %s", decoded_dps)
+
+            # Notify all traits about a new message and each trait will
+            # only update what fields that it is responsible for.
+            # More traits can be added here below.
+            self.status.update_from_dps(decoded_dps)
+
+
+def create(channel: MqttChannel) -> Q10PropertiesApi:
+    """Create traits for B01 devices."""
+    return Q10PropertiesApi(channel)

roborock_cli/_vendor/roborock/devices/traits/b01/q10/command.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+from roborock_cli._vendor.roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+from roborock_cli._vendor.roborock.devices.rpc.b01_q10_channel import send_command
+from roborock_cli._vendor.roborock.devices.transport.mqtt_channel import MqttChannel
+from roborock_cli._vendor.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)

roborock_cli/_vendor/roborock/devices/traits/b01/q10/common.py

@@ -0,0 +1,115 @@
+"""Common utilities for Q10 traits.
+
+This module provides infrastructure for mapping Roborock Data Points (DPS) to
+Python dataclass fields and handling the lifecycle of data updates from the
+device.
+
+### DPS Metadata Annotation
+
+Classes extending `RoborockBase` can annotate their fields with DPS IDs using
+the `field(metadata={"dps": ...})` convention. This creates a declarative
+mapping that `DpsDataConverter` uses to automatically route incoming device
+data to the correct attribute.
+
+Example:
+
+```python
+@dataclass
+class MyStatus(RoborockBase):
+    battery: int = field(metadata={"dps": B01_Q10_DP.BATTERY})
+```
+
+### Update Lifecycle
+1. **Raw Data**: The device sends encoded DPS updates over MQTT.
+2. **Decoding**: The transport layer decodes these into a dictionary (e.g., `{"101": 80}`).
+3. **Conversion**: `DpsDataConverter` uses `RoborockBase.convert_dict` to transform
+   raw values into appropriate Python types (e.g., Enums, ints) based on the
+   dataclass field types.
+4. **Update**: `update_from_dps` maps these converted values to field names and
+   updates the target object using `setattr`.
+
+### Usage
+
+Typically, a trait will instantiate a single `DpsDataConverter` for its status class
+and call `update_from_dps` whenever new data is received from the device stream.
+
+"""
+
+import dataclasses
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from roborock_cli._vendor.roborock.callbacks import CallbackList
+from roborock_cli._vendor.roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+from roborock_cli._vendor.roborock.data.containers import RoborockBase
+
+
+class TraitUpdateListener:
+    """Trait update listener.
+
+    This is a base class for traits to support notifying listeners when they
+    have been updated. Clients may register callbacks to be notified when the
+    trait has been updated. When the listener callback is invoked, the client
+    should read the trait's properties to get the updated values.
+    """
+
+    def __init__(self, logger: logging.Logger) -> None:
+        """Initialize the trait update listener."""
+        self._update_callbacks: CallbackList[None] = CallbackList(logger=logger)
+
+    def add_update_listener(self, callback: Callable[[], None]) -> Callable[[], None]:
+        """Register a callback when the trait has been updated.
+
+        Returns a callable to remove the listener.
+        """
+        # We wrap the callback to ignore the value passed to it.
+        return self._update_callbacks.add_callback(lambda _: callback())
+
+    def _notify_update(self) -> None:
+        """Notify all update listeners."""
+        self._update_callbacks(None)
+
+
+class DpsDataConverter:
+    """Utility to handle the transformation and merging of DPS data into models.
+
+    This class pre-calculates the mapping between Data Point IDs and dataclass fields
+    to optimize repeated updates from device streams.
+    """
+
+    def __init__(self, dps_type_map: dict[B01_Q10_DP, type], dps_field_map: dict[B01_Q10_DP, str]):
+        """Initialize the converter for a specific RoborockBase-derived class."""
+        self._dps_type_map = dps_type_map
+        self._dps_field_map = dps_field_map
+
+    @classmethod
+    def from_dataclass(cls, dataclass_type: type[RoborockBase]):
+        """Initialize the converter for a specific RoborockBase-derived class."""
+        dps_type_map: dict[B01_Q10_DP, type] = {}
+        dps_field_map: dict[B01_Q10_DP, str] = {}
+        for field_obj in dataclasses.fields(dataclass_type):
+            if field_obj.metadata and "dps" in field_obj.metadata:
+                dps_id = field_obj.metadata["dps"]
+                dps_type_map[dps_id] = field_obj.type
+                dps_field_map[dps_id] = field_obj.name
+        return cls(dps_type_map, dps_field_map)
+
+    def update_from_dps(self, target: RoborockBase, decoded_dps: dict[B01_Q10_DP, Any]) -> bool:
+        """Convert and merge raw DPS data into the target object.
+
+        Uses the pre-calculated type mapping to ensure values are converted to the
+        correct Python types before being updated on the target.
+
+        Args:
+            target: The target object to update.
+            decoded_dps: The decoded DPS data to convert.
+
+        Returns:
+            True if any values were updated, False otherwise.
+        """
+        conversions = RoborockBase.convert_dict(self._dps_type_map, decoded_dps)
+        for dps_id, value in conversions.items():
+            field_name = self._dps_field_map[dps_id]
+            setattr(target, field_name, value)
+        return bool(conversions)

roborock_cli/_vendor/roborock/devices/traits/b01/q10/status.py

@@ -0,0 +1,32 @@
+"""Status trait for Q10 B01 devices."""
+
+import logging
+from typing import Any
+
+from roborock_cli._vendor.roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+from roborock_cli._vendor.roborock.data.b01_q10.b01_q10_containers import Q10Status
+
+from .common import DpsDataConverter, TraitUpdateListener
+
+_LOGGER = logging.getLogger(__name__)
+
+_CONVERTER = DpsDataConverter.from_dataclass(Q10Status)
+
+
+class StatusTrait(Q10Status, TraitUpdateListener):
+    """Trait for managing the status of Q10 Roborock devices.
+
+    This is a thin wrapper around Q10Status that provides the Trait interface.
+    The current values reflect the most recently received data from the device.
+    New values can be requested through the `Q10PropertiesApi`'s `refresh` method.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the status trait."""
+        super().__init__()
+        TraitUpdateListener.__init__(self, logger=_LOGGER)
+
+    def update_from_dps(self, decoded_dps: dict[B01_Q10_DP, Any]) -> None:
+        """Update the trait from raw DPS data."""
+        if _CONVERTER.update_from_dps(self, decoded_dps):
+            self._notify_update()

roborock_cli/_vendor/roborock/devices/traits/b01/q10/vacuum.py

@@ -0,0 +1,81 @@
+"""Traits for Q10 B01 devices."""
+
+from roborock_cli._vendor.roborock.data.b01_q10.b01_q10_code_mappings import (
+    B01_Q10_DP,
+    YXCleanType,
+    YXFanLevel,
+)
+
+from .command import CommandTrait
+
+
+class VacuumTrait:
+    """Trait for sending vacuum commands.
+
+    This is a wrapper around the CommandTrait for sending vacuum related
+    commands to Q10 devices.
+    """
+
+    def __init__(self, command: CommandTrait) -> None:
+        """Initialize the VacuumTrait."""
+        self._command = command
+
+    async def start_clean(self) -> None:
+        """Start cleaning."""
+        await self._command.send(
+            command=B01_Q10_DP.START_CLEAN,
+            # TODO: figure out other commands
+            # 1 = start cleaning
+            # 2 = "electoral" clean, also has "clean_parameters"
+            # 4 = fast create map
+            params={"cmd": 1},
+        )
+
+    async def pause_clean(self) -> None:
+        """Pause cleaning."""
+        await self._command.send(
+            command=B01_Q10_DP.PAUSE,
+            params={},
+        )
+
+    async def resume_clean(self) -> None:
+        """Resume cleaning."""
+        await self._command.send(
+            command=B01_Q10_DP.RESUME,
+            params={},
+        )
+
+    async def stop_clean(self) -> None:
+        """Stop cleaning."""
+        await self._command.send(
+            command=B01_Q10_DP.STOP,
+            params={},
+        )
+
+    async def return_to_dock(self) -> None:
+        """Return to dock."""
+        await self._command.send(
+            command=B01_Q10_DP.START_DOCK_TASK,
+            params={},
+        )
+
+    async def empty_dustbin(self) -> None:
+        """Empty the dustbin at the dock."""
+        await self._command.send(
+            command=B01_Q10_DP.START_DOCK_TASK,
+            params=2,  # 2 = dock task type for "empty dustbin"
+        )
+
+    async def set_clean_mode(self, mode: YXCleanType) -> None:
+        """Set the cleaning mode (vacuum, mop, or both)."""
+        await self._command.send(
+            command=B01_Q10_DP.CLEAN_MODE,
+            params=mode.code,
+        )
+
+    async def set_fan_level(self, level: YXFanLevel) -> None:
+        """Set the fan suction level."""
+        await self._command.send(
+            command=B01_Q10_DP.FAN_LEVEL,
+            params=level.code,
+        )

roborock_cli/_vendor/roborock/devices/traits/b01/q7/__init__.py

@@ -0,0 +1,136 @@
+"""Traits for Q7 B01 devices.
+Potentially other devices may fall into this category in the future."""
+
+from typing import Any
+
+from roborock_cli._vendor.roborock import B01Props
+from roborock_cli._vendor.roborock.data.b01_q7.b01_q7_code_mappings import (
+    CleanPathPreferenceMapping,
+    CleanRepeatMapping,
+    CleanTaskTypeMapping,
+    CleanTypeMapping,
+    SCDeviceCleanParam,
+    SCWindMapping,
+    WaterLevelMapping,
+)
+from roborock_cli._vendor.roborock.devices.rpc.b01_q7_channel import send_decoded_command
+from roborock_cli._vendor.roborock.devices.traits import Trait
+from roborock_cli._vendor.roborock.devices.transport.mqtt_channel import MqttChannel
+from roborock_cli._vendor.roborock.protocols.b01_q7_protocol import CommandType, ParamsType, Q7RequestMessage
+from roborock_cli._vendor.roborock.roborock_message import RoborockB01Props
+from roborock_cli._vendor.roborock.roborock_typing import RoborockB01Q7Methods
+
+from .clean_summary import CleanSummaryTrait
+
+__all__ = [
+    "Q7PropertiesApi",
+    "CleanSummaryTrait",
+]
+
+
+class Q7PropertiesApi(Trait):
+    """API for interacting with B01 devices."""
+
+    clean_summary: CleanSummaryTrait
+    """Trait for clean records / clean summary (Q7 `service.get_record_list`)."""
+
+    def __init__(self, channel: MqttChannel) -> None:
+        """Initialize the B01Props API."""
+        self._channel = channel
+        self.clean_summary = CleanSummaryTrait(channel)
+
+    async def query_values(self, props: list[RoborockB01Props]) -> B01Props | None:
+        """Query the device for the values of the given Q7 properties."""
+        result = await self.send(
+            RoborockB01Q7Methods.GET_PROP,
+            {"property": props},
+        )
+        if not isinstance(result, dict):
+            raise TypeError(f"Unexpected response type for GET_PROP: {type(result).__name__}: {result!r}")
+        return B01Props.from_dict(result)
+
+    async def set_prop(self, prop: RoborockB01Props, value: Any) -> None:
+        """Set a property on the device."""
+        await self.send(
+            command=RoborockB01Q7Methods.SET_PROP,
+            params={prop: value},
+        )
+
+    async def set_fan_speed(self, fan_speed: SCWindMapping) -> None:
+        """Set the fan speed (wind)."""
+        await self.set_prop(RoborockB01Props.WIND, fan_speed.code)
+
+    async def set_water_level(self, water_level: WaterLevelMapping) -> None:
+        """Set the water level (water)."""
+        await self.set_prop(RoborockB01Props.WATER, water_level.code)
+
+    async def set_mode(self, mode: CleanTypeMapping) -> None:
+        """Set the cleaning mode (vacuum, mop, or vacuum and mop)."""
+        await self.set_prop(RoborockB01Props.MODE, mode.code)
+
+    async def set_clean_path_preference(self, preference: CleanPathPreferenceMapping) -> None:
+        """Set the cleaning path preference (route)."""
+        await self.set_prop(RoborockB01Props.CLEAN_PATH_PREFERENCE, preference.code)
+
+    async def set_repeat_state(self, repeat: CleanRepeatMapping) -> None:
+        """Set the cleaning repeat state (cycles)."""
+        await self.set_prop(RoborockB01Props.REPEAT_STATE, repeat.code)
+
+    async def start_clean(self) -> None:
+        """Start cleaning."""
+        await self.send(
+            command=RoborockB01Q7Methods.SET_ROOM_CLEAN,
+            params={
+                "clean_type": CleanTaskTypeMapping.ALL.code,
+                "ctrl_value": SCDeviceCleanParam.START.code,
+                "room_ids": [],
+            },
+        )
+
+    async def pause_clean(self) -> None:
+        """Pause cleaning."""
+        await self.send(
+            command=RoborockB01Q7Methods.SET_ROOM_CLEAN,
+            params={
+                "clean_type": CleanTaskTypeMapping.ALL.code,
+                "ctrl_value": SCDeviceCleanParam.PAUSE.code,
+                "room_ids": [],
+            },
+        )
+
+    async def stop_clean(self) -> None:
+        """Stop cleaning."""
+        await self.send(
+            command=RoborockB01Q7Methods.SET_ROOM_CLEAN,
+            params={
+                "clean_type": CleanTaskTypeMapping.ALL.code,
+                "ctrl_value": SCDeviceCleanParam.STOP.code,
+                "room_ids": [],
+            },
+        )
+
+    async def return_to_dock(self) -> None:
+        """Return to dock."""
+        await self.send(
+            command=RoborockB01Q7Methods.START_RECHARGE,
+            params={},
+        )
+
+    async def find_me(self) -> None:
+        """Locate the robot."""
+        await self.send(
+            command=RoborockB01Q7Methods.FIND_DEVICE,
+            params={},
+        )
+
+    async def send(self, command: CommandType, params: ParamsType) -> Any:
+        """Send a command to the device."""
+        return await send_decoded_command(
+            self._channel,
+            Q7RequestMessage(dps=10000, command=command, params=params),
+        )
+
+
+def create(channel: MqttChannel) -> Q7PropertiesApi:
+    """Create traits for B01 devices."""
+    return Q7PropertiesApi(channel)

roborock_cli/_vendor/roborock/devices/traits/b01/q7/clean_summary.py

@@ -0,0 +1,75 @@
+"""Clean summary / clean records trait for B01 Q7 devices.
+
+For B01/Q7, the Roborock app uses `service.get_record_list` which returns totals
+and a `record_list` whose items contain a JSON string in `detail`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from roborock_cli._vendor.roborock import CleanRecordDetail, CleanRecordList, CleanRecordSummary
+from roborock_cli._vendor.roborock.devices.rpc.b01_q7_channel import send_decoded_command
+from roborock_cli._vendor.roborock.devices.traits import Trait
+from roborock_cli._vendor.roborock.devices.transport.mqtt_channel import MqttChannel
+from roborock_cli._vendor.roborock.exceptions import RoborockException
+from roborock_cli._vendor.roborock.protocols.b01_q7_protocol import Q7RequestMessage
+from roborock_cli._vendor.roborock.roborock_typing import RoborockB01Q7Methods
+
+__all__ = [
+    "CleanSummaryTrait",
+]
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CleanSummaryTrait(CleanRecordSummary, Trait):
+    """B01/Q7 clean summary + clean record access (via record list service)."""
+
+    def __init__(self, channel: MqttChannel) -> None:
+        """Initialize the clean summary trait.
+
+        Args:
+            channel: MQTT channel used to communicate with the device.
+        """
+        super().__init__()
+        self._channel = channel
+
+    async def refresh(self) -> None:
+        """Refresh totals and last record detail from the device."""
+        record_list = await self._get_record_list()
+
+        self.total_time = record_list.total_time
+        self.total_area = record_list.total_area
+        self.total_count = record_list.total_count
+
+        details = await self._get_clean_record_details(record_list=record_list)
+        self.last_record_detail = details[0] if details else None
+
+    async def _get_record_list(self) -> CleanRecordList:
+        """Fetch the raw device clean record list (`service.get_record_list`)."""
+        result = await send_decoded_command(
+            self._channel,
+            Q7RequestMessage(dps=10000, command=RoborockB01Q7Methods.GET_RECORD_LIST, params={}),
+        )
+
+        if not isinstance(result, dict):
+            raise TypeError(f"Unexpected response type for GET_RECORD_LIST: {type(result).__name__}: {result!r}")
+        return CleanRecordList.from_dict(result)
+
+    async def _get_clean_record_details(self, *, record_list: CleanRecordList) -> list[CleanRecordDetail]:
+        """Return parsed record detail objects (newest-first)."""
+        details: list[CleanRecordDetail] = []
+        for item in record_list.record_list:
+            try:
+                parsed = item.detail_parsed
+            except RoborockException as ex:
+                # Rather than failing if something goes wrong here, we should fail and log to tell the user.
+                _LOGGER.debug("Failed to parse record detail: %s", ex)
+                continue
+            if parsed is not None:
+                details.append(parsed)
+
+        # The server returns the newest record at the end of record_list; reverse so newest is first (index 0).
+        details.reverse()
+        return details

roborock_cli/_vendor/roborock/devices/traits/traits_mixin.py

@@ -0,0 +1,64 @@
+"""Holds device traits mixin and related code.
+
+This holds the TraitsMixin class, which is used to provide accessors for
+various device traits. Each trait is a class that encapsulates a specific
+set of functionality for a device, such as controlling a vacuum or a mop.
+
+The TraitsMixin holds traits across all protocol types. A trait is supported
+if it is non-None.
+"""
+
+from dataclasses import dataclass, fields
+from typing import get_args, get_origin
+
+from . import Trait, a01, b01, v1
+
+__all__ = [
+    "TraitsMixin",
+]
+
+
+@dataclass(init=False)
+class TraitsMixin:
+    """Mixin to provide trait accessors."""
+
+    v1_properties: v1.PropertiesApi | None = None
+    """V1 properties trait, if supported."""
+
+    dyad: a01.DyadApi | None = None
+    """Dyad API, if supported."""
+
+    zeo: a01.ZeoApi | None = None
+    """Zeo API, if supported."""
+
+    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.
+
+        This will populate the appropriate trait attributes based on the types
+        of the traits provided.
+        """
+        for item in fields(self):
+            trait_type = _get_trait_type(item)
+            if trait_type is type(trait):
+                setattr(self, item.name, trait)
+                break
+
+
+def _get_trait_type(item) -> type[Trait]:
+    """Get the trait type from a dataclass field."""
+    if get_origin(item.type) is None:
+        raise ValueError(f"Trait {item.name} is not an optional type")
+    if (args := get_args(item.type)) is None:
+        raise ValueError(f"Trait {item.name} is not an optional type")
+    if len(args) != 2 or args[1] is not type(None):
+        raise ValueError(f"Trait {item.name} is not an optional type")
+    trait_type = args[0]
+    if not issubclass(trait_type, Trait):
+        raise ValueError(f"Trait {item.name} is not a Trait subclass")
+    return trait_type