roborock-cli 0.1.1__py3-none-any.whl

roborock_cli/_vendor/roborock/devices/traits/v1/__init__.py

@@ -0,0 +1,344 @@
+"""Create traits for V1 devices.
+
+Traits are modular components that encapsulate specific features of a Roborock
+device. This module provides a factory function to create and initialize the
+appropriate traits for V1 devices based on their capabilities.
+
+Using Traits
+------------
+Traits are accessed via the `v1_properties` attribute on a device. Each trait
+represents a specific capability, such as `status`, `consumables`, or `rooms`.
+
+Traits serve two main purposes:
+1.  **State**: Traits are dataclasses that hold the current state of the device
+    feature. You can access attributes directly (e.g., `device.v1_properties.status.battery`).
+2.  **Commands**: Traits provide methods to control the device. For example,
+    `device.v1_properties.volume.set_volume()`.
+
+Additionally, the `command` trait provides a generic way to send any command to the
+device (e.g. `device.v1_properties.command.send("app_start")`). This is often used
+for basic cleaning operations like starting, stopping, or docking the vacuum.
+
+Most traits have a `refresh()` method that must be called to update their state
+from the device. The state is not updated automatically in real-time unless
+specifically implemented by the trait or via polling.
+
+Adding New Traits
+-----------------
+When adding a new trait, the most common pattern is to subclass `V1TraitMixin`
+and a `RoborockBase` dataclass. You must define a `command` class variable that
+specifies the `RoborockCommand` used to fetch the trait data from the device.
+See `common.py` for more details on common patterns used across traits.
+
+There are some additional decorators in `common.py` that can be used to specify which
+RPC channel to use for the trait (standard, MQTT/cloud, or map-specific).
+
+  - `@common.mqtt_rpc_channel` - Use the MQTT RPC channel for this trait.
+  - `@common.map_rpc_channel` - Use the map RPC channel for this trait.
+
+There are also some attributes that specify device feature dependencies for
+optional traits:
+
+    - `requires_feature` - The string name of the device feature that must be supported
+        for this trait to be enabled. See `DeviceFeaturesTrait` for a list of
+        available features.
+    - `requires_dock_type` - If set, this is a function that accepts a `RoborockDockTypeCode`
+        and returns a boolean indicating whether the trait is supported for that dock type.
+
+Additionally, DeviceFeaturesTrait has a method `is_field_supported` that is used to
+check individual trait field values. This is a more fine grained version to allow
+optional fields in a dataclass, vs the above feature checks that apply to an entire
+trait. The `requires_schema_code` field metadata attribute is a string of the schema
+code in HomeDataProduct Schema that is required for the field to be supported.
+"""
+
+import logging
+from dataclasses import dataclass, field, fields
+from typing import Any, get_args
+
+from roborock_cli._vendor.roborock.data.containers import HomeData, HomeDataProduct, RoborockBase
+from roborock_cli._vendor.roborock.data.v1.v1_code_mappings import RoborockDockTypeCode
+from roborock_cli._vendor.roborock.devices.cache import DeviceCache
+from roborock_cli._vendor.roborock.devices.traits import Trait
+from roborock_cli._vendor.roborock.map.map_parser import MapParserConfig
+from roborock_cli._vendor.roborock.protocols.v1_protocol import V1RpcChannel
+from roborock_cli._vendor.roborock.web_api import UserWebApiClient
+
+from . import (
+    child_lock,
+    clean_summary,
+    command,
+    common,
+    consumeable,
+    device_features,
+    do_not_disturb,
+    dust_collection_mode,
+    flow_led_status,
+    home,
+    led_status,
+    map_content,
+    maps,
+    network_info,
+    rooms,
+    routines,
+    smart_wash_params,
+    status,
+    valley_electricity_timer,
+    volume,
+    wash_towel_mode,
+)
+from .child_lock import ChildLockTrait
+from .clean_summary import CleanSummaryTrait
+from .command import CommandTrait
+from .common import V1TraitMixin
+from .consumeable import ConsumableTrait
+from .device_features import DeviceFeaturesTrait
+from .do_not_disturb import DoNotDisturbTrait
+from .dust_collection_mode import DustCollectionModeTrait
+from .flow_led_status import FlowLedStatusTrait
+from .home import HomeTrait
+from .led_status import LedStatusTrait
+from .map_content import MapContentTrait
+from .maps import MapsTrait
+from .network_info import NetworkInfoTrait
+from .rooms import RoomsTrait
+from .routines import RoutinesTrait
+from .smart_wash_params import SmartWashParamsTrait
+from .status import StatusTrait
+from .valley_electricity_timer import ValleyElectricityTimerTrait
+from .volume import SoundVolumeTrait
+from .wash_towel_mode import WashTowelModeTrait
+
+_LOGGER = logging.getLogger(__name__)
+
+__all__ = [
+    "PropertiesApi",
+    "child_lock",
+    "clean_summary",
+    "command",
+    "common",
+    "consumeable",
+    "device_features",
+    "do_not_disturb",
+    "dust_collection_mode",
+    "flow_led_status",
+    "home",
+    "led_status",
+    "map_content",
+    "maps",
+    "network_info",
+    "rooms",
+    "routines",
+    "smart_wash_params",
+    "status",
+    "valley_electricity_timer",
+    "volume",
+    "wash_towel_mode",
+]
+
+
+@dataclass
+class PropertiesApi(Trait):
+    """Common properties for V1 devices.
+
+    This class holds all the traits that are common across all V1 devices.
+    """
+
+    # All v1 devices have these traits
+    status: StatusTrait
+    command: CommandTrait
+    dnd: DoNotDisturbTrait
+    clean_summary: CleanSummaryTrait
+    sound_volume: SoundVolumeTrait
+    rooms: RoomsTrait
+    maps: MapsTrait
+    map_content: MapContentTrait
+    consumables: ConsumableTrait
+    home: HomeTrait
+    device_features: DeviceFeaturesTrait
+    network_info: NetworkInfoTrait
+    routines: RoutinesTrait
+
+    # Optional features that may not be supported on all devices
+    child_lock: ChildLockTrait | None = None
+    led_status: LedStatusTrait | None = None
+    flow_led_status: FlowLedStatusTrait | None = None
+    valley_electricity_timer: ValleyElectricityTimerTrait | None = None
+    dust_collection_mode: DustCollectionModeTrait | None = None
+    wash_towel_mode: WashTowelModeTrait | None = None
+    smart_wash_params: SmartWashParamsTrait | None = None
+
+    def __init__(
+        self,
+        device_uid: str,
+        product: HomeDataProduct,
+        home_data: HomeData,
+        rpc_channel: V1RpcChannel,
+        mqtt_rpc_channel: V1RpcChannel,
+        map_rpc_channel: V1RpcChannel,
+        web_api: UserWebApiClient,
+        device_cache: DeviceCache,
+        map_parser_config: MapParserConfig | None = None,
+        region: str | None = None,
+    ) -> None:
+        """Initialize the V1TraitProps."""
+        self._device_uid = device_uid
+        self._rpc_channel = rpc_channel
+        self._mqtt_rpc_channel = mqtt_rpc_channel
+        self._map_rpc_channel = map_rpc_channel
+        self._web_api = web_api
+        self._device_cache = device_cache
+        self._region = region
+
+        self.device_features = DeviceFeaturesTrait(product, self._device_cache)
+        self.status = StatusTrait(self.device_features, region=self._region)
+        self.consumables = ConsumableTrait()
+        self.rooms = RoomsTrait(home_data, web_api)
+        self.maps = MapsTrait(self.status)
+        self.map_content = MapContentTrait(map_parser_config)
+        self.home = HomeTrait(self.status, self.maps, self.map_content, self.rooms, self._device_cache)
+        self.network_info = NetworkInfoTrait(device_uid, self._device_cache)
+        self.routines = RoutinesTrait(device_uid, web_api)
+
+        # Dynamically create any traits that need to be populated
+        for item in fields(self):
+            if (trait := getattr(self, item.name, None)) is None:
+                # We exclude optional features and them via discover_features
+                if (union_args := get_args(item.type)) is None or len(union_args) > 0:
+                    continue
+                _LOGGER.debug("Trait '%s' is supported, initializing", item.name)
+                if not callable(item.type):
+                    continue
+                trait = item.type()
+                setattr(self, item.name, trait)
+            # This is a hack to allow setting the rpc_channel on all traits. This is
+            # used so we can preserve the dataclass behavior when the values in the
+            # traits are updated, but still want to allow them to have a reference
+            # to the rpc channel for sending commands.
+            trait._rpc_channel = self._get_rpc_channel(trait)
+
+    def _get_rpc_channel(self, trait: V1TraitMixin) -> V1RpcChannel:
+        # The decorator `@common.mqtt_rpc_channel` means that the trait needs
+        # to use the mqtt_rpc_channel (cloud only) instead of the rpc_channel (adaptive)
+        if hasattr(trait, "mqtt_rpc_channel"):
+            return self._mqtt_rpc_channel
+        elif hasattr(trait, "map_rpc_channel"):
+            return self._map_rpc_channel
+        else:
+            return self._rpc_channel
+
+    async def discover_features(self) -> None:
+        """Populate any supported traits that were not initialized in __init__."""
+        _LOGGER.debug("Starting optional trait discovery")
+        await self.device_features.refresh()
+        # Dock type also acts like a device feature for some traits.
+        dock_type = await self._dock_type()
+
+        # Dynamically create any traits that need to be populated
+        for item in fields(self):
+            if (trait := getattr(self, item.name, None)) is not None:
+                continue
+            if (union_args := get_args(item.type)) is None:
+                raise ValueError(f"Unexpected non-union type for trait {item.name}: {item.type}")
+            if len(union_args) != 2 or type(None) not in union_args:
+                raise ValueError(f"Unexpected non-optional type for trait {item.name}: {item.type}")
+
+            # Union args may not be in declared order
+            item_type = union_args[0] if union_args[1] is type(None) else union_args[1]
+            if not self._is_supported(item_type, item.name, dock_type):
+                _LOGGER.debug("Trait '%s' not supported, skipping", item.name)
+                continue
+            _LOGGER.debug("Trait '%s' is supported, initializing", item.name)
+            trait = item_type()
+            setattr(self, item.name, trait)
+            trait._rpc_channel = self._get_rpc_channel(trait)
+
+    def _is_supported(self, trait_type: type[V1TraitMixin], name: str, dock_type: RoborockDockTypeCode) -> bool:
+        """Check if a trait is supported by the device."""
+
+        if (requires_dock_type := getattr(trait_type, "requires_dock_type", None)) is not None:
+            return requires_dock_type(dock_type)
+
+        if (feature_name := getattr(trait_type, "requires_feature", None)) is None:
+            _LOGGER.debug("Optional trait missing 'requires_feature' attribute %s, skipping", name)
+            return False
+        if (is_supported := getattr(self.device_features, feature_name)) is None:
+            raise ValueError(f"Device feature '{feature_name}' on trait '{name}' is unknown")
+        return is_supported
+
+    async def _dock_type(self) -> RoborockDockTypeCode:
+        """Get the dock type from the status trait or cache."""
+        dock_type = await self._get_cached_trait_data("dock_type")
+        if dock_type is not None:
+            _LOGGER.debug("Using cached dock type: %s", dock_type)
+            try:
+                return RoborockDockTypeCode(dock_type)
+            except ValueError:
+                _LOGGER.debug("Cached dock type %s is invalid, refreshing", dock_type)
+
+        _LOGGER.debug("Starting dock type discovery")
+        await self.status.refresh()
+        _LOGGER.debug("Fetched dock type: %s", self.status.dock_type)
+        if self.status.dock_type is None:
+            # Explicitly set so we reuse cached value next type
+            dock_type = RoborockDockTypeCode.no_dock
+        else:
+            dock_type = self.status.dock_type
+        await self._set_cached_trait_data("dock_type", dock_type)
+        return dock_type
+
+    async def _get_cached_trait_data(self, name: str) -> Any:
+        """Get the dock type from the status trait or cache."""
+        cache_data = await self._device_cache.get()
+        if cache_data.trait_data is None:
+            cache_data.trait_data = {}
+        _LOGGER.debug("Cached trait data: %s", cache_data.trait_data)
+        return cache_data.trait_data.get(name)
+
+    async def _set_cached_trait_data(self, name: str, value: Any) -> None:
+        """Set trait-specific cached data."""
+        cache_data = await self._device_cache.get()
+        if cache_data.trait_data is None:
+            cache_data.trait_data = {}
+        cache_data.trait_data[name] = value
+        _LOGGER.debug("Updating cached trait data: %s", cache_data.trait_data)
+        await self._device_cache.set(cache_data)
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return the trait data as a dictionary."""
+        result: dict[str, Any] = {}
+        for item in fields(self):
+            trait = getattr(self, item.name, None)
+            if trait is None or not isinstance(trait, RoborockBase):
+                continue
+            data = trait.as_dict()
+            if data:  # Don't omit unset traits
+                result[item.name] = data
+        return result
+
+
+def create(
+    device_uid: str,
+    product: HomeDataProduct,
+    home_data: HomeData,
+    rpc_channel: V1RpcChannel,
+    mqtt_rpc_channel: V1RpcChannel,
+    map_rpc_channel: V1RpcChannel,
+    web_api: UserWebApiClient,
+    device_cache: DeviceCache,
+    map_parser_config: MapParserConfig | None = None,
+    region: str | None = None,
+) -> PropertiesApi:
+    """Create traits for V1 devices."""
+    return PropertiesApi(
+        device_uid,
+        product,
+        home_data,
+        rpc_channel,
+        mqtt_rpc_channel,
+        map_rpc_channel,
+        web_api,
+        device_cache,
+        map_parser_config,
+        region=region,
+    )

roborock_cli/_vendor/roborock/devices/traits/v1/child_lock.py

@@ -0,0 +1,29 @@
+from roborock_cli._vendor.roborock.data import ChildLockStatus
+from roborock_cli._vendor.roborock.devices.traits.v1 import common
+from roborock_cli._vendor.roborock.roborock_typing import RoborockCommand
+
+_STATUS_PARAM = "lock_status"
+
+
+class ChildLockTrait(ChildLockStatus, common.V1TraitMixin, common.RoborockSwitchBase):
+    """Trait for controlling the child lock of a Roborock device."""
+
+    command = RoborockCommand.GET_CHILD_LOCK_STATUS
+    requires_feature = "is_set_child_supported"
+
+    @property
+    def is_on(self) -> bool:
+        """Return whether the child lock is enabled."""
+        return self.lock_status == 1
+
+    async def enable(self) -> None:
+        """Enable the child lock."""
+        await self.rpc_channel.send_command(RoborockCommand.SET_CHILD_LOCK_STATUS, params={_STATUS_PARAM: 1})
+        # Optimistic update to avoid an extra refresh
+        self.lock_status = 1
+
+    async def disable(self) -> None:
+        """Disable the child lock."""
+        await self.rpc_channel.send_command(RoborockCommand.SET_CHILD_LOCK_STATUS, params={_STATUS_PARAM: 0})
+        # Optimistic update to avoid an extra refresh
+        self.lock_status = 0

roborock_cli/_vendor/roborock/devices/traits/v1/clean_summary.py

@@ -0,0 +1,83 @@
+import logging
+from typing import Self
+
+from roborock_cli._vendor.roborock.data import CleanRecord, CleanSummaryWithDetail
+from roborock_cli._vendor.roborock.devices.traits.v1 import common
+from roborock_cli._vendor.roborock.roborock_typing import RoborockCommand
+from roborock_cli._vendor.roborock.util import unpack_list
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CleanSummaryTrait(CleanSummaryWithDetail, common.V1TraitMixin):
+    """Trait for managing the clean summary of Roborock devices."""
+
+    command = RoborockCommand.GET_CLEAN_SUMMARY
+
+    async def refresh(self) -> None:
+        """Refresh the clean summary data and last clean record.
+
+        Assumes that the clean summary has already been fetched.
+        """
+        await super().refresh()
+        if not self.records:
+            _LOGGER.debug("No clean records available in clean summary.")
+            self.last_clean_record = None
+            return
+        last_record_id = self.records[0]
+        self.last_clean_record = await self.get_clean_record(last_record_id)
+
+    @classmethod
+    def _parse_type_response(cls, response: common.V1ResponseData) -> Self:
+        """Parse the response from the device into a CleanSummary."""
+        if isinstance(response, dict):
+            return cls.from_dict(response)
+        elif isinstance(response, list):
+            clean_time, clean_area, clean_count, records = unpack_list(response, 4)
+            return cls(
+                clean_time=clean_time,
+                clean_area=clean_area,
+                clean_count=clean_count,
+                records=records,
+            )
+        elif isinstance(response, int):
+            return cls(clean_time=response)
+        raise ValueError(f"Unexpected clean summary format: {response!r}")
+
+    async def get_clean_record(self, record_id: int) -> CleanRecord:
+        """Load a specific clean record by ID."""
+        response = await self.rpc_channel.send_command(RoborockCommand.GET_CLEAN_RECORD, params=[record_id])
+        return self._parse_clean_record_response(response)
+
+    @classmethod
+    def _parse_clean_record_response(cls, response: common.V1ResponseData) -> CleanRecord:
+        """Parse the response from the device into a CleanRecord."""
+        if isinstance(response, list) and len(response) == 1:
+            response = response[0]
+        if isinstance(response, dict):
+            return CleanRecord.from_dict(response)
+        if isinstance(response, list):
+            if isinstance(response[-1], dict):
+                records = [CleanRecord.from_dict(rec) for rec in response]
+                final_record = records[-1]
+                try:
+                    # This code is semi-presumptuous - so it is put in a try finally to be safe.
+                    final_record.begin = records[0].begin
+                    final_record.begin_datetime = records[0].begin_datetime
+                    final_record.start_type = records[0].start_type
+                    for rec in records[0:-1]:
+                        final_record.duration = (final_record.duration or 0) + (rec.duration or 0)
+                        final_record.area = (final_record.area or 0) + (rec.area or 0)
+                        final_record.avoid_count = (final_record.avoid_count or 0) + (rec.avoid_count or 0)
+                        final_record.wash_count = (final_record.wash_count or 0) + (rec.wash_count or 0)
+                        final_record.square_meter_area = (final_record.square_meter_area or 0) + (
+                            rec.square_meter_area or 0
+                        )
+                    return final_record
+                except Exception:
+                    # Return final record when an exception occurred
+                    return final_record
+            # There are still a few unknown variables in this.
+            begin, end, duration, area = unpack_list(response, 4)
+            return CleanRecord(begin=begin, end=end, duration=duration, area=area)
+        raise ValueError(f"Unexpected clean record format: {response!r}")

roborock_cli/_vendor/roborock/devices/traits/v1/command.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+from roborock_cli._vendor.roborock import RoborockCommand
+from roborock_cli._vendor.roborock.protocols.v1_protocol import ParamsType
+
+
+class CommandTrait:
+    """Trait for sending commands to Roborock devices.
+
+    This trait allows sending raw commands directly to the device. It is particularly
+    useful for:
+    1.  **Cleaning Control**: Sending commands like `app_start`, `app_stop`, `app_pause`,
+        or `app_charge` which don't belong to a specific state trait.
+    2.  **Unsupported Features**: Accessing device functionality that hasn't been
+        mapped to a specific trait yet.
+
+    See `roborock.roborock_typing.RoborockCommand` for a list of available commands.
+    """
+
+    def __post_init__(self) -> None:
+        """Post-initialization to set up the RPC channel.
+
+        This is called automatically after the dataclass is initialized by the
+        device setup code.
+        """
+        self._rpc_channel = None
+
+    async def send(self, command: RoborockCommand | str, 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._rpc_channel:
+            raise ValueError("Device trait in invalid state")
+        return await self._rpc_channel.send_command(command, params=params)

roborock_cli/_vendor/roborock/devices/traits/v1/common.py

@@ -0,0 +1,172 @@
+"""Module for Roborock V1 devices common trait commands.
+
+This is an internal library and should not be used directly by consumers.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, fields
+from typing import ClassVar, Self
+
+from roborock_cli._vendor.roborock.data import RoborockBase
+from roborock_cli._vendor.roborock.protocols.v1_protocol import V1RpcChannel
+from roborock_cli._vendor.roborock.roborock_typing import RoborockCommand
+
+_LOGGER = logging.getLogger(__name__)
+
+V1ResponseData = dict | list | int | str
+
+
+@dataclass
+class V1TraitMixin(ABC):
+    """Base model that supports v1 traits.
+
+    This class provides functioanlity for parsing responses from V1 devices
+    into dataclass instances. It also provides a reference to the V1RpcChannel
+    used to communicate with the device to execute commands.
+
+    Each trait subclass must define a class variable `command` that specifies
+    the RoborockCommand used to fetch the trait data from the device. The
+    `refresh()` method can be called to update the contents of the trait data
+    from the device.
+
+    A trait can also support additional commands for updating state associated
+    with the trait. It is expected that a trait will update its own internal
+    state either reflecting the change optimistically or by refreshing the
+    trait state from the device. In cases where one trait caches data that is
+    also represented in another trait, it is the responsibility of the caller
+    to ensure that both traits are refreshed as needed to keep them in sync.
+
+    The traits typically subclass RoborockBase to provide serialization
+    and deserialization functionality, but this is not strictly required.
+    """
+
+    command: ClassVar[RoborockCommand]
+
+    @classmethod
+    def _parse_type_response(cls, response: V1ResponseData) -> RoborockBase:
+        """Parse the response from the device into a a RoborockBase.
+
+        Subclasses should override this method to implement custom parsing
+        logic as needed.
+        """
+        if not issubclass(cls, RoborockBase):
+            raise NotImplementedError(f"Trait {cls} does not implement RoborockBase")
+        # Subclasses can override to implement custom parsing logic
+        if isinstance(response, list):
+            response = response[0]
+        if not isinstance(response, dict):
+            raise ValueError(f"Unexpected {cls} response format: {response!r}")
+        return cls.from_dict(response)
+
+    def _parse_response(self, response: V1ResponseData) -> RoborockBase:
+        """Parse the response from the device into a a RoborockBase.
+
+        This is used by subclasses that want to override the class
+        behavior with instance-specific data.
+        """
+        return self._parse_type_response(response)
+
+    def __post_init__(self) -> None:
+        """Post-initialization to set up the RPC channel.
+
+        This is called automatically after the dataclass is initialized by the
+        device setup code.
+        """
+        self._rpc_channel = None
+
+    @property
+    def rpc_channel(self) -> V1RpcChannel:
+        """Helper for executing commands, used internally by the trait"""
+        if not self._rpc_channel:
+            raise ValueError("Device trait in invalid state")
+        return self._rpc_channel
+
+    async def refresh(self) -> None:
+        """Refresh the contents of this trait."""
+        response = await self.rpc_channel.send_command(self.command)
+        new_data = self._parse_response(response)
+        if not isinstance(new_data, RoborockBase):
+            raise ValueError(f"Internal error, unexpected response type: {new_data!r}")
+        _LOGGER.debug("Refreshed %s: %s", self.__class__.__name__, new_data)
+        self._update_trait_values(new_data)
+
+    def _update_trait_values(self, new_data: RoborockBase) -> None:
+        """Update the values of this trait from another instance."""
+        for field in fields(new_data):
+            new_value = getattr(new_data, field.name, None)
+            setattr(self, field.name, new_value)
+
+
+def _get_value_field(clazz: type[V1TraitMixin]) -> str:
+    """Get the name of the field marked as the main value of the RoborockValueBase."""
+    value_fields = [field.name for field in fields(clazz) if field.metadata.get("roborock_value", False)]
+    if len(value_fields) != 1:
+        raise ValueError(
+            f"RoborockValueBase subclass {clazz} must have exactly one field marked as roborock_value, "
+            f" but found: {value_fields}"
+        )
+    return value_fields[0]
+
+
+@dataclass(init=False, kw_only=True)
+class RoborockValueBase(V1TraitMixin, RoborockBase):
+    """Base class for traits that represent a single value.
+
+    This class is intended to be subclassed by traits that represent a single
+    value, such as volume or brightness. The subclass should define a single
+    field with the metadata `roborock_value=True` to indicate which field
+    represents the main value of the trait.
+    """
+
+    @classmethod
+    def _parse_response(cls, response: V1ResponseData) -> Self:
+        """Parse the response from the device into a RoborockValueBase."""
+        if isinstance(response, list):
+            response = response[0]
+        if not isinstance(response, int):
+            raise ValueError(f"Unexpected response format: {response!r}")
+        value_field = _get_value_field(cls)
+        return cls(**{value_field: response})
+
+
+class RoborockSwitchBase(ABC):
+    """Base class for traits that represent a boolean switch."""
+
+    @property
+    @abstractmethod
+    def is_on(self) -> bool:
+        """Return whether the switch is on."""
+
+    @abstractmethod
+    async def enable(self) -> None:
+        """Enable the switch."""
+
+    @abstractmethod
+    async def disable(self) -> None:
+        """Disable the switch."""
+
+
+def mqtt_rpc_channel(cls):
+    """Decorator to mark a function as cloud only.
+
+    Normally a trait uses an adaptive rpc channel that can use either local
+    or cloud communication depending on what is available. This will force
+    the trait to always use the cloud rpc channel.
+    """
+
+    def wrapper(*args, **kwargs):
+        return cls(*args, **kwargs)
+
+    cls.mqtt_rpc_channel = True  # type: ignore[attr-defined]
+    return wrapper
+
+
+def map_rpc_channel(cls):
+    """Decorator to mark a function as cloud only using the map rpc format."""
+
+    def wrapper(*args, **kwargs):
+        return cls(*args, **kwargs)
+
+    cls.map_rpc_channel = True  # type: ignore[attr-defined]
+    return wrapper