homewatch

A small self-hosted service for correlating Home Assistant outages with Apple / HomePod / HA software releases. It answers one question: did a HomePod / iOS update land just before Home Assistant's HomeKit/Matter integrations broke (or vice versa)?

It does this by pulling release metadata (RSS/Atom feeds + scraped Apple support pages + on-LAN version probes) and lining it up on a single timeline against your own append-only log of "noticed it down at 19:42".

See docs/specs/homewatch-spec.md for the full design.

Quick start (local-first — no server needed)

uv sync                      # create venv, install deps (or: uv sync --extra all)
cp .env.example .env         # optional: HA url/token, bearer, HOMEWATCH_HOME
uv run homewatch refresh     # pull all release streams into the local DB
uv run homewatch status      # per device: running version vs latest
uv run homewatch timeline    # releases × devices × observations, interleaved

(Or install it as a tool — see Install at the bottom.)

The CLI talks straight to the local SQLite file and the upstream feeds. Log an observation, pull a single source, read full notes on demand:

homewatch til down homepod-kitchen "siri unresponsive"
homewatch til up   homepod-kitchen
homewatch latest homepod_software
homewatch show    home_assistant_core          # full release notes, fetched live
homewatch sources                              # streams + freshness

Cadence

homewatch refresh is a single-shot updater — schedule it however you like:

0 * * * *  homewatch refresh            # hourly via cron/launchd/systemd

Or run the foreground "watchman" loop until an update lands:

homewatch watch --interval 1h --until-new --product homepod_software
homewatch watch --interval 30m --for 7d --probe          # poll a window

Daemon (secondary — access from other devices)

Run a server so phones/other hosts can hit the URL drop-in and timeline:

uv run homewatch serve       # http://127.0.0.1:8765

http://homewatch.local:8765/til/drop/down/homepod-kitchen?text=siri+timer+dead

Point the CLI at a remote daemon with --remote URL (or HOMEWATCH_URL):

homewatch --remote https://homewatch.example til down ha "core upgrade broke matter"

Surfaces

Half	What
releases	POST /releases/refresh, GET /releases, GET /releases/latest
probes	POST /probe/ha, POST /probe/homepods, GET /probe/history
til	web form GET /til, URL drop-in GET /til/drop/{kind}/{target}
timeline	GET /timeline — releases × probes × TIL, interleaved by time

HomePod probes

HomePod versions are only discoverable over mDNS (link-local), so the HomePod probe must run on the same L2 network as the HomePods. Install the probe extra there:

uv sync --extra probe    # pyatv
# or the lighter raw-mDNS path:
uv sync --extra zeroconf

Then enable discovery and probe (must be on the same L2 segment as the HomePods):

export HOMEWATCH_HOMEPOD_DISCOVERY=pyatv
homewatch probe homepods            # records + auto-enrolls each HomePod
homewatch probe homepods --raw      # debug: list every AirPlay device seen
homewatch probe homepods --raw --host 192.168.1.42   # unicast a known IP
homewatch devices list              # name, version, IP per device

Detection uses the AirPlay TXT (AudioAccessory* / osvers) and device name, so HomePods are found even when pyatv can't resolve their model. On a VPS, run the release/TIL halves remotely and a thin probe agent on the LAN that posts results up (see spec §7).

Docs

• docs/STATUS.md — orientation: where it is, what works, what's open.
• docs/specs/ — design intent (the spec); §11.4 is the CLI verb×noun grammar.
• docs/refs/ — durable reference: product vocabulary, update streams, tvOS↔HomePod, date precision.
• docs/sessions/ — per-session reports + the REQUESTS log.

Development

uv run pytest

Install

Not on PyPI — install or run straight from GitHub:

# choose your fighter:  uvx (one-off) · uv tool install (onto PATH) · pip
# choose your edition:   homewatch · homewatch[probe] (pyatv) · homewatch[all] (+zeroconf)

# one-off, no install (uv):
uvx --from git+https://github.com/mcint/homewatch homewatch --help
#   …with on-LAN probing for this run:
uvx --with pyatv --from git+https://github.com/mcint/homewatch homewatch probe homepods

# install as a CLI tool:
uv tool install git+https://github.com/mcint/homewatch
#   …with the LAN-probe libs (pick one or both):
uv tool install git+https://github.com/mcint/homewatch --with pyatv --with zeroconf
#   (equivalently, via the declared extras:)
uv tool install "homewatch[all] @ git+https://github.com/mcint/homewatch"

# or pip:
pip install git+https://github.com/mcint/homewatch
pip install "homewatch[all] @ git+https://github.com/mcint/homewatch"

The default install is the lean version tracker (release feeds + CLI + daemon). Add pyatv (--with pyatv or [probe]), zeroconf, or [all] for on-LAN device discovery — homewatch probe coaches you if the lib is missing. The package is PyPI-ready (metadata + extras) if/when you choose to publish.