Skip to content

Add server-side scheduling that runs jobs the way the cloud does - #179

Open
virtitnerd wants to merge 9 commits into
Python-roborock:mainfrom
virtitnerd:feat/schedule-store
Open

virtitnerd wants to merge 9 commits into
Python-roborock:mainfrom
virtitnerd:feat/schedule-store

Conversation

@virtitnerd

@virtitnerd virtitnerd commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Roborock schedules are run by the cloud: the official app writes each one as a job (/user/devices/{duid}/jobs) and the cloud starts the clean when it is due. Against this server those calls had nowhere to go, so clients like LocalRock saw no schedules, could never create one, and a schedule made in the official app never ran. This covers both the legacy get/set/upd/del_timer robots and robots on the newer server_timer protocol.

Changes

  • A schedule store per device (cron, enabled state, vac/mop settings), persisted in the existing inventory, with an HTTP API to create, update and delete schedules (the official app's /jobs calls).
  • get/set/upd/del_timer answered from that store instead of being forwarded. Editing merges settings rather than resetting them; an empty action object leaves existing settings alone. One-time schedules (day and month pinned, e.g. 15 23 18 10 *) are listed with their date, the form the robot and the official app use. A settings entry's name, the official app's link to the robot-side timer, is kept so a client can find that timer to edit or delete it.
  • A cron runner that evaluates each device's schedules against its own timezone and starts the clean when one is due, through the existing routine runner (extended to start without a saved scene).
  • How a schedule is started. A job that carries a robot-side timer id (name) is run the way the cloud runs it: the robot is sent server_scheduled_start with the job's settings entry. The robot accepts it for room and whole-home schedules, and for a room schedule it records the clean as "Schedules" in its history. A job without a timer id (one saved through legacy set_timer), or one the robot refuses, falls back to the plainer ways, which is safe because a refused command changes nothing: a whole-home clean is one app_start carrying the schedule's fields plus source: 3 (which the robot also records as "Schedules"), and a room schedule is the settings commands followed by a segment clean. Scenes and routines are untouched; the new step types are produced only by schedules.

Deliberately out of scope

get/set/upd/del_server_timer are not answered from the store. They are forwarded to the robot, which keeps those entries and from which the official app reads them back. Answering them locally, which I tried and reverted during development, hid the robot's real schedules from every client, and the official app then deleted the entries it no longer recognized. A parametrized test guards that this stays so. What runs a server_timer schedule here is its /jobs record, which the runner fires like any other job.

How the start was found

The robot does not run a server_timer entry by itself: with the runner told to skip those jobs, four scheduled times passed with the robot idle. So the server has to start them. Starting a clean with the settings commands and an empty app_start works but the robot records it as started by "App". Sending server_scheduled_start (the method name inside the job) with only the job's settings is refused with -10005 "Invalid timer", and with a bare id with "Param should be name + fan + segment"; with the job's whole settings entry including name it runs (a room schedule's history reads "Schedules | Rooms"). Separately, app_start takes a source field and source: 3 is recorded as "Schedules" (other spellings tried, such as start_type, are ignored).

Related

#88 is the same territory; I held this back for a bit specifically to avoid stepping on that work. Happy to coordinate however's easiest, this doesn't need to be the one that lands if yours is further along, consider it an alternative or reference rather than a race.

Tested

pytest: 458 passed. Verified live on a Roborock Qrevo. End to end: a one-time whole-home schedule created from LocalRock was run by the server at its scheduled minute with exactly one command, server_scheduled_start carrying the job's settings entry, which the robot answered ok; the robot's history shows it as "Schedules | Full". Commands sent to the robot directly: server_scheduled_start for a room schedule (history: "Schedules | Rooms"), and app_start with source: 3 (history: "Schedules | Full"). The fallback paths are covered by unit tests against a fake robot that answers -10005.

@virtitnerd
virtitnerd marked this pull request as draft October 18, 2026 03:05
@virtitnerd
virtitnerd marked this pull request as ready for review October 18, 2026 13:21
@virtitnerd
virtitnerd marked this pull request as draft October 18, 2026 14:08
@virtitnerd
virtitnerd force-pushed the feat/schedule-store branch 2 times, most recently from 297fc12 to 59bf2e6 Compare October 18, 2026 17:13
@virtitnerd virtitnerd changed the title Add server-side scheduling for cloud-managed (legacy set_timer) robots Add server-side scheduling that runs jobs the way the cloud does Oct 18, 2026
@virtitnerd
virtitnerd marked this pull request as ready for review October 18, 2026 17:30
@Lash-L Lash-L self-assigned this Oct 22, 2026
@virtitnerd

Copy link
Copy Markdown
Contributor Author

A status note, in case it helps with review: this PR is still mergeable and clean against main after today's commits, and I have not needed to change it since the last push.

Other work now builds on it, so it is the piece the rest is waiting for:

If it is easier to review in pieces, I can split it: the store and its API first, then the executor that fires jobs. Just say which you would prefer, or point me at anything you want changed first.

@C9H13NO3-dev

Copy link
Copy Markdown

Test report: S6 MaxV (roborock.vacuum.a10, firmware 02.62.46) on top of main @ 02a1770, PR head ce54133. The full test suite passes (582 passed).

Before this PR (on main)

  • LocalRock's set_timer ([[id, ["on", [cron, ["start_clean", {}]]]]]) is forwarded to the robot. The robot rejects it with -10005 "Timer format error: data should be json".
  • The robot does accept the legacy layout [[id, [cron, ["start_clean", {"segments":"","fan_power":102,"water_box_mode":202,"repeat":1}]]]]. It turns it into a server timer (get_server_timer → ["Y <id> 1 1 <cron> app_start", 0]) and leaves get_timer empty.
  • Confirms what you found: the robot does not run that entry itself. I set a timer for 2 minutes ahead in the robot's timezone (get_timezone → Europe/Berlin). The robot stayed docked, sent nothing to the server at the due minute, and the server sent it nothing.
  • Side note for the native sync: upd_server_timer only accepts [[<full "Y …" entry string>, "on"|"off"]] here. After that, the entry shows as ["Y …", "off", 0]. del_server_timer also needs the full entry string. A bare id returns ok but changes nothing.

With this PR

  • The same LocalRock set_timer payload is answered locally (['ok']), and get_timer over MQTT lists it.
  • At the due minute the runner logged Schedule … fired: started and sent app_start [{repeat:1, segments:"0", clean_mop:1, map_index:-1, source:3}]. The robot went to state 5 (cleaning) right away. ✅
  • del_timer removes the job from the store.

One rough edge: right after a container restart, native_schedule_sync.refresh logs Could not save native schedule reconciliation with a CancelledError traceback. That's because the robot hasn't reconnected over MQTT yet, so get_server_timer times out. Later polls succeed. It might be worth skipping or retrying quietly until the device's rr/d topic is known.

@virtitnerd

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough test. I fixed the restart traceback: a timed-out MQTT read was being caught by the save-failure handler because TimeoutError is an OSError, so it now logs quietly at debug level and only real save failures warn. I'm leaving the full-entry timer format as an observation for now, since the sync only replays what the app sent.

virtitnerd added a commit to virtitnerd/local_roborock_server that referenced this pull request Nov 14, 2026
The map backup and capabilities probes reach the robot through the routine
runner's get_routine_runner(), which comes with the schedule store (Python-roborock#179).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Lash-L Lash-L added area: routines Routines, scenes, schedules and cleaning execution. feature PR adding capability; under this two-type scheme also covers additive documentation. labels Nov 15, 2026
@Lash-L

Lash-L commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

@C9H13NO3-dev I appreciate you testing out this PR!

@virtitnerd - this PR has conflicts now, can you fix?

virtitnerd and others added 5 commits November 15, 2026 16:13
Split _run_scene so a scheduled job can run the same step executor
without syncing scene IDs to the robot, and add start_job(), which
refuses to interrupt a routine that is already running on the device.
get_routine_runner() gives other callers the per-context instance.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
(cherry picked from commit c657648)
Roborock's cloud fires server_scheduled_start jobs at nextFireTime. With
the vacuum pointed at this server nothing did, so imported schedules
never ran. ScheduleRunner evaluates each enabled job's cron in its own
timezone and hands due jobs to the routine runner, carrying fan_power,
water_box_mode and mop_mode so vac-only and vac+mop schedules behave as
configured. One-shot jobs disable themselves after firing.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
(cherry picked from commit b5203b2)
Start the scheduler alongside the other supervisor tasks and stop it on
shutdown. GET /user/devices/{id}/jobs now computes nextFireTime from the
cron instead of returning whatever value was captured at import time.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
(cherry picked from commit 14ddb5f)
schedule_store holds create/update/delete for the per-device jobs kept in
the inventory, so the timer RPC handler, HTTP routes and dashboard can
share one writer. Crons without their own timeZoneId now evaluate in the
zone the robot is told by /location (America/New_York unless configured)
rather than UTC, so a 11:00 schedule fires at 11:00 local.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
(cherry picked from commit 0751a7b)
Timer RPCs carry each schedule's vac and mop settings, and a schedule keeps
the official app's link to its server_timer entry (the robot-side id in its
name) so writing it back goes to the right robot entry.

The four get/set/upd/del_server_timer methods are left to the robot: a robot
that speaks server_timer stores those schedules itself, and answering them
from this store hid the robot's real schedules and, tried once, caused data
loss (the official app deletes server_timer entries it does not recognize when
its schedule screen opens). A parametrized test over all four methods keeps
the interceptor's method list from regressing.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
virtitnerd and others added 4 commits November 15, 2026 16:13
POST /user/devices/{duid}/jobs creates a job (the call python-roborock
makes), and PUT/PATCH and DELETE on /jobs/{id} edit or remove one. The
GET matcher is now method-aware so a write no longer falls through to
the list route. Update and delete paths are not confirmed against the
official app; they follow the scene routes' conventions.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
(cherry picked from commit 5b83853)
A schedule's job (POST /user/devices/{duid}/jobs) carries a settings entry whose
"name" is the id of the matching timer the official app also saved on the robot.
The cloud runs such a job by sending server_scheduled_start with that entry, which
is the method name inside the job itself. The robot accepts it, runs the clean
(rooms or whole home) and records it as "Schedules" in its history; without the
entry it answers -10005 "Invalid timer", and with a bare id "Param should be name
+ fan + segment". python-roborock does not list the command, so it is sent through
a small SchedulerCommand enum.

A schedule with no robot-side id (one saved through the legacy set_timer), or one
the robot refuses, falls back to the plainer ways, since a refused command changes
nothing: a whole-home clean is one app_start carrying the schedule's fields plus
source 3, which the robot also records as "Schedules"; a room schedule is the
settings commands followed by a segment clean. Scenes and routines are untouched.
The new steps are produced only by schedules.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
asyncio.timeout raises TimeoutError, which is an OSError, so a read that timed out because
the robot had not reconnected after a restart was logged as 'Could not save native schedule
reconciliation' with a traceback. The read now has its own handler that logs at debug and
returns, and only a failure to save the result still warns.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@virtitnerd

Copy link
Copy Markdown
Contributor Author

Rebased on the current main and fixed the conflicts. Same 9 commits. The conflicts were in devices/service.py, routine_runner.py, its tests and known_limitations.md. In each one I kept what main changed (the new inventory imports and device name limits, the _OPTIONAL_SETTING_COMMANDS set and its test, the updated limitations bullets) and put the schedule changes on top. The full test suite passes on the rebased branch (611 passed).

@C9H13NO3-dev

C9H13NO3-dev commented Nov 15, 2026 •

Copy link
Copy Markdown

Follow-up test on the rebased head a1a1991 (on main @ 32608dd), same S6 MaxV (roborock.vacuum.a10, firmware 02.62.46).

  • Full test suite: 611 passed.
  • Upgraded in place from the old head ce54133 with the existing data directory. The robot reconnected on its own, with no re-pairing.
  • Restart noise is fixed. On ce54133 every restart logged two Could not save native schedule reconciliation warnings with tracebacks (CancelledError → TimeoutError). The same thing happened every night around 03:20 local time, when this robot drops off MQTT for a moment. In 3 days I saw 10 of them, all TimeoutError, none real save failures. On a1a1991, after a restart: 0 warnings, and get_server_timer polls resume once the robot is back.
  • LocalRock-format timer lifecycle, sent over MQTT through the server: set_timer [[id, ["on", [cron, ["start_clean", {}]]]]] → ok. get_timer lists it (normalised to {"repeat":1,"segments":"0"}). upd_timer off and upd_timer on both apply and show up in get_timer. del_timer removes it. The robot's own get_server_timer was not changed and the robot stayed docked.
  • Real-world result from the previous head: a schedule imported from the Roborock cloud (00 10 * * ?, Europe/Berlin) fired every day at 10:00 local time on Nov 13, 14 and 15 (Schedule 6720712 … fired: started followed by Completed routine scene=Schedule 6720712). That one stays enabled on this head, so the next run will be on a1a1991.

Thanks for the quick fix!

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

area: routines Routines, scenes, schedules and cleaning execution. feature PR adding capability; under this two-type scheme also covers additive documentation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants