Skip to content

v0.3.0 – wellness on evidence, the watch's own files, Health Snapshots

Choose a tag to compare

@futureweb futureweb released this 10 Oct 09:27
· 140 commits to main since this release

The night's values within minutes of the morning watch sync, a quarter of the
Garmin requests, and a mirror that now includes what the watch itself
recorded: the original wellness files of every day, Health Snapshots among
them, which Intervals now shows too.

Upgrading: systemd users add --activity-interval 120 to the 30-minute
unit's ExecStart (the copy in deploy/systemd/ has it). The first run
takes over the new schedule on its own. To mirror the past once:
backfill --scope wellness --from 2020-01-01 --wellness-files --pause 3,
backfill --scope activities --from 2020-01-01 --archive-only --pause 3
(adds Garmin's splits) and snapshot-account --history-from 2020-01-01.
If Intervals' Garmin settings import SpO2, untick it: the official
integration only ever delivers it from Health Snapshots.

Changed

  • Wellness is read on evidence, not on a clock. Last night's values
    (sleep, SpO₂, respiration, sleeping HR, HRV detail, sleep stages, Training
    Readiness, skin temperature) reach Intervals within about ten minutes of
    the morning watch sync instead of up to four hours later. The watch checks
    Intervals' record for today every ten minutes, which costs no Garmin
    request, and reads four Garmin endpoints once the official integration has
    delivered the sleep; Training Readiness gets two more tries if it lags. A
    finished day is read in full once the device has synced after it ended
    (proven by Garmin's last-sync time), so its totals are complete; a day
    without any sync is read anyway at 20:00 the day after. Without the
    official wellness sync, Garmin is checked at a few fixed morning times.
  • The scheduled runs ask Garmin far less: no more four-hourly re-reads of
    today and yesterday, no re-read of the day before yesterday, no login on
    runs with nothing to do, and in enrich mode the Garmin activity list is
    scanned every two hours (sync --activity-interval, also in run); the
    watch enriches new activities in between. About 75 requests on a normal
    day instead of about 310.
  • Manual container builds move latest only when asked; a release always
    does. The tag of a manual build is validated before it reaches the shell.

Added

  • The device's original wellness files. Every finished day's ZIP of the
    watch's own wellness FIT files is mirrored to wellness-files/<day>.zip
    with its final read (one request a day): all-day heart rate, respiration
    per minute, stress, SpO₂ readings, overnight HRV, sleep, skin temperature,
    and Health Snapshots, which exist nowhere else. An index next to it lists
    the files (each CRC-checked) and summarises every Health Snapshot (heart
    rate, RMSSD and SDRR, respiration, SpO₂, stress). backfill --scope wellness --wellness-files fetches the past.
  • Garmin's own splits of every activity (typed splits and split summaries)
    in the activity extras; backfill --archive-only adds them to older
    archive entries without fetching anything else again.
  • Health Snapshots in Intervals: the day's first snapshot (heart rate,
    RMSSD, SDRR, respiration, SpO₂, stress) in GarminSnapshot… fields with
    a new chart. Where the official integration writes a snapshot into
    resting HR, HRV or SpO₂, the night's value is put back, on the same day
    (one read of today's files when Intervals' HRV moves away from the
    night's); that is the only case besides a filtered file in which the
    bridge replaces a value.
  • More of the night: lowest SpO₂, lowest and highest respiration, Body
    Battery change during sleep and Garmin's HRV baseline band, all from the
    archive (the HRV and SpO₂ charts show them).
  • The container image is also on Docker Hub,
    futurewebat/garmin-intervals-bridge, for NAS container managers that
    only know Docker Hub.
  • The account snapshot also keeps goals, gear defaults, training plan
    details, the calendar of scheduled workouts, Garmin's FTP (latest and
    daily history, cycling and running), running tolerance and the activity
    type table; snapshot-account --history-from DATE reaches back once.

Fixed

  • The regular enrich and upload runs now archive Garmin's summary, weather,
    gear and exercise sets of every activity they handle. Before, only
    backfill --archive-only did, so a mirror built once drifted as new
    activities came in (the recording was kept, the rest was not). Extras that
    Garmin has not attached yet to a fresh activity are asked for again on the
    next run instead of being archived as empty.
  • Exercise sets are also fetched when the activity comes from the detail
    endpoint (activityTypeDTO), not only from the list.

Documentation

  • README links the sister project, the
    Futureweb Intervals MCP:
    it lets ChatGPT, Claude and other MCP clients read and analyse every field
    and stream the bridge writes. A table maps the bridge's data to the MCP
    tools that read it.

Install: pip install -U garmin-intervals-bridge, or the image ghcr.io/futureweb/garmin-intervals-bridge:0.3.0 / futurewebat/garmin-intervals-bridge:0.3.0 (Docker Hub).