Automations
A rule interrupts the effect on a device for a while, then gives it back: the time on the hour over your usual effect, the keyboard dark at night. Rules run inside the application, like the effects, so they keep working with the window closed.
A rule is a sentence
Every hour · on weekdays · on DeathStalker V2 Pro · show Clock · for 10 seconds
Each part is a choice in the Automations tab: when — a time, or nobody at the computer — on which devices, which effect, for how long. The effect can be any of them — one that ships with Candeo, one of yours, or one the device's firmware runs, Off included — with settings of its own, so the hourly clock need not look like the clock you apply by hand.
A switch turns a rule on. Try runs it once, now, for its duration, so you see what it does without waiting for the hour. Two examples, Hourly clock and Night off, are there to start from.
When: a cron expression
The chips write the usual cases: every minute, every quarter of an hour, every hour, at a time; every day, weekdays, the weekend, chosen days. Advanced takes any cron expression instead — one or the other holds a rule, never both.
An expression has five fields, minute hour day month weekday, or six with
the seconds first. It is read against the computer's clock, daylight saving included.
An occurrence starts each time it matches, and lasts the rule's duration.
| What | Expression | For |
|---|---|---|
| On the hour | 0 * * * * |
10 s |
| Five seconds before each hour | 55 59 * * * * |
10 s |
| Every quarter of an hour | */15 * * * * |
10 s |
| Each hour from 9 to 18, on weekdays | 0 9-18 * * 1-5 |
10 s |
| The night | 0 22 * * * |
9 h |
A time window is a start and a duration: at 22:00 for nine hours. Occurrences that follow each other without a gap — every second for a second — are one display, not an effect restarted every second.
When: nobody at the computer
A rule can wait for you to step away instead of watching the clock: after 10 min idle, show Off, until someone is back. It ends at the first key or mouse move, within a second.
The time comes from the system's own count of the last input — Candeo reads no keys for this, and someone using only the mouse is not away. Windows answers it; elsewhere the choice is shown unavailable, and a rule waiting for it does nothing.
When: another program says so
A rule can wait for a signal: a value another program sends —
when build is failed, show a red
gradient on the ring, while it holds. A build script, a home-automation
system, a watcher of your own: anything that can make an HTTP request, with the token
shown in Settings.
While it holds suits a state: the rule lasts from the moment the value arrives until it changes, expires or is erased. For 5 seconds suits an event: a flash at each receipt, so a doorbell rung again flashes again. The sender never names a device or an effect — it says what happened, and the rule decides what that lights. The API is off until you turn it on; how to send, and how a setting can follow a signal too, is on the signals page.
When two rules meet
The order of the list is the priority. When two rules apply to a device at the same time, the higher one shows; drag a rule, or use its arrows, to move it. With the hourly clock above the night:
| Time | The keyboard shows |
|---|---|
| 21:59 | your effect |
| 22:00 | nothing — the night turns it off |
| 23:00:00 | the clock, the higher rule |
| 23:00:10 | nothing again — the night is still under way |
| 07:00 | your effect, as it was at 21:59 |
A hidden rule is not postponed. Put the clock under the night and it does not show at night — nor at 07:00: an occurrence nobody saw is simply gone.
You have the last word
- Applying an effect, stopping one, or choosing one from the tray ends what the rules were showing on that device — every rule under way there, not only the one on screen. Each comes back at its next occurrence: the next hour, the next night.
- Resume, on the device card and in the tray, gives the device its effect back now, the same way.
- Pause automations, in the tray and in the tab, holds every rule until you turn them back on — for a meeting, for a game — and stays paused across a restart.
What a device goes back to
The effect applied to it, with its settings, started again from the beginning. Rules never change which effect is applied: when the last one ends, the device shows what you chose.
When the firmware was running the lighting — Spectrum Cycle, Wave — Candeo reads its effect back from the device before a rule interrupts it, and sets it again afterwards. One it cannot read back gives way to Off, rather than leaving the rule's last frame frozen on the keys.
Where rules live
In settings.json, with the other settings, in the order of the list. A rule
edited by hand into something unreadable does nothing and stays as written, without
stopping the others. The format is in
docs/api/commands.md,
and the reasons behind these choices in
docs/design/inputs-and-automations.md.