Skip to content

Rework schedules: options, server_timer support, SmartPlan, Once and Repeat - #37

Open
virtitnerd wants to merge 6 commits into
DonSidro:masterfrom
virtitnerd:feat/schedule-rework
Open

virtitnerd wants to merge 6 commits into
DonSidro:masterfrom
virtitnerd:feat/schedule-rework

Conversation

@virtitnerd

@virtitnerd virtitnerd commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

  • A schedule only had a time and weekdays, so it always ran with whatever settings the robot happened to have. The official app lets each schedule choose vacuum only, vacuum and mop, or mop only, with its own suction, water level, mop route and pass count.
  • On robots whose firmware uses the newer server_timer protocol, saving a schedule is refused with -10005 "timer type error" and the app used to look as if it had worked (Roborock Qrevo Curv 2 Flow (a245) — Schedule save silently fails, set_timer rejected with -10005 "timer type error" #28).
  • A schedule saved only on the robot did not last: the official app also writes a cloud record for every server_timer schedule and deletes any robot schedule that has none the next time its schedule screen opens. This app's own list is read from those records, so such a schedule never showed in the list either.
  • The schedule screen lacked what the official app offers: SmartPlan, one-time schedules, the Repeat choices and an exact-minute picker.

Changes

One commit per step, in order.

  1. Options per schedule (vacuum, mop, suction, water, route, passes), a refused save is shown as an error, an edit deletes and re-adds instead of sending null, and the option chips wrap (the first three commits, as reviewed).
  2. A schedule's settings also carry the room list, the mop flag and the map index.
  3. The server_timer wire format and detection of which protocol a robot uses, the way the official app does it (the featureset flag from app_get_init_status).
  4. Saving, toggling and editing through server_timer for robots that need it. Every field the official app sends is included, because the robot answers "Param error" to a shorter entry. The fallback to the legacy command happens only for a real "timer type error"; any other refusal is shown, since a retry would save the schedule somewhere the robot never sees.
  5. Editing and deleting a schedule read back from the cloud uses the robot-side id (the name in its settings), not the record's own id.
  6. SmartPlan as a cleaning choice, shown when the robot supports it.
  7. One-time schedules: the day and month are pinned in the cron (15 23 18 10 *), which the app used to read back as "every day". Adds kotlinx-datetime to pick the next date for a time.
  8. The official app's Repeat choices: Once, Every day, Weekdays, Weekends, Custom.
  9. "Current settings" removed from the dialog, as the official app has none; a schedule always opens on Vac & Mop.
  10. The Hawk plugin signs JSON bodies and body-less DELETEs (needed for the cloud record).
  11. Writing the cloud record of a server_timer schedule, as the official app does: created after the robot accepts it, updated on edit and on/off, removed on delete. If the record cannot be written, the robot's entry is removed again so nothing is left half saved.
  12. The mop route chips are Standard, plus Fast when the robot's feature flags support it. A Qrevo Pro accepts Deep and Deep+ as a route setting but refuses them inside a start command (-10005 "Param error"), and the official app's schedule screen offers only the two. A route an existing schedule already carries stays visible.

Verified live

Against a Roborock Qrevo Pro and local_roborock_server, with Python-roborock/local_roborock_server#179 providing the schedule store and the runner: a one-time whole-home schedule created from this app was saved on the robot and as a cloud record, was not deleted when the official app was opened, and was run by the server at its minute; the robot's history shows it as "Schedules | Full". Deleting a schedule from this app removed it on both sides.

Known gaps

Related

Addresses #28. Replaces #30, whose scope this grew past. The time picker change is a separate PR.

Tested

./gradlew :composeApp:testDebugUnitTest: 217 tests, 0 failures. Built the Android app, installed it on a phone and exercised schedules against the Qrevo Pro.

@tslany

tslany commented Oct 20, 2026

Copy link
Copy Markdown
Contributor

Looks like toggleTimer() and deleteTimer() are missing requireOk() on both timer paths. If the robot rejects the command, the app still updates the local list and potentially the cloud record.

@virtitnerd
virtitnerd force-pushed the feat/schedule-rework branch from de88cc2 to cab7109 Compare October 21, 2026 03:30
@DonSidro
DonSidro self-requested a review October 21, 2026 16:51

@DonSidro DonSidro left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

Thanks for the thorough work, and for covering the points from #30.
Server dependency. Saving a server_timer schedule now also writes the cloud record, and that needs local_roborock_server #179, which isn't merged yet. On the current server, POST /user/devices/{duid}/jobs fails. The app then deletes the robot's schedule again and shows an error. Your own Qrevo Pro accepts the old set_timer even with the server_timer flag set, so robots like that can save schedules on master today and would stop being able to after this PR. Could you fall back to legacy set_timer when the jobs endpoint isn't there (404/405)? Either way, I'd like to wait for #179 to be released before merging, and then note the minimum server version in the release notes.

Toggle. upd_server_timer is marked "assumed, not captured". Could you capture the official app turning a schedule on and off? Until then, toggling could use the same delete-and-add as editing, since that path is verified.

Errors on the schedule screen. Toggle and delete in ScheduleScreen are still wrapped in runCatching, so a refusal is silently ignored. Could they go through saveTimer like create and edit, so the error shows and the list is read back?

Water levels. The schedule dialog always offers 201–203. On water-slide robots the cleaning mode sheet uses the slide codes instead, so the schedule should probably do the same when supportsWaterSlide is true.

#28. The a245 reporter tried set_server_timer with the old set_timer shape and got "param error". Could you post the exact params this PR sends for a whole-home Vac & Mop schedule? I'd like to ask them to try it on their robot before this goes in.

I'll merge this before #38 and ask for #38 to be rebased, since both change ScheduleScreen.kt.

@virtitnerd

Copy link
Copy Markdown
Contributor Author

Captured the official app turning a schedule off and back on (Qrevo Pro). Each time it sends two things.

  1. To the robot: upd_server_timer with [["<robot id>","off"]], then [["<robot id>","on"]]. The robot answers ["ok"].
  2. To the server: PUT /user/devices/{duid}/jobs/{jobId} with the schedule's record body and "enabled": false, then true. The cron, the settings and the robot-side id in name stay the same.

The toggle in this PR already sends exactly that, so no behaviour changed. I replaced the "assumed, not captured" comment and added a test pinned to the capture. Delete-and-add would not work for turning a schedule off, because set_server_timer has no on/off field.

For #28, the params for a whole-home Vac & Mop schedule: set_server_timer {"data":[["<id>",["15 23 * * 0,1,2,3,4,5,6",["start_clean",{"fan_power":102,"water_box_mode":202,"mop_mode":300,"repeat":1,"segments":"0","clean_mop":1,"map_index":-1}]]]],"need_retry":1}. That is a bare object, not wrapped in a list.

@DonSidro

Copy link
Copy Markdown
Owner

Thanks for the toggle capture and the params. #38 and #63 are now in master and touch ScheduleScreen and the timer functions, so this needs a rebase (in #63's timer functions, take your version). I'm still waiting for local_roborock_server #179 before merging, since without it saving fails on server_timer robots. #60 covers the same area from the server-jobs side; could you and @pponce agree on one approach? Your native timer and model support, plus #60's read-back checks, seems like the right combination.

@pponce

pponce commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

Thanks @virtitnerd and @DonSidro. I'm happy to combine the approaches rather than land two competing schedule implementations.

My main requirement is preserving schedules that the local server starts at their due time. I confirmed a successful scheduled start on my S7 (a15, firmware 02.16.12), with LocalRock and the OEM Roborock app used for schedule control. I see that this PR already verifies the same overall server-triggered flow on a Qrevo Pro, so we are working toward the same goal.

The server scheduler builds on the still-open [server PR #179](Python-roborock/local_roborock_server#179). My [server PR #213](Python-roborock/local_roborock_server#213) builds on that work with dispatch verification, persisted occurrence claims, imported-payload preservation and stricter handling of rejected native starts.

For reconciliation, I suggest retaining your native timer creation/deletion and model-specific support, then incorporating #60's direct HTTP jobs listing, payload preservation, read-back checks and partial-save reporting.

One integration point needs attention: the server changes keep native-linked jobs out of the legacy get_timer compatibility view. The combined UI therefore needs to read the jobs API so those imported schedules remain visible. It also needs to retain support for server-only jobs without a native timer name.

I agree with waiting for the supporting server functionality to be merged and released before merging the combined client feature, and documenting the minimum server version. Server #214 is a separate dashboard contribution and is not required by LocalRock.

Would that be a reasonable split for combining the work?

@DonSidro

Copy link
Copy Markdown
Owner

Yes, that split works for me: #37 as the base, with #60's jobs listing, payload preservation, read-back and partial-save reporting added on top, so it ends up as one PR. @virtitnerd, are you OK leading the combined branch, with @pponce adding the #60 parts to it? Since the server changes take native-linked jobs out of get_timer, the combined version should read the jobs API, and it needs to come out close to the server release that includes #179 and #213. I'll merge it once those are released and note the minimum server version.

@virtitnerd
virtitnerd force-pushed the feat/schedule-rework branch from 5f90884 to fb0392c Compare October 26, 2026 20:31
@virtitnerd

Copy link
Copy Markdown
Contributor Author

Yes, I'll lead the combined branch. #37 is rebased onto master now (one commit, clean). Where #63 touched the same timer functions I kept the server_timer-aware versions, as suggested.

@pponce, the easiest way to add the #60 parts is a PR into my branch (virtitnerd:feat/schedule-rework). I'll merge it there so it lands in #37 with your commits and your authorship. Since #213 takes native-linked jobs out of get_timer, the list needs to come from the jobs API: your direct jobs listing, payload preservation, read-back checks and partial-save reporting, including jobs that have no native timer name.

What to keep from #37 while combining: native create and delete by the robot-side id, the fallback to legacy set_timer when the jobs endpoint answers 404 or 405, the water slide codes, and the upd_server_timer toggle that matches the capture.

Minimum server version: #179 for #37 on its own, and #179 plus #213 for the combined behaviour. I agree with waiting for those releases before merging.

@pponce

pponce commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Would you be open to using the compact, OEM-style schedule layout from #60 for the combined version? The main list shows start time, repeat, Full/selected rooms, cleaning mode and the enable switch, with the full controls available when editing.

We could retain #37’s SmartPlan, model-specific water and route settings, dated one-time schedules, and native timer support within that editor. Robot-timer diagnostics would remain under More details.

I’m happy to keep this as a separate UI follow-up if that makes the functional integration easier to review.
B9E7ABB0-003E-4C26-8E8B-EB45D225CC32_4_5005_c
F8F0D1B1-1886-43AD-989D-CA0E774C40F7_4_5005_c

@virtitnerd

Copy link
Copy Markdown
Contributor Author

Would you be open to using the compact, OEM-style schedule layout from #60 for the combined version? The main list shows start time, repeat, Full/selected rooms, cleaning mode and the enable switch, with the full controls available when editing.

We could retain #37’s SmartPlan, model-specific water and route settings, dated one-time schedules, and native timer support within that editor. Robot-timer diagnostics would remain under More details.

I’m happy to keep this as a separate UI follow-up if that makes the functional integration easier to review. B9E7ABB0-003E-4C26-8E8B-EB45D225CC32_4_5005_c F8F0D1B1-1886-43AD-989D-CA0E774C40F7_4_5005_c

I'm fine with that yes.
I've been doing all testing via Android so you testing from iOS is a bonus and I can confirm it as well

virtitnerd and others added 5 commits November 14, 2026 01:58
…Repeat

Rebased onto master after DonSidro#38, DonSidro#63, DonSidro#69 and DonSidro#71. In the timer functions
DonSidro#63 also touched, this keeps the server_timer-aware versions; it uses
master's getInitStatus and its live SmartPlan and Water Slide flags.

- Let schedules choose vacuum, mop and suction options
- Check the robot's answer when saving a schedule, and stop sending null
- Wrap the schedule option chips so the chosen one is always visible
- Carry segments, mop, and map fields on a schedule's settings
- Add the server_timer wire format and feature-flag detection
- Speak server_timer to robots that need it
- Edit and delete a server_timer schedule by its real robot-side id
- Offer SmartPlan as a cleaning choice for schedules
- Read and write one-time schedules
- Offer the official app's Repeat choices on a schedule
- Drop "Current settings" from the schedule dialog
- Sign JSON bodies and body-less DELETEs in the Hawk plugin
- Write the cloud record of a server_timer schedule, as the official app does
- Offer only the mop routes a schedule can use
- Read the whole 64-bit featureset when checking for server timers

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Restore the original legacy entry when a replacement fails and report restoration failures. Keep server-job edit behavior unchanged. Exercise 404/405 fallback, 500 propagation, empty jobs and legacy restoration outcomes. Use explicit schedule imports and remove trailing blank lines.
@pponce

pponce commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

@virtitnerd. I reviewed the new restore flow at f964cadd and added automated checks against the unchanged production code.

The existing 387 tests passed, the Android debug build passed, and shared Kotlin code compiled for both iPhone and iOS Simulator. Of 22 additional restore checks, 10 passed and 12 failed. Those failures cover three groups below, rather than 12 separate bugs. I also ran 14 server store/reconciliation checks, all passing, against server #179 at 1927b430.

Normal enabled/disabled whole-home restore worked in the simulation, including the native timer ID, known cleaning/map settings, and dated one-time cron. Existing native timers were not overwritten, and ordinary room schedules and server-only jobs were correctly refused.

There are a few things I think we should address:

  1. A partial restore can enable a schedule that was disabled. Restore creates the native timer enabled, then sends a separate disable. If creation succeeds but disable fails, the timer stays on. Lost responses also exit without reading back the actual state. The details UI can still label it “Missing,” and another restore attempt refuses the now-existing timer. The server reconciliation checks confirm that observing this native timer on can also enable the saved recurring server job.

    I suggest reusing the partial-save safeguards: read back uncertain writes, report what succeeded and what remains unconfirmed, provide a recovery path without blindly recreating the timer, and check the server job’s final state too. There is also a temporary synchronization window between create and disable; a later confirmed off poll corrects that case.

  2. Restore uses the previously loaded server record without checking for changes. In the tests, deleting or editing the server job after loading the screen still allowed restoration from the old record. Two server jobs sharing the same native timer reference were also not rejected.

    I suggest using the fresh snapshot and unique-reference checks already used by normal schedule edits/toggles, including rechecking after network waits.

  3. Unsupported input needs stricter validation. These were defensive tests with synthetic payloads: a malformed native response such as ["ok"] was treated as “Missing”; array-valued room selections bypassed the room guard and became whole-home settings; and an unknown extra setting was silently dropped.

    I suggest refusing malformed or unsupported formats before writing, and preserving extra settings only where they can be restored faithfully. These tests do not establish that a particular robot normally emits those payloads.

I would address the first two before merging and add the input-validation guards alongside them. This remains automated validation; real-device restore, scheduled execution, and OEM/Homebridge interaction still need confirmation. The agreed dependency on server #179 being merged and released remains unchanged.

[Validation run](https://github.com/pponce/LocalRock/actions/runs/43625485455) · [Detailed findings, reproductions and tests](https://github.com/pponce/LocalRock/blob/review/schedule-restore-validation-20261114/local-work/restore-review/REVIEW.md)

The validation run is red because the additional restore checks expose these gaps; the existing test suite and Android build passed.

Re-pairing a robot can clear its server_timer list while the server keeps
the schedules, so toggling one stopped with "Native timer is missing".
Opening Schedules now reads the robot's server_timer list once; if any
schedule's timer is gone, a card says how many and Restore on robot
rebuilds them from the job (name, cron with ? as *, settings), turns off
the ones whose job is off, and reads them back. A single schedule can also
be restored from its More details.

Restore works from a fresh read of the server job and refuses one that was
deleted, edited since it was loaded, or shares its native timer with
another job. A lost or timed-out reply is read back, never resent. If the
timer came back but could not be turned off, the error says so and More
details offers Finish restore, which only turns it off. When the server's
reconciliation copied the brief "on" into the job, the job's saved state is
put back and confirmed.

Refused before any write: room schedules (the robot numbers rooms
differently), room selections that are not a string, settings the app
cannot rebuild exactly, and a malformed server_timer list, which now reads
as Unknown rather than Missing everywhere.

Restore flow tests from pponce's review of DonSidro#37, run through the real
repository, session and codec over an in-memory MQTT transport.

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

Copy link
Copy Markdown
Contributor Author

@pponce Thanks for the thorough review and the tests. All three groups are fixed in the restore commit (now 2f7c1aa), and your NativeRestoreFlowTest is included; all 22 checks pass along with the existing suite.

  1. Partial restore: a lost or timed-out reply is read back and never resent. If the timer came back but could not be turned off, the error says so and More details offers Finish restore, which only sends the off. After the robot is confirmed, the server job is read again; if reconciliation copied the brief "on" into it, the saved state is put back and confirmed.
  2. Restore now works from a fresh job read and refuses a job that was deleted, edited since loading, or shares its native timer with another job, rechecked before the off is sent.
  3. A malformed server_timer list now reads as Unknown rather than Missing everywhere; non-string room selections and settings the app cannot rebuild exactly are refused before any write.

Two test changes: the stub mirror's update now applies the patch (the reconcile fix needs that write), and the create-timeout test expects success when the read-back confirms the timer, matching the lost-reply test. Still automated only; no live restore yet.

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants