retouch-homekit

A ReTouch plugin that exposes the speaker to Apple Home over the HomeKit Accessory Protocol (HAP).

HomeKit used to be built into ReTouch. It is now a plugin so the core binary stays stdlib-only and Apple Home support is opt-in: ReTouch downloads, verifies and supervises this binary like any other plugin, and renders its settings (the pairing QR code and setup code) from the manifest it serves.

What it does

• Publishes the speaker as a single HomeKit Television accessory: on/off, a linked Speaker service (volume/mute) and the six presets as input sources.
• Mirrors live speaker state into HomeKit so the Home app reflects what the speaker is actually doing.
• Serves a config API ReTouch proxies under /api/plugins/homekit/:
  • GET /health — readiness probe
  • GET /manifest — the settings UI (a qr field with the pairing code)
  • POST /action/reset — reset the HomeKit pairing

The HAP server listens on its own LAN port (:51827); the config API listens on the loopback address ReTouch passes with --listen.

How ReTouch runs it

retouch-homekit \
  --speaker-host 127.0.0.1:8090 \  # the SoundTouch local API
  --config-dir   <plugin dir> \    # HAP pairing state persists here
  --listen       127.0.0.1:<port> \# loopback config API (proxied)
  --host-url     http://…          # accepted, unused

The plugin exits on stdin EOF, so it never outlives the ReTouch process that launched it.

Build

Stdlib plus github.com/brutella/hap (HAP needs SRP pairing and transport crypto that isn't feasible on the stdlib). Build inside Docker, like ReTouch:

docker run --rm -v "$PWD":/src -w /src golang:1.22-alpine \
  sh -c 'GOOS=linux GOARCH=arm GOARM=7 go build -o retouch-homekit-armv7l .'

Release (for over-the-air install)

ReTouch installs a plugin from a GitHub release, verifying it exactly like its own OTA. A release must contain:

• retouch-homekit-armv7l — the ARMv7 binary (the catalog asset name)
• SHA256SUMS — checksums covering that asset
• SHA256SUMS.sig — optional ed25519 signature; when the catalog entry carries a public key, this is required

Until the release repo is public, ReTouch can sideload a locally-built binary from the plugin settings ("Install from file").

Vendored speaker client

speaker/ is a copy of ReTouch's speaker client (SoundTouch :8090 REST + :17000 CLI). It is vendored rather than imported because ReTouch keeps it in an internal/ package; this keeps the plugin decoupled from ReTouch's internal API.