[GUIDE] Volumio Time Sync Watchdog (setdatetime-helper)

Help and Support Guides
, , , ,
1

What it is

Volumio is a bit-perfect audio player. Accurate system time is critical for:

  • Online services such as TIDAL, Qobuz, Spotify, Web Radio
  • Secure HTTPS connections
  • Correct playback scheduling
  • Multiroom synchronization

Not every device has a Real-Time Clock (RTC), and not every network provides working NTP. To avoid time drift or boot-time errors, Volumio now includes a Time Sync Watchdog.

How it works

  1. Runs every minute via systemd timer.

  2. Checks if ntpsec already keeps the clock in sync.

    • If yes, nothing else is done.
    • If not, fallback kicks in.

  3. Queries external services for their HTTP Date headers (time.is, Cloudflare, Google, Bing, Baidu).

  4. Applies the first reliable timestamp.

  5. Avoids unnecessary corrections:

    • Ignores tiny drifts (<=1 second).
    • Skips small backward steps (<120 seconds) to protect audio.

Default logging

  • By default the watchdog only logs errors (safe for microSD cards).

  • A sentinel control file /data/setdatetime.logger is created automatically.

  • Its content controls verbosity:

    • error = only errors (default)
    • info = include sync decisions
    • debug = full diagnostic output

Edit manually with:

nano /data/setdatetime.logger

Running manually

sudo /usr/bin/setdatetime-helper.sh

Flags:

  • -f, --force = force sync, ignore safeguards and ntpsec
  • -v, --verbose = temporary verbose output to stdout
  • -d, --debug = temporary debug output to stdout
  • -q, --quiet = errors only for this run
  • --no-sentinel = bypass logger file
  • -h, --help = usage info

Diagnostics

Check scheduling

systemctl status setdatetime-helper.timer
systemctl show setdatetime-helper.timer -p NextElapseUSecMonotonic -p LastTriggerUSecMonotonic
systemctl list-timers | grep setdatetime

Show helper activity

journalctl -b -u setdatetime-helper.service | tail -50

Verify sync against trusted source

hdr="$(curl -sI --max-time 3 https://time.is | sed -n 's/^[Dd]ate:[[:space:]]*//p')"
echo "hdr: $hdr"
echo "sys: $(date -u)"
echo "delta_sec=$(( $(date -u +%s) - $(date -ud "$hdr" +%s) ))"
  • If delta_sec is near zero, your clock is aligned.
  • If delta_sec keeps small, ntpsec has taken over fine sync.
  • If large corrections happen, the watchdog is stepping in.

FAQ

Q: Does this break static IP setups?
A: No. It only needs outbound HTTPS.

Q: Will it conflict with ntpsec?
A: No. If ntpsec is running, the watchdog only observes.

Q: Why HTTPS instead of just NTP?
A: Some networks (firewalled, captive portals, hotel WiFi) may block NTP. HTTPS Date headers are universally available.

Availability

The Time Sync Watchdog ships starting with Volumio 4.027 RC, enabled by default on all builds:

Kind Regards,

2 Likes