Skip to content

feat: add Q7 goto position - #1042

Open
ramon-angosto wants to merge 5 commits into
Python-roborock:mainfrom
ramon-angosto:q7/5-goto-position
Open

ramon-angosto wants to merge 5 commits into
Python-roborock:mainfrom
ramon-angosto:q7/5-goto-position

Conversation

@ramon-angosto

Copy link
Copy Markdown

Depends on #1041. Only the last commit belongs to this PR.

Summary

Adds Q7PropertiesApi.goto_position(target: Q7RoborockPoint). This is what Home Assistant needs for vacuum.set_vacuum_goto_position.

The Q7 firmware has no goto command, so, as on the Q10, it is emulated:

  1. A 50 × 50 cm zone-clean task is started around the target.
  2. While the goto is active, the live map is requested every 3 s to track the position. cur_path pushes are used too, but the device does not always stream them.
  3. When the robot is within 30 cm of the target, the zone task is stopped (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 GotoAction class (goto.py), which owns no tasks and sends no commands. It is fed with the position and the work_mode from device pushes:

Situation Action
Zone task running (PLAN_AREA) and near the target Stop the zone task
Zone finished and robot heading home (PLAN_AREA_GO_HOME) before a close position arrived Stop, since it already reached the target
Zone task ended or replaced in any other way Complete without commands
300 s safety timeout with the zone task still running Stop the zone task

A 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 does close().

Testing

  • Unit tests for the state machine and the API integration: stop at the target, already at the target, cancelled by another command.
  • Verified on a Q7 TF+ (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.

@Lash-L Lash-L added Feature New feature Q7 B01 Q7 platform labels Nov 15, 2026

@Lash-L Lash-L left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 (mm with (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) via service.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 GotoAction state machine cleanly decouples state evaluation (WorkModeMapping.PLAN_AREA -> STOP near target or WorkModeMapping.PLAN_AREA_GO_HOME if 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):
      1. Calling goto_position while an existing goto is already near the new target returns early without stopping the active goto's zone-clean task.
      2. If the 300 s safety timeout fires while a STOP command is in flight and that STOP fails, retry() re-evaluates normal arrival logic instead of the timeout branch.
  • Layer 3: Wire Protocols, Codecs & Resilient Enums

    • WorkModeMapping.from_code_optional(work_mode) safely handles unknown integer wire codes without raising ValueError.
  • 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 via FakeQ7Channel.

return

await self.clean_zone(
Q7RoborockPoint(x=target.x - _GOTO_HALF_ZONE_MM, y=target.y - _GOTO_HALF_ZONE_MM),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
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

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
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__)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@Lash-L Lash-L added the /review run Code review skill (/review) has been run label Nov 15, 2026
@Lash-L
Lash-L marked this pull request as draft November 15, 2026 19:57
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.
@ramon-angosto
ramon-angosto marked this pull request as ready for review November 16, 2026 08:07

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Feature New feature Q7 B01 Q7 platform /review run Code review skill (/review) has been run

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants