feat: add a sound volume trait (#477)

* feat: Add volume trait

* feat: Add volume trait

* chore: remove duplicate api_error from bad merge

* chore: fix imports

Author: allenporter

roborock/cli.py

@@ -382,7 +382,7 @@ async def execute_scene(ctx, scene_id):
 @click.pass_context
 @async_command
 async def status(ctx, device_id: str):
-    """Get device status - unified implementation for both modes."""
+    """Get device status."""
     context: RoborockContext = ctx.obj
 
     device_manager = await context.get_device_manager()
@@ -414,6 +414,46 @@ async def clean_summary(ctx, device_id: str):
     click.echo(dump_json(clean_summary_result.as_dict()))
 
 
+@session.command()
+@click.option("--device_id", required=True)
+@click.pass_context
+@async_command
+async def volume(ctx, device_id: str):
+    """Get device volume."""
+    context: RoborockContext = ctx.obj
+
+    device_manager = await context.get_device_manager()
+    device = await device_manager.get_device(device_id)
+
+    if not (volume_trait := device.traits.get("sound_volume")):
+        click.echo(f"Device {device.name} does not have a volume trait")
+        return
+
+    volume_result = await volume_trait.get_volume()
+    click.echo(f"Device {device_id} volume:")
+    click.echo(volume_result)
+
+
+@session.command()
+@click.option("--device_id", required=True)
+@click.option("--volume", required=True, type=int)
+@click.pass_context
+@async_command
+async def set_volume(ctx, device_id: str, volume: int):
+    """Set the devicevolume."""
+    context: RoborockContext = ctx.obj
+
+    device_manager = await context.get_device_manager()
+    device = await device_manager.get_device(device_id)
+
+    if not (volume_trait := device.traits.get("sound_volume")):
+        click.echo(f"Device {device.name} does not have a volume trait")
+        return
+
+    await volume_trait.set_volume(volume)
+    click.echo(f"Set Device {device_id} volume to {volume}")
+
+
 @click.command()
 @click.option("--device_id", required=True)
 @click.option("--cmd", required=True)
@@ -653,6 +693,8 @@ def write_markdown_table(product_features: dict[str, dict[str, any]], all_featur
 cli.add_command(get_device_info)
 cli.add_command(update_docs)
 cli.add_command(clean_summary)
+cli.add_command(volume)
+cli.add_command(set_volume)
 
 
 def main():

roborock/devices/device_manager.py

@@ -25,6 +25,7 @@
 from .traits.clean_summary import CleanSummaryTrait
 from .traits.dnd import DoNotDisturbTrait
 from .traits.dyad import DyadApi
+from .traits.sound_volume import SoundVolumeTrait
 from .traits.status import StatusTrait
 from .traits.trait import Trait
 from .traits.zeo import ZeoApi
@@ -156,6 +157,7 @@ def device_creator(device: HomeDataDevice, product: HomeDataProduct) -> Roborock
                 traits.append(StatusTrait(product, channel.rpc_channel))
                 traits.append(DoNotDisturbTrait(channel.rpc_channel))
                 traits.append(CleanSummaryTrait(channel.rpc_channel))
+                traits.append(SoundVolumeTrait(channel.rpc_channel))
             case DeviceVersion.A01:
                 mqtt_channel = create_mqtt_channel(user_data, mqtt_params, mqtt_session, device)
                 match product.category:

roborock/devices/traits/sound_volume.py

@@ -0,0 +1,31 @@
+"""Module for controlling the sound volume of Roborock devices."""
+
+from roborock.devices.traits.trait import Trait
+from roborock.devices.v1_rpc_channel import V1RpcChannel
+from roborock.exceptions import RoborockException
+from roborock.roborock_typing import RoborockCommand
+
+__all__ = [
+    "SoundVolumeTrait",
+]
+
+
+class SoundVolumeTrait(Trait):
+    """Trait for controlling the sound volume of a Roborock device."""
+
+    name = "sound_volume"
+
+    def __init__(self, rpc_channel: V1RpcChannel) -> None:
+        """Initialize the SoundVolumeTrait."""
+        self._rpc_channel = rpc_channel
+
+    async def get_volume(self) -> int:
+        """Get the current sound volume of the device."""
+        response = await self._rpc_channel.send_command(RoborockCommand.GET_SOUND_VOLUME)
+        if not isinstance(response, list) or not response:
+            raise RoborockException(f"Unexpected volume format: {response!r}")
+        return int(response[0])
+
+    async def set_volume(self, volume: int) -> None:
+        """Set the sound volume of the device."""
+        await self._rpc_channel.send_command(RoborockCommand.CHANGE_SOUND_VOLUME, params=[volume])

roborock/devices/v1_rpc_channel.py

@@ -149,7 +149,10 @@ def find_response(response_message: RoborockMessage) -> None:
                 return
             _LOGGER.debug("Received response (request_id=%s): %s", self._name, decoded.request_id)
             if decoded.request_id == request_message.request_id:
-                future.set_result(decoded.data)
+                if decoded.api_error:
+                    future.set_exception(decoded.api_error)
+                else:
+                    future.set_result(decoded.data)
 
         unsub = await self._channel.subscribe(find_response)
         try:

roborock/protocols/v1_protocol.py

@@ -108,9 +108,18 @@ class ResponseMessage:
     data: ResponseData
     """The data of the response, where the type depends on the command."""
 
+    api_error: RoborockException | None = None
+    """The API error message of the response if any."""
+
 
 def decode_rpc_response(message: RoborockMessage) -> ResponseMessage:
-    """Decode a V1 RPC_RESPONSE message."""
+    """Decode a V1 RPC_RESPONSE message.
+
+    This will raise a RoborockException if the message cannot be parsed. A
+    response object will be returned even if there is an error in the
+    response, as long as we can extract the request ID. This is so we can
+    associate an API response with a request even if there was an error.
+    """
     if not message.payload:
         return ResponseMessage(request_id=message.seq, data={})
     try:
@@ -136,19 +145,26 @@ def decode_rpc_response(message: RoborockMessage) -> ResponseMessage:
         ) from e
 
     request_id: int | None = data_point_response.get("id")
+    exc: RoborockException | None = None
     if error := data_point_response.get("error"):
-        raise RoborockException(f"Error in message: {error}")
-
+        exc = RoborockException(error)
     if not (result := data_point_response.get("result")):
-        raise RoborockException(f"Invalid V1 message format: missing 'result' in data point for {message.payload!r}")
-    _LOGGER.debug("Decoded V1 message result: %s", result)
-    if isinstance(result, str) and result == "ok":
-        result = {}
-    if not isinstance(result, (dict, list, int)):
-        raise RoborockException(
-            f"Invalid V1 message format: 'result' was unexpected type {type(result)}. {message.payload!r}"
-        )
-    return ResponseMessage(request_id=request_id, data=result)
+        exc = RoborockException(f"Invalid V1 message format: missing 'result' in data point for {message.payload!r}")
+    else:
+        _LOGGER.debug("Decoded V1 message result: %s", result)
+        if isinstance(result, str):
+            if result == "unknown_method":
+                exc = RoborockException("The method called is not recognized by the device.")
+            elif result != "ok":
+                exc = RoborockException(f"Unexpected API Result: {result}")
+            result = {}
+        if not isinstance(result, (dict, list, int)):
+            raise RoborockException(
+                f"Invalid V1 message format: 'result' was unexpected type {type(result)}. {message.payload!r}"
+            )
+    if not request_id and exc:
+        raise exc
+    return ResponseMessage(request_id=request_id, data=result, api_error=exc)
 
 
 @dataclass

tests/protocols/__snapshots__/test_v1_protocol.ambr

@@ -84,3 +84,13 @@
   ]
   '''
 # ---
+# name: test_decode_rpc_payload[get_volume]
+  20001
+# ---
+# name: test_decode_rpc_payload[get_volume].1
+  '''
+  [
+    90
+  ]
+  '''
+# ---

tests/protocols/test_v1_protocol.py

@@ -227,3 +227,50 @@ def test_create_map_response_decoder_invalid_payload():
 
     with pytest.raises(RoborockException, match="Invalid V1 map response format: missing payload"):
         decoder(message)
+
+
+@pytest.mark.parametrize(
+    ("payload", "expected_data", "expected_error"),
+    [
+        (
+            b'{"t":1757883536,"dps":{"102":"{\\"id\\":20001,\\"result\\":\\"unknown_method\\"}"}}',
+            {},
+            "The method called is not recognized by the device.",
+        ),
+        (
+            b'{"t":1757883536,"dps":{"102":"{\\"id\\":20001,\\"result\\":\\"other\\"}"}}',
+            {},
+            "Unexpected API Result",
+        ),
+    ],
+)
+def test_decode_result_with_error(payload: bytes, expected_data: dict[str, str], expected_error: str) -> None:
+    """Test decoding a v1 RPC response protocol message."""
+    # The values other than the payload are arbitrary
+    message = RoborockMessage(
+        protocol=RoborockMessageProtocol.GENERAL_RESPONSE,
+        payload=payload,
+        seq=12750,
+        version=b"1.0",
+        random=97431,
+        timestamp=1652547161,
+    )
+    decoded_message = decode_rpc_response(message)
+    assert decoded_message.request_id == 20001
+    assert decoded_message.data == expected_data
+    assert decoded_message.api_error
+    assert expected_error in str(decoded_message.api_error)
+
+
+def test_decode_no_request_id():
+    """Test map response decoder without a request id is raised as an exception."""
+    message = RoborockMessage(
+        protocol=RoborockMessageProtocol.GENERAL_RESPONSE,
+        payload=b'{"t":1757883536,"dps":{"102":"{\\"result\\":\\"unknown_method\\"}"}}',
+        seq=12750,
+        version=b"1.0",
+        random=97431,
+        timestamp=1652547161,
+    )
+    with pytest.raises(RoborockException, match="The method called is not recognized by the device"):
+        decode_rpc_response(message)

tests/protocols/testdata/v1_protocol/get_volume.json

@@ -0,0 +1 @@
+{"t":1757903261,"dps":{"102":"{\"id\":20001,\"result\":[90]}"}}