Skip to content

Commit febdc69

Browse files
committed
feat(camera): expose V1 camera signaling commands
1 parent ed5f859 commit febdc69

9 files changed

Lines changed: 468 additions & 9 deletions

File tree

‎docs/CAMERA_PROTOCOL.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,51 @@ Camera viewing is protected by a separate PIN / pattern lock configured in the m
129129

130130
## Commands Reference
131131

132+
### Library command interface
133+
134+
Camera-equipped V1 vacuums expose `device.v1_properties.camera` after feature
135+
discovery, gated by `is_video_monitor_supported`. It is `None` on unsupported
136+
devices. The device manager also restricts V1 traits to V1 vacuum products.
137+
138+
`CameraTrait` sends preview control, quality selection, TURN requests, SDP/ICE
139+
exchange, and voice chat control through the existing cloud MQTT channel.
140+
Cloud connectivity is required even when the robot is reachable locally.
141+
PIN hashes and WebRTC signaling therefore pass through Roborock's cloud.
142+
A single channel strategy prevents a PIN attempt that fails or times out on
143+
one connection from being sent again through local/cloud fallback.
144+
145+
It adds no WebRTC dependency and does not open a media connection. Callers
146+
provide PIN/pattern digits, not a precomputed hash. Use a unique caller-owned
147+
`client_id` for the session, and close any other viewer first.
148+
149+
```python
150+
from contextlib import suppress
151+
152+
from roborock.exceptions import RoborockException
153+
154+
camera = device.v1_properties.camera
155+
if camera is not None:
156+
await camera.start_preview(client_id="my-viewer", password=camera_pin)
157+
try:
158+
turn_server = await camera.get_turn_server()
159+
# Create a WebRTC peer using turn_server, then exchange SDP and ICE.
160+
# get_sdp_answer() returns None for "retry"; bound polling in the caller.
161+
finally:
162+
# Best-effort cleanup must not mask an earlier signaling failure.
163+
with suppress(RoborockException):
164+
await camera.stop_preview()
165+
```
166+
167+
`stop_preview()` is not scoped to a client ID. Call it after a successful
168+
start, rather than automatically stopping after an explicit start rejection.
169+
If starting times out, the robot may already have activated the camera;
170+
the caller must decide how to reconcile or clean up that ambiguous session.
171+
172+
The caller owns polling deadlines, ICE deduplication and session teardown.
173+
If voice chat is started, stop it before stopping preview. No polling tasks,
174+
listeners, media objects or session credentials are retained by the trait.
175+
The streaming/session manager is a separate layer to be added later.
176+
132177
See also [V1_API_COMMANDS.md](V1_API_COMMANDS.md) for general V1 device RPC references.
133178

134179
> [!NOTE]

‎roborock/callbacks.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,10 +121,11 @@ def decoder_callback(
121121

122122
def wrapper(data: K) -> None:
123123
if not (messages := decoder(data)):
124-
logger.debug("Failed to decode message: %s", data)
124+
logger.debug("Failed to decode message of type %s", type(data).__name__)
125125
return
126126
for message in messages:
127-
logger.debug("Decoded message: %s", message)
127+
# Decrypted payloads can contain credentials; log only their shape.
128+
logger.debug("Decoded message of type %s", type(message).__name__)
128129
safe_cb(message)
129130

130131
return wrapper

‎roborock/devices/rpc/v1_channel.py‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,12 @@
4747

4848
_T = TypeVar("_T", bound=RoborockBase)
4949
_TIMEOUT = 10.0
50+
_SENSITIVE_CAMERA_COMMANDS = {
51+
RoborockCommand.CHECK_HOMESEC_PASSWORD,
52+
RoborockCommand.START_CAMERA_PREVIEW,
53+
RoborockCommand.SEND_SDP_TO_ROBOT,
54+
RoborockCommand.SEND_ICE_TO_ROBOT,
55+
}
5056

5157

5258
# Exponential backoff parameters for reconnecting to local
@@ -126,7 +132,7 @@ async def _send_rpc(
126132
strategy.name,
127133
request.request_id,
128134
request.method,
129-
request.params,
135+
"<redacted>" if request.method in _SENSITIVE_CAMERA_COMMANDS else request.params,
130136
)
131137

132138
message = strategy.encoder(request)
@@ -135,7 +141,7 @@ def find_response(response_message: RoborockMessage) -> None:
135141
try:
136142
decoded = strategy.decoder(response_message)
137143
except RoborockException as ex:
138-
logger.debug("Exception while decoding message (%s): %s", response_message, ex)
144+
logger.debug("Exception while decoding message (seq=%s): %s", response_message.seq, type(ex).__name__)
139145
return
140146
if decoded is None:
141147
return
@@ -530,21 +536,21 @@ def _should_use_cache(self, local_connect_failures: int) -> bool:
530536

531537
def _on_mqtt_message(self, message: RoborockMessage) -> None:
532538
"""Handle incoming MQTT messages."""
533-
self._logger.debug("V1Channel received MQTT message: %s", message)
539+
self._logger.debug("V1Channel received MQTT message (seq=%s, protocol=%s)", message.seq, message.protocol)
534540
if self._callback:
535541
self._callback(message)
536542
try:
537543
datapoints = decode_data_protocol_message(message)
538544
except RoborockException as e:
539-
self._logger.debug("Error decoding data protocol message: %s", e)
545+
self._logger.debug("Error decoding data protocol message: %s", type(e).__name__)
540546
return
541547

542548
if datapoints:
543549
self._dps_listeners(datapoints)
544550

545551
def _on_local_message(self, message: RoborockMessage) -> None:
546552
"""Handle incoming local messages."""
547-
self._logger.debug("V1Channel received local message: %s", message)
553+
self._logger.debug("V1Channel received local message (seq=%s, protocol=%s)", message.seq, message.protocol)
548554
if self._callback:
549555
self._callback(message)
550556

‎roborock/devices/traits/v1/__init__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@
6969
from roborock.web_api import UserWebApiClient
7070

7171
from . import (
72+
camera,
7273
child_lock,
7374
clean_summary,
7475
command,
@@ -94,6 +95,7 @@
9495
volume,
9596
wash_towel_mode,
9697
)
98+
from .camera import CameraTrait
9799
from .child_lock import ChildLockTrait
98100
from .clean_summary import CleanSummaryTrait
99101
from .command import CommandTrait
@@ -123,6 +125,7 @@
123125

124126
__all__ = [
125127
"PropertiesApi",
128+
"camera",
126129
"child_lock",
127130
"clean_summary",
128131
"command",
@@ -173,6 +176,7 @@ class PropertiesApi(Trait):
173176
routines: RoutinesTrait
174177

175178
# Optional features that may not be supported on all devices
179+
camera: CameraTrait | None = None
176180
child_lock: ChildLockTrait | None = None
177181
led_status: LedStatusTrait | None = None
178182
flow_led_status: FlowLedStatusTrait | None = None
Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
"""Camera control and WebRTC signaling through the existing V1 RPC channel."""
2+
3+
from roborock.data.camera import CameraIceCandidate, CameraQuality, CameraSdpDescription, CameraTurnServer
4+
from roborock.exceptions import RoborockException, RoborockParsingException
5+
from roborock.protocols.camera_signaling import (
6+
decode_ice_candidates,
7+
decode_sdp_answer,
8+
encode_ice_candidate,
9+
encode_sdp_offer,
10+
hash_camera_password,
11+
)
12+
from roborock.protocols.v1_protocol import ParamsType, V1RpcChannel
13+
from roborock.roborock_typing import RoborockCommand
14+
15+
16+
class CameraTrait:
17+
"""Control a camera session without owning a WebRTC connection.
18+
19+
Callers own session ordering, bounded SDP/ICE polling and cleanup: pair
20+
a successful ``start_preview`` with ``stop_preview`` in a ``finally`` block, and stop
21+
voice chat if started. This trait creates no tasks, listeners or sockets.
22+
Only one viewer can use the robot's camera at a time.
23+
"""
24+
25+
requires_feature = "is_video_monitor_supported"
26+
# Use one existing channel strategy so a rejected PIN is not retried via
27+
# local/cloud fallback. Local camera signaling can be exposed separately.
28+
mqtt_rpc_channel = True
29+
30+
def __init__(self) -> None:
31+
"""Initialize the trait; device discovery supplies its RPC channel."""
32+
self._rpc_channel: V1RpcChannel | None = None
33+
34+
@property
35+
def rpc_channel(self) -> V1RpcChannel:
36+
"""Return the channel supplied by the device."""
37+
if self._rpc_channel is None:
38+
raise RoborockException("Camera trait has no RPC channel")
39+
return self._rpc_channel
40+
41+
async def check_password(self, password: str) -> None:
42+
"""Check PIN/pattern digits, raising if rejected; never retry a bad PIN."""
43+
await self._send_ack(RoborockCommand.CHECK_HOMESEC_PASSWORD, {"password": hash_camera_password(password)})
44+
45+
async def start_preview(self, client_id: str, password: str, quality: CameraQuality = CameraQuality.HD) -> None:
46+
"""Start preview using PIN/pattern digits and a caller-owned session ID."""
47+
if not client_id.strip():
48+
raise ValueError("Camera client ID cannot be empty")
49+
await self._send_ack(
50+
RoborockCommand.START_CAMERA_PREVIEW,
51+
{"client_id": client_id, "quality": quality.value, "password": hash_camera_password(password)},
52+
)
53+
54+
async def stop_preview(self) -> None:
55+
"""Stop the active preview; the command is not scoped to a client ID."""
56+
await self._send_ack(RoborockCommand.STOP_CAMERA_PREVIEW)
57+
58+
async def set_quality(self, quality: CameraQuality) -> None:
59+
"""Switch the active preview's video quality."""
60+
await self._send_ack(RoborockCommand.SWITCH_VIDEO_QUALITY, {"quality": quality.value})
61+
62+
async def get_turn_server(self) -> CameraTurnServer:
63+
"""Fetch ephemeral TURN credentials without retaining them on the trait."""
64+
response = await self.rpc_channel.send_command(RoborockCommand.GET_TURN_SERVER)
65+
try:
66+
if not isinstance(response, dict | list):
67+
raise TypeError("Expected a TURN response object or list")
68+
return CameraTurnServer.from_dict(response)
69+
except (TypeError, ValueError):
70+
# TURN parser errors may include credentials or URLs supplied by firmware.
71+
raise RoborockParsingException(
72+
trait_name=type(self).__name__,
73+
command=RoborockCommand.GET_TURN_SERVER,
74+
payload={"type": type(response).__name__},
75+
inner_error="Invalid TURN server response",
76+
) from None
77+
78+
async def send_sdp_offer(self, sdp: str) -> None:
79+
"""Send an SDP offer, preserving its line endings."""
80+
await self._send_ack(RoborockCommand.SEND_SDP_TO_ROBOT, {"app_sdp": encode_sdp_offer(sdp)})
81+
82+
async def get_sdp_answer(self) -> CameraSdpDescription | None:
83+
"""Fetch once; return None while the robot reports ``retry``."""
84+
response = await self.rpc_channel.send_command(RoborockCommand.GET_DEVICE_SDP)
85+
if not isinstance(response, str | dict | list):
86+
raise RoborockParsingException(
87+
trait_name=type(self).__name__,
88+
command=RoborockCommand.GET_DEVICE_SDP,
89+
payload={"type": type(response).__name__},
90+
inner_error="Expected an SDP response object, list or string",
91+
)
92+
return decode_sdp_answer(response)
93+
94+
async def send_ice_candidate(self, candidate: CameraIceCandidate) -> None:
95+
"""Send one local ICE candidate, including its media identifiers."""
96+
await self._send_ack(RoborockCommand.SEND_ICE_TO_ROBOT, {"app_ice": encode_ice_candidate(candidate)})
97+
98+
async def get_ice_candidates(self) -> list[CameraIceCandidate]:
99+
"""Fetch remote ICE candidates once; the caller handles deduplication."""
100+
response = await self.rpc_channel.send_command(RoborockCommand.GET_DEVICE_ICE)
101+
if not isinstance(response, str | dict | list):
102+
raise RoborockParsingException(
103+
trait_name=type(self).__name__,
104+
command=RoborockCommand.GET_DEVICE_ICE,
105+
payload={"type": type(response).__name__},
106+
inner_error="Expected an ICE response object, list or string",
107+
)
108+
return decode_ice_candidates(response)
109+
110+
async def start_voice_chat(self) -> None:
111+
"""Enable the robot's microphone for the active WebRTC session."""
112+
await self._send_ack(RoborockCommand.START_VOICE_CHAT)
113+
114+
async def stop_voice_chat(self) -> None:
115+
"""Stop voice chat for the active session."""
116+
await self._send_ack(RoborockCommand.STOP_VOICE_CHAT)
117+
118+
async def _send_ack(self, command: RoborockCommand, params: ParamsType = None) -> None:
119+
response = await self.rpc_channel.send_command(command, params=params)
120+
# decode_rpc_response normalizes a bare "ok" to {}; other firmware
121+
# sends ["ok"]. Do not treat arbitrary result dictionaries as success.
122+
if response not in ({}, ["ok"]):
123+
raise RoborockException(f"Camera command {command.value} was not accepted")

‎roborock/protocols/v1_protocol.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,8 @@ def decode_rpc_response(message: RoborockMessage) -> ResponseMessage:
207207
)
208208
result = {}
209209
else:
210-
_LOGGER.debug("Decoded V1 message result: %s", result)
210+
# Camera results may contain TURN passwords or SDP/ICE credentials.
211+
_LOGGER.debug("Decoded V1 message result type: %s", type(result).__name__)
211212
if isinstance(result, str):
212213
if result == "unknown_method":
213214
api_error = RoborockUnsupportedFeature("The method called is not recognized by the device.")

‎tests/devices/rpc/test_v1_channel.py‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -840,3 +840,85 @@ async def test_v1_channel_subscribe_failure_is_atomic(
840840
mock_mqtt_channel.notify_subscribers(TEST_RESPONSE)
841841
callback.assert_called_once_with(TEST_RESPONSE)
842842
unsub()
843+
844+
845+
@pytest.mark.parametrize(
846+
("method", "params", "result", "secret"),
847+
[
848+
(RoborockCommand.CHECK_HOMESEC_PASSWORD, {"password": "secret-pin-hash"}, ["ok"], "secret-pin-hash"),
849+
(
850+
RoborockCommand.START_CAMERA_PREVIEW,
851+
{"password": "secret-preview-hash", "quality": "HD", "client_id": "viewer"},
852+
["ok"],
853+
"secret-preview-hash",
854+
),
855+
(RoborockCommand.SEND_SDP_TO_ROBOT, {"app_sdp": "secret-encoded-sdp"}, ["ok"], "secret-encoded-sdp"),
856+
(RoborockCommand.SEND_ICE_TO_ROBOT, {"app_ice": "secret-encoded-ice"}, ["ok"], "secret-encoded-ice"),
857+
(RoborockCommand.GET_TURN_SERVER, None, [{"url": "turn:example", "pwd": "secret-turn"}], "secret-turn"),
858+
],
859+
)
860+
async def test_camera_rpc_debug_logs_do_not_expose_secrets(
861+
v1_channel: V1Channel,
862+
mqtt_rpc_channel: V1RpcChannel,
863+
mock_mqtt_channel: FakeChannel,
864+
caplog: pytest.LogCaptureFixture,
865+
method: RoborockCommand,
866+
params: dict[str, str] | None,
867+
result: list,
868+
secret: str,
869+
) -> None:
870+
"""Actual channel routing preserves wire values while excluding them from debug output."""
871+
caplog.set_level(logging.DEBUG)
872+
mock_mqtt_channel.response_queue.append(TEST_NETWORK_INFO_RESPONSE)
873+
unsubscribe = await v1_channel.subscribe(Mock())
874+
try:
875+
caplog.clear()
876+
mock_mqtt_channel.response_queue.append(
877+
RoborockMessage(
878+
protocol=RoborockMessageProtocol.RPC_RESPONSE,
879+
payload=json.dumps({"dps": {"102": json.dumps({"id": 12346, "result": result})}}).encode(),
880+
)
881+
)
882+
assert await mqtt_rpc_channel.send_command(method, params=params) == result
883+
assert secret not in caplog.text
884+
assert "request_id=12346" in caplog.text
885+
request = mock_mqtt_channel.published_messages[-1]
886+
assert request.payload is not None
887+
encoded = json.loads(json.loads(request.payload)["dps"]["101"])
888+
assert encoded["params"] == (params if params is not None else [])
889+
finally:
890+
unsubscribe()
891+
892+
893+
async def test_camera_decode_failure_does_not_log_payload(
894+
v1_channel: V1Channel,
895+
mqtt_rpc_channel: V1RpcChannel,
896+
mock_mqtt_channel: FakeChannel,
897+
caplog: pytest.LogCaptureFixture,
898+
) -> None:
899+
"""A decoder exception containing raw JSON must not expose it through channel logs."""
900+
caplog.set_level(logging.DEBUG)
901+
mock_mqtt_channel.response_queue.append(TEST_NETWORK_INFO_RESPONSE)
902+
unsubscribe = await v1_channel.subscribe(Mock())
903+
secret = "secret-malformed-camera-response"
904+
905+
async def reply(message: RoborockMessage) -> None:
906+
malformed = {"id": 12346, "result": 1.5, "extra": secret}
907+
mock_mqtt_channel.notify_subscribers(
908+
RoborockMessage(
909+
protocol=RoborockMessageProtocol.RPC_RESPONSE,
910+
payload=json.dumps({"dps": {"102": json.dumps(malformed)}}).encode(),
911+
)
912+
)
913+
mock_mqtt_channel.notify_subscribers(TEST_RESPONSE)
914+
915+
mock_mqtt_channel.publish_handler = reply
916+
try:
917+
caplog.clear()
918+
assert await mqtt_rpc_channel.send_command(RoborockCommand.GET_TURN_SERVER) == {
919+
"state": RoborockStateCode.cleaning
920+
}
921+
assert "Exception while decoding message" in caplog.text
922+
assert secret not in caplog.text
923+
finally:
924+
unsubscribe()

0 commit comments

Comments
 (0)