RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

Scheduler

Recurring maintenance and deferred actions — chores — for a host application:
a water change every week, a filter rinse after 720 hours of running, a check at
a set time. The module registers its pages and API on the host's router
(/scheduler, /api/scheduler/...); it has no port of its own. Aquarium and
energy include it.

How an application uses it

Include the module and add it to deps. It brings i18n, settings,
notifications, forms and inventory.

The application:

  • defines host_shell(req, title, body, scripts): the module's pages render
    content only, and their CSS travels with the content;
  • seeds its chores at startup with scheduler_presets(text) (below);
  • calls scheduler_usage_tick() from its background work, after
    inventory_runtime_tick(), if chores follow an item's runtime;
  • calls scheduler_complete_title(title, note) when what it records is the
    chore itself — a water change logged is the water-change chore done;
  • adds the module's settings tab: scheduler_settings_form and
    scheduler_settings_save, combined through host_settings_tabs/form/save
    (see appshell/index).

scheduler_status(chore, now) and scheduler_links_text(chore) let an
application show a chore's state and what it is tied to on its own pages.

Schedules

KindWhen it is due
intervalEvery N hours (interval_hours; a day when none is given)
cronA five-field cron expression (minute, hour, day of month, month, day of week) in the machine's local time: *, 5, 1-5, 1,3,5, */15, 10-50/20. As in cron, when both day fields are restricted a day matching either is taken; day of week 7 is Sunday
one_timeA date and time
usageAfter N hours of use (usage_hours), typed in, posted to POST /api/scheduler/chores/{id}/usage, or counted from an inventory item's runtime

A chore is due when its time comes and overdue once its grace period
(grace_hours) has passed. Completing it records the note and computes the next
due time at once. Snoozing moves the visible due time without changing the
schedule.

Tied to the inventory

A chore can name inventory items by handle. runtime_of: filter-main makes a
usage chore count the item's switch runtime instead of hours typed in; only
runtime gained since the chore was tied to the item counts. consumes: filter-pads with consumes_qty: 1 takes that much off the shelf each time the
chore is done, recorded as a stock movement for the chore (chore#<id>).

Presets

scheduler_presets(text) seeds the chores from the text of the application's
presets/schedule.yml. Each chore under chores: has a title and a kind,
and may have value (the cron expression or the date), interval_hours,
usage_hours, grace_hours, priority, runtime_of, consumes and
consumes_qty:

chores:
  water-change:
    title: Water change 30 %
    kind: interval
    interval_hours: 168
  rinse-filter:
    title: Rinse filter media
    kind: usage
    usage_hours: 720
    runtime_of: filter-main
    consumes: filter-pads
    consumes_qty: 1

A chore is added once, by its title; after that it is the person's.

API

The JSON API under /api/scheduler/chores lists chores with their status and
due time, creates one, and completes, snoozes (in hours) or adds usage hours to
one by id. The routes are listed in the reference below.

Settings

Kept in the application's settings store (see settings/index):

KeyDefaultWhat it is
scheduler.grace_hours12The grace period a new chore starts with
scheduler.prioritynormalThe priority a new chore starts with

Data it keeps

In the application's database, <workspace>/data/app.db (or
RHO_SCHEDULER_DB), from the module's own db/schema.sql, which rho-sql
generates into every application that depends on the module:

TableWhat it holds
choresEach chore: its schedule, next due time, grace, priority, and what it is tied to in the inventory (runtime_of, the runtime already counted, consumes)
chore_completionsEach completion, with the note a person left

Additions and completions are written to the application log under the
scheduler subject; a changed chore is written to the journal.

Reference

Generated from the module's manifest and sources when this site was built.

Exports — what an application may call (provides.exports, imported as robohub.scheduler):

  • scheduler_status
  • scheduler_links_text
  • scheduler_usage_tick
  • scheduler_presets
  • scheduler_complete_title
  • scheduler_settings_form
  • scheduler_settings_save

Routes — registered on the host application's router:

MethodPathHandler
GET/schedulerscheduler_page
POST/scheduler/chores/addscheduler_chores_add
POST/scheduler/chores/completescheduler_chores_complete
POST/scheduler/chores/snoozescheduler_chores_snooze
POST/scheduler/chores/usagescheduler_chores_usage
GET/scheduler/chores/editscheduler_chore_edit_page
POST/scheduler/chores/editscheduler_chore_edit_save
POST/scheduler/chores/deletescheduler_chore_delete
GET/api/scheduler/choresscheduler_api_list
POST/api/scheduler/choresscheduler_api_add
POST/api/scheduler/chores/{id}/completescheduler_api_complete
POST/api/scheduler/chores/{id}/snoozescheduler_api_snooze
POST/api/scheduler/chores/{id}/usagescheduler_api_usage

Host hooks — functions the application must define, because this module calls them:

  • host_shell

Release history

[0.1.0] - 2026-11-02

The scheduler module. Interval, cron, one-time and usage-based chores; due and overdue states with a grace period; completion notes and next-due recalculation; snoozing; and a JSON chores API under /api/scheduler/chores. Tables live in the host application's main SQL database.

[0.1.1] - 2026-11-03

The scheduler page carries the same full application menu as the dashboard.

[0.1.2] - 2026-11-08

English/Romanian navigation and page copy, forms-engine add-chore flow with CSRF, and scheduler defaults moved to parent settings.

[0.1.3] - 2026-11-09

Pages render content through the host shell, so the host application owns the header, footer and menu. The scheduler CSS moved into templates/parts/style.html with the content. Chore additions and completions are written to the host application log.

[0.1.4] - 2026-11-12

The module declares the runtime functions it calls rather than relying on helpers the including application defines. Its smoke test signs in with a keeper ticket and sends the form token the module checks.

[0.1.5] - 2026-11-13

The module declares its tables and statements in its own sql: block, and rho-sql 0.2 generates them into each application that depends on it, so an application no longer repeats them. The smoke test runs in the aquarium's own repository.

[0.2.0] - 2026-11-13

A chore can be tied to the inventory: runtime_of names an item whose switch runtime (counted by inventory 0.2) drives a usage chore through scheduler_usage_tick(), and consumes names an item and a quantity that completing the chore takes off the shelf, recorded as a stock movement for that chore. An application seeds its chores from its presets (scheduler_presets); a seeded chore is added once and is the person's after that. scheduler_complete_title(title, note) completes a chore by its title, for an application whose own record is the chore (a water change logged).

[0.2.1] - 2026-11-13

The clock is read from the process (rho_now_s, rho 0.6.0) instead of from date written to a file and read back, which a request and the background loop could truncate under each other: entries dated 1970 and modes that expired at once. A date a person typed is one argument of date -d, run without a shell (rho_exec_capture), and its answer is returned rather than read from a shared file.

[0.2.2] - 2026-11-13

Cron is read as cron: *, numbers, ranges, lists and steps in all five fields (*/15 * * * *, 30 9 * * 1-5, 0 8 * * 7), day of week 7 as Sunday, and a day of the month or of the week matching when both are restricted, in local time with the offset of each moment. Before, */15 was never due and every weekday range was Saturday. A cron that names no time is refused. The API's add says whether the chore was kept, and why not, instead of always answering 201.

[0.2.3] - 2026-11-14

Trimming, URL escapes, form fields and decimals come from the toolchain (rho 0.7.0: str_trim, str_url_encode/str_url_decode, form_field, milli_*) rather than this module's own copy, the same on both backends. Needs rho 0.7.0. A quantity reads a decimal comma and a sign; a negative one is 0.

[0.2.4] - 2026-11-14

Cron is read in src/cron.rho, apart from the chores, and has unit tests of its own (tests/scheduler_test.rho): fields, lists, ranges and steps, the next time in local time in any time zone, and expressions that name no time. Nothing it does changed.

[0.2.5] - 2026-11-14

The route handlers are scheduler_chores_add, scheduler_chores_complete and so on, and the helpers and constants carry the prefix too (ignore_string is scheduler_ignore_string); unprefixed, they were in every including application's namespace.

[0.2.6] - 2026-11-14

Its data is kept where app_workspace() says (rho 0.8.0) — the application's workspace, else ~/.rho/apps/<app> — so two applications started by hand no longer share this module's records. It declares the i18n module it uses. Needs rho 0.8.0.

[0.2.7] - 2026-11-14

A chore can be edited — its schedule, what it uses, its priority — and deleted with its history, from its row; renaming one does not move when it is due. The row's forms carry the form token and are translated, and a change returns to the page by GET.

[0.2.8] - 2026-11-14

Its settings form is its own (scheduler_settings_form, scheduler_settings_save), shown by an application as one of its settings tabs.

[0.3.0] - 2026-11-14

It lists what other code may use (provides.exports, imported as robohub.scheduler). An application that includes it still reaches everything, and a build (rho 0.8.3) names each call to a function outside the list. The list is what the applications and modules of the ecosystem call; anything else is the module's own and may change without notice.