Hebcal's candle-lighting and havdalah times are merged into windows: one Shabbat, one Yom Tov, or several consecutive days of both (a two-day Yom Tov running into Shabbat is a single window). Each device has rules; a rule is an action at an offset from an event in each window:

Rule options: offset ("-60m", "+1h30m", "20s", or whole minutes), action (usually "on"/"off"), only (any, shabbat, yomtov, shabbat_without_yomtov), and catch_up: how late the action may still be sent if the computer was off or the device unreachable (default 15m). Use a long catch_up for things that should still happen late (Sabbath mode on) and a short one for things that should not (a hot plate).

If several actions for one device are due at once, only the latest is sent. Failed actions are retried (retries, retry_delay); after the last attempt a notification is sent.

mkdir -p ~/.local/share/shabbat-tools ~/.config/shabbat-tools
cp -r . ~/.local/share/shabbat-tools/scheduler/
cp config.example.toml ~/.config/shabbat-tools/scheduler.toml
chmod 600 ~/.config/shabbat-tools/scheduler.toml
$EDITOR ~/.config/shabbat-tools/scheduler.toml
python3 ~/.local/share/shabbat-tools/scheduler/shabbat_scheduler.py --plan

The config is TOML (Python 3.11+). A .json file with the same structure also works, including on older Python. More examples are in [examples/](examples/).

Location

[location]
tzid = "Asia/Jerusalem"      # always required
latitude = 31.778            # or: geonameid = ...
longitude = 35.235
israel = true                # false = diaspora (two-day Yom Tov)
candle_minutes = 18
havdalah_minutes = 40

(Jerusalem is only an illustration.) If candle_minutes is omitted the default is 18 outside Israel, 40 with jerusalem = true, and 15 elsewhere in Israel; communities differ, so set your shul's own figure (the board's calibration page shows it). Run the scheduler on a device that stays on for all of Shabbos and Yom Tov. Hebcal treats b=18 as "use the default", which in Israel becomes 20; the scheduler works around this so 18 means 18.

Secrets

Keep tokens out of the config file. Every driver accepts token_env (the name of an environment variable) or token_file (a file only you can read); password settings work the same way (password_env, password_file). With systemd, put KEY=value lines in ~/.config/shabbat-tools/scheduler.env (chmod 600); the units load it.

SmartThings

• Personal access token: create one at the SmartThings developer site with device read and execute scopes and set token_env. SmartThings has announced that newly created personal access tokens expire after 24 hours; if yours does, use OAuth.
• OAuth: create an API-only OAuth app with the SmartThings CLI (smartthings apps:create), with scopes r:devices:* and x:devices:* and a redirect URI you control. Set auth = "oauth", oauth_client_id, oauth_client_secret_env and oauth_token_file, then run python3 shabbat_scheduler.py --smartthings-login fridge --redirect-uri <uri> once. Tokens are refreshed and rotated automatically and stored with mode 600. (This flow is covered by mock tests only; please report problems.)
• device_id comes from the SmartThings app or smartthings devices.
• verify = true (default) reads the state back after the command.

Notifications

[notify]
command = ["notify-send", "Shabbat scheduler"]   # subject and body are appended

[notify.smtp]
host = "smtp.example.org"
port = 587
username = "me@example.org"
password_env = "SCHEDULER_SMTP_PASSWORD"
from = "me@example.org"
to = ["me@example.org"]

Running

Pick one:

• Service: --run catches up, then sleeps until each next action. ``bash cp systemd/shabbat-scheduler.service ~/.config/systemd/user/ systemctl --user daemon-reload && systemctl --user enable --now shabbat-scheduler loginctl enable-linger "$USER"
• Timer: --tick every minute, exits immediately when nothing is due. ``bash cp systemd/shabbat-scheduler-tick.* ~/.config/systemd/user/ systemctl --user daemon-reload && systemctl --user enable --now shabbat-scheduler-tick.timer
• Cron: see [crontab.example](crontab.example).

A lock file prevents a tick and the service from acting at the same time; a state file in ~/.local/state/shabbat-tools/scheduler/ prevents double firing.

Other commands:

python3 shabbat_scheduler.py --plan --days 30      # no device is contacted
python3 shabbat_scheduler.py --do fridge on        # send one action now, to test

Tests

python3 -m unittest discover -s tests -v

Plan computation (plain Shabbat, Yom Tov on Friday running into Shabbat, a diaspora two-day Yom Tov, Shabbat running into Sunday Yom Tov), catch-up, retries and notifications, the Hebcal request, and every driver against a local mock HTTP server or TCP socket. No real device or cloud API is contacted.