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.
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
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 windowRun a server so phones/other hosts can hit the URL drop-in and timeline:
uv run homewatch serve # http://127.0.0.1:8765http://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"| 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 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/STATUS.md— orientation: where it is, what works, what's open.docs/specs/— design intent (the spec); §11.4 is the CLI ve×ばつnoun grammar.docs/refs/— durable reference: product vocabulary, update streams, tvOS↔HomePod, date precision.docs/sessions/— per-session reports + the REQUESTS log.
uv run pytest
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.