This page was generated from the source of RoboHub. Edit the source, not this page.
Rules & modes
When something holds, do something. The engine, its tables, its page and its
evaluation are this module's; the rules are the application's — seeded from its
presets/rules.yml, changed by its people, kept in its database, and seen by no
other application.
How an application uses it
Include the module after inventory and journal, and add it to deps. It
brings i18n, inventory, journal, notifications, forms and the
robohub.alert interface — the interface only. An application that binds
robohub.alert to providers in its bind: block gets a rule's alerts on those
channels (see robohub-alert/index); one that binds none gets them in the
journal.
The application:
- defines
host_shell(req, title, body, scripts), which draws the rules page in
its layout; - defines
rules_host_value(ref: string) string— its own values that a
condition may name (aquarium.nitrate), and""for any it does not know; - seeds its rules and modes at startup with
rules_presets(text); - calls
rules_tick()from its background work: every few seconds, and when a
reading arrives; - reads the mode in force with
rules_mode();appshellshows it in the top
bar, and its quick-mode button posts to/rules/mode.
Conditions
A small fixed grammar, combined with and, or, not and brackets:
| Written | Reads |
|---|---|
heater.temperature < 24.5 | an inventory item's capability, by handle, through the gateway |
filter-main.switch == on | on/true are 1, off/false 0 |
aquarium.nitrate >= 25 | a value the host answers (rules_host_value) |
mode == feeding | the mode in force (!= too) |
time between 10:00 and 20:00 | the machine's clock; a window may cross midnight |
Numbers compare as numbers, in thousandths; anything else compares as text, for
== and != only. A reading that is not there makes the condition false and is
shown on the rule: a rule never acts on a value it could not read. and and or
stop at the side that decides, so a missing reading there does not matter.
Actions
Separated by ;:
| Written | Does |
|---|---|
switch heater on | switches an inventory item through the gateway |
use feeder | one use of an item (a feeder's portion of food) |
alert warning "the filter draws no power" | the journal, and every alert channel the application binds |
journal info "lights on" | the journal only |
mode feeding, mode end | starts a mode, or ends the one in force |
A rule's states
idle → pending (the condition holds and for is set) → active (it held for
the whole wait; the do actions run). An active rule returns to idle when its
clear condition holds — or, with none, when the condition stops holding — and
its else actions run. A rule fires at most once per cooldown. When an action
cannot be done — an item not yet bound, a device not answering — the rule stays
where it was and tries again a minute later; the problem shows on the
rule and is written to the journal once.
Modes
A mode is a named change for a while: starting it ends the one in force, runs its
do actions and suspends the rules it names; it ends after its time (or when
someone ends it) and runs its end actions.
Presets
rules:
keep-temperature:
when: heater.temperature < 24.5
clear: heater.temperature > 25.5
do: switch heater on
else: switch heater off
filter-stopped:
when: filter-main.switch == on and filter-main.power < 5
for: 60s
cooldown: 30m
do: alert warning "the filter draws no power"
modes:
feeding:
title: Feeding
for: 10m
do: switch filter-main off
end: switch filter-main on
suspends: filter-stopped
rules_presets(text) seeds them. A preset rule or mode is kept as the presets
say; one a person added is never touched; whether a rule is enabled stays the
person's choice.
Changing a rule
Every rule has an Edit link on the rules page: its condition, clear
condition, wait, cooldown and actions are changed there and checked before they
are saved — a change that does not read is shown again with what was typed and
why. A preset rule that is changed becomes edited: the application's presets
no longer change it, and Back to the preset puts it back as they say it (the
presets' own values are kept in rule_presets each time they are applied).
Data it keeps
In the application's database, <workspace>/data/app.db (or RHO_RULES_DB),
from the module's own db/schema.sql, which rho-sql generates into every
application that depends on the module:
| Table | What it holds |
|---|---|
rules | Each rule: its condition, clear condition, wait, cooldown, actions, origin (preset, edited, person), whether it is enabled, its state and when it last fired |
rule_presets | What the presets say each preset rule is, for Back to the preset |
rule_modes | Each mode: its actions, duration, end actions and the rules it suspends |
rule_mode_active | The mode in force, at most one |
The module has no settings of its own; its rules and modes are its data.
GET /rules is the page; GET /api/rules is the state of every rule and the
mode in force, as JSON.
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.rules):
rules_moderules_tickrules_presets
Routes — registered on the host application's router:
| Method | Path | Handler |
|---|---|---|
| GET | /rules | rules_page |
| POST | /rules/add | rules_add |
| POST | /rules/change | rules_change |
| GET | /rules/edit | rules_edit_page |
| POST | /rules/edit | rules_edit_save |
| POST | /rules/mode | rules_mode_form |
| GET | /api/rules | rules_api |
Host hooks — functions the application must define, because this module calls them:
host_shellrules_host_value
Release history
[0.1.0] - 2026-11-13
The rule engine RoboHub applications share. Conditions in a small fixed grammar (comparisons of inventory readings, host values and literals; and, or, not, brackets; the mode in force; a time window), actions on inventory items, alerts, the journal and modes, and a state machine per rule with a pending window, a clear condition and a cooldown. Modes run actions, suspend rules and end by themselves. Rules and modes are seeded from an application's presets; a page and a JSON API.
A rule whose action could not be done stays where it was and tries again, rather than counting as fired; the problem is written to the journal once, not on every evaluation.
[0.1.1] - 2026-11-13
An ordering comparison (<, <=, >, >=) of a reading that is not a number is a problem, as a missing reading already was, not a false answer: not t > 30 no longer holds — and acts — when the sensor says "unavailable".
[0.1.2] - 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. The time of day for time between likewise (rho_local_clock).
[0.1.3] - 2026-11-13
Durations read decimals and days: 1.5h is 5400 seconds and 1d 86400, where both were 0 and a rule's for or cooldown silently vanished. A mode is ended once: whoever clears it runs its end actions, so a tick and a person ending it together do not run them twice.
[0.1.4] - 2026-11-13
A rule whose action failed keeps the failure until an action is done: while it waits out its minute, and while its condition comes and goes — a reading hovering at the threshold. The failure was cleared each time, so the action was tried at once whenever the condition held again and the failure written to the journal every few seconds. An item with no switch bound says so (heater has no switch bound to a device) rather than reading as a device that failed.
[0.1.5] - 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 number in a condition may be written with a decimal comma; a lone . or - is no longer the number 0.
[0.1.6] - 2026-11-14
The grammar has unit tests of its own (tests/rulestest.rho): tokens, numbers and durations, comparisons, and/or/not and brackets, modes, time windows, and a reading that is missing or not a number. `rulesseconds` moved beside the rest of the grammar in src/expr.rho; nothing it does changed.
[0.1.7] - 2026-11-14
MODES_CAPACITY and ignore_rules are RULES_MODES_CAPACITY and rules_ignore. Both carry the module's prefix; unprefixed, they were in the namespace of every application that includes the module.
[0.1.8] - 2026-11-14
A rule can be changed: Edit on the rules page opens its condition, clear condition, wait, cooldown and actions, checked before they are saved and shown again with what was typed when they do not read. A preset rule changed becomes edited, which the presets leave alone, and Back to the preset restores it from rule_presets, which the presets fill each time they are applied. The page's forms send the browser back to the page by GET after a change.
[0.1.9] - 2026-11-14
Deleting a rule asks for confirmation first.
[0.1.10] - 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. Copies of helpers the toolchain now provides (i64_to_str, str_lower, str_field, json_str_field, escape_html) are gone. It declares the i18n module it uses. Needs rho 0.8.0.
[0.2.0] - 2026-11-14
It lists what other code may use (provides.exports, imported as robohub.rules). 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.