Repository navigation
feat: add Q7 goto position - #1042
ramon-angosto wants to merge 5 commits into
Conversation
Lash-L
left a comment
There was a problem hiding this comment.
Automated code review by Gemini 4 Argon in Antigravity using our /review (/code-review) skill (.agents/skills/code-review/SKILL.md / AGENTS.md).
Scope & Stacking Note
This PR (q7/5-goto-position) is stacked on top of #1038, #1039, #1040, and #1041 while targeting main. This review focuses specifically on the head commit 1f77ea9e3bf57c37011ba3d1e32a8b21588970aa (feat: add Q7 goto position).
Review Summary by Architectural Layer
-
Layer 1: Public Trait APIs & Consumer Contracts (
roborock/devices/traits/b01/q7/__init__.py)Q7PropertiesApi.goto_position(target: Q7RoborockPoint)exposes a clean, strongly typed consumer contract in common Roborock coordinates (mmwith(25500, 25500)origin).- Using an emulated 50 × 50 cm zone-clean task around
target(_GOTO_HALF_ZONE_MM = 250) stopped within a 30 cm arrival radius (_GOTO_TOLERANCE_MM = 300) viaservice.set_zone_clean(ctrl_value: 0) is the right design for Q7.
-
Layer 2: Data Lifecycle, State & Concurrency (
roborock/devices/traits/b01/q7/goto.py,roborock/devices/traits/b01/q7/__init__.py)- The pure
GotoActionstate machine cleanly decouples state evaluation (WorkModeMapping.PLAN_AREA->STOPnear target orWorkModeMapping.PLAN_AREA_GO_HOMEif the zone finishes first) from async task management and RPC commands. - Teardown in
Q7PropertiesApi.close()and cancellation across other cleaning commands (start_clean,clean_segments,clean_zones,pause_clean,stop_clean,return_to_dock) properly clean up_goto_track_task,_goto_command_task, and listeners. - Two minor lifecycle/state edge cases identified (see inline comments):
- Calling
goto_positionwhile an existing goto is already near the new target returns early without stopping the active goto's zone-clean task. - If the 300 s safety timeout fires while a
STOPcommand is in flight and thatSTOPfails,retry()re-evaluates normal arrival logic instead of the timeout branch.
- Calling
- The pure
-
Layer 3: Wire Protocols, Codecs & Resilient Enums
WorkModeMapping.from_code_optional(work_mode)safely handles unknown integer wire codes without raisingValueError.
-
Tests & Conformance (
tests/devices/traits/b01/q7/test_goto.py)- Well-structured unit and integration tests colocated under the mirror path (
tests/devices/traits/b01/q7/test_goto.py), exercising state transitions and channel interactions viaFakeQ7Channel.
- Well-structured unit and integration tests colocated under the mirror path (
| return | ||
|
|
||
| await self.clean_zone( | ||
| Q7RoborockPoint(x=target.x - _GOTO_HALF_ZONE_MM, y=target.y - _GOTO_HALF_ZONE_MM), |
There was a problem hiding this comment.
Priority 2 (Lifecycle & State Management): Stop an active goto zone task when a new goto_position target is already within tolerance
If a caller invokes goto_position(target_b) while an earlier goto_position(target_a) is still running and the robot happens to be within _GOTO_TOLERANCE_MM of target_b, returning early here leaves the previous goto action and its 50×50 cm zone-clean task around target_a running (driving the robot away from target_b).
On Q10 (VacuumTrait.goto_position), this case cancels the active goto and stops/pauses the owned task before returning. Doing the same here ensures the robot stays at target_b:
| Q7RoborockPoint(x=target.x - _GOTO_HALF_ZONE_MM, y=target.y - _GOTO_HALF_ZONE_MM), | |
| if probe.is_near_target(self.map_content.robot_position): | |
| if self._goto_action is not None: | |
| self.cancel_goto() | |
| await self.send(RoborockB01Q7Methods.SET_ZONE_CLEAN, {"ctrl_value": SCDeviceCleanParam.STOP.code}) | |
| return |
There was a problem hiding this comment.
Done in 54f38a2: if a goto is still active and the new target is already within tolerance, the previous goto is cancelled and its zone task stopped. Covered by test_q7_goto_new_target_already_reached_stops_previous_goto.
| """Stop the zone task if it is still running when the safety timeout expires.""" | ||
| if self._finished or self._command_pending: | ||
| return | ||
| self._latest_snapshot = snapshot |
There was a problem hiding this comment.
Priority 2 (State Management): Preserve timeout state across retry() if a command is already in flight
If timeout() is called while a STOP command is currently in flight (self._command_pending is True) and that command subsequently fails, _async_stop_goto_zone calls action.retry(). Because timeout() returned early at line 76 without recording that the safety timeout expired, retry() falls back to self._evaluate(self._latest_snapshot) instead of the timeout check—so if the robot is still in PLAN_AREA but not near the target, the timed-out zone task will not be stopped on retry.
Tracking self._timeout_requested = True (matching roborock/devices/traits/b01/q10/goto.py) ensures retry() re-evaluates the timeout condition:
| self._latest_snapshot = snapshot | |
| def retry(self) -> None: | |
| """Re-evaluate the latest state after a requested command failed.""" | |
| if self._finished or self._latest_snapshot is None: | |
| return | |
| self._command_pending = False | |
| if self._timeout_requested: | |
| self._evaluate_timeout(self._latest_snapshot) | |
| else: | |
| self._evaluate(self._latest_snapshot) | |
| def timeout(self, snapshot: GotoSnapshot) -> None: | |
| """Stop the zone task if it is still running when the safety timeout expires.""" | |
| if self._finished: | |
| return | |
| self._latest_snapshot = snapshot | |
| self._timeout_requested = True | |
| if self._command_pending: | |
| return | |
| self._evaluate_timeout(snapshot) | |
| def _evaluate_timeout(self, snapshot: GotoSnapshot) -> None: | |
| """Derive the safe timeout command from the latest device state.""" | |
| if self._task_seen and snapshot.work_mode is _ZONE_WORK_MODE: | |
| self._emit(GotoActionCommand.STOP) | |
| else: | |
| self._emit(GotoActionCommand.COMPLETE) |
(along with self._timeout_requested = False in __init__)
There was a problem hiding this comment.
Done in 54f38a2, following the Q10 approach: timeout() records _timeout_requested even while a command is in flight, and retry() re-evaluates the timeout rules in that case. test_goto_action_retry_keeps_timeout fails on the previous code and passes now.
Add `clean_zone` and `clean_zones` to the Q7 properties API. Zones are given as two opposite corners in the common Roborock millimetre coordinate space through a new `Q7RoborockPoint`, which converts to and from the Q7 world coordinates (meters, origin next to the dock). The device expects the zone preference type to be selected first (`service.set_preference_type`), then the zone corners as a flat list (`service.set_zone_points`), and finally `service.set_zone_clean` to start. Several zones are concatenated into a single task.
Add a `RemoteTrait` to the Q7 properties API, mirroring the Q10 remote API. Manual mode is entered with `prop.set sweep_type=5` and the robot is driven with `service.set_direction` (1 forward, 2 left, 3 right, 0 exit). Each command moves the robot for a short burst, so callers repeat it while a direction is held. Leaving remote mode restores `sweep_type=0`.
Add `set_carpet_turbo` and `set_carpet_avoid` to the Q7 properties API. Both are written individually with `prop.set` (`carpet_turbo` / `carpet_avoid`) and reported back nested under `privacy`. Keep the user-visible `name` of each entry returned by `service.get_map_list`, which was previously dropped.
Add `MapContentTrait.robot_position` (common Roborock coordinates) for Q7 devices, kept up to date from two sources: - the current pose in live map frames (`currentPose`), ignoring the `(1100, 1100)` and `(0, 0)` placeholders the firmware reports when the pose is unknown or outside the map; - `cur_path` samples in unsolicited `prop.post` device pushes, which the device streams while a task is running. To receive those pushes, `B01Q7Channel` now implements a `Q7PushChannel` protocol that decodes `*.post` messages into `Q7DevicePush`, and `Q7PropertiesApi.start()` subscribes to them. Add `MapContentTrait.refresh_live()`, which requests the live map by type (`service.upload_by_maptype`). Unlike the saved map it carries the current pose and makes the device stream `cur_path` positions.
Add `Q7PropertiesApi.goto_position`. The Q7 firmware has no goto command, so (like the Q10) it is emulated with a small zone-clean task around the target that is stopped once the live position is within 30 cm, leaving the robot there. A `GotoAction` state machine decides when to stop, based on the robot position and the `work_mode` reported in device pushes: - near the target while the zone task runs: stop the task; - the zone finished and the robot heads home (`PLAN_AREA_GO_HOME`) before a close position arrived: stop, since it already reached the target; - the zone task ended or was replaced any other way: complete silently. While a goto is active the live map is requested every 3 s, because `cur_path` pushes are not always streamed. A 300 s safety timeout stops a zone task that is still running. Any other cleaning command cancels the goto.
1f77ea9 to
54f38a2
Compare
Summary
Adds
Q7PropertiesApi.goto_position(target: Q7RoborockPoint). This is what Home Assistant needs forvacuum.set_vacuum_goto_position.The Q7 firmware has no goto command, so, as on the Q10, it is emulated:
cur_pathpushes are used too, but the device does not always stream them.set_zone_clean ctrl_value 0) and the robot stays there.If the robot is already within 30 cm of the target, nothing is sent.
State machine
The decisions live in a pure
GotoActionclass (goto.py), which owns no tasks and sends no commands. It is fed with the position and thework_modefrom device pushes:PLAN_AREA) and near the targetPLAN_AREA_GO_HOME) before a close position arrivedA failed stop is retried. Any other cleaning command (
start_clean,clean_segments,clean_zones,pause_clean,stop_clean,return_to_dock) cancels the goto, and so doesclose().Testing
roborock.vacuum.sc05, firmware 03.01.80). Two runs ended 15 cm and 12 cm from the target. The second run went through the "zone finished, heading home" path. In both, the robot stayed idle at the target.