openhab-heartbeat

A small watchdog that checks, via the myopenhab.org cloud REST API, whether an openHAB item is still being updated. If the item's last update is older than a configurable threshold, it touches a restart file that some external mechanism (a systemd path unit, a cron job, etc.) can watch to restart openHAB.

How it works

On each run heartbeat:

1. Fetches https://myopenhab.org/rest/items/<item> using HTTP basic auth.
2. Reads the item's state, which is expected to be an ISO-8601 timestamp (for example a DateTime item driven by a rule that stamps "now" at a fixed interval).
3. Compares that timestamp against --minutes:
   • fresh -> writes the current time to the heartbeat state file and reports OK.
   • too old / missing / unreachable -> treated as a failed heartbeat (see below).

A failed heartbeat does not restart immediately. It only touches the restart file once the heartbeat state file itself is older than --minutes, which gives openHAB a grace period to reconnect after its own start-up. If the heartbeat state file does not exist yet (the very first run after start-up), it logs a warning and does nothing.

Installation

Nix

nix build              # builds the package
nix run . -- --help    # run without installing

The flake also exposes an overlay (overlays.default) and a dev shell (nix develop) with the Crystal toolchain, ameba, crystal2nix and friends.

From source

Requires Crystal and shards:

shards install
make            # -> bin/heartbeat   (or: make release)

Usage

Usage: heartbeat [options]
    -i, --item ITEM                  Item to check
    -m, --minutes MINUTES            Age in minutes for heartbeat check to fail
    -f, --file FILE                  File to touch when out of date
    -b, --heartbeat FILE             Heartbeat state file
    -l, --log FILE                   Log file
    -u, --user USER                  User for authentication
    -p, --pass PASSWORD              Password for authentication
    -n, --interval SECONDS           Loop instead of exiting and run every SECONDS
    -v, --verbose                    Run verbosely
    -h, --help                       Show help

--item, --user and --pass are required.

For --user and --pass, if the given value is a path to an existing file, the credential is read from that file (trailing newline stripped). This makes it easy to pass secrets via systemd credentials or a secrets manager instead of on the command line.

--file, --heartbeat and --log default to paths under $STATE_DIRECTORY (itself defaulting to /var/lib/openhab); --log defaults to standard output when unset. Defaults:

Examples

One-shot check (suitable for cron or a systemd timer):

heartbeat --item Heartbeat_DateTime --user me@example.com --pass /run/secrets/openhab-pass

Run continuously, checking every 60 seconds:

heartbeat -i Heartbeat_DateTime -u /run/secrets/openhab-user -p /run/secrets/openhab-pass -n 60

Exit codes (one-shot mode)

In loop mode (--interval > 0) the process never exits on its own; it keeps checking and acting on every iteration.

Development

shards install      # install dependencies
crystal spec        # run the test suite
ameba               # lint
crystal tool format # format
nix flake check     # build with tests enabled

After changing dependencies, regenerate the vendored shard set with crystal2nix (updates shards.nix). The package version comes from meta.json, regenerated from shard.yml with make auto.

License

MIT - see LICENSE. Copyright (c) 2023 Peter Hoeg.