Relay docs

The Relay as a Home Assistant app

Already running Home Assistant? Then the Relay can live right inside it — no separate computer needed. Same Relay, same pairing, same features.

approx. 2 min Beginner-friendly Last updated:

What you need

Add the repository

In Home Assistant, open Settings → Add-ons → Add-on store, then the ⋮ menu (top right) → Repositories, and add this address:

https://github.com/ylabonte/poolpilot-relay

Install the Relay

Find PoolPilot Relay in the store, open it and select Install. Home Assistant pulls a ready-made image — nothing is built on your device.

Check the settings — before pairing

The app’s Configuration tab has exactly two settings:

  • LAN port (lan_port, default 8443): the port the PoolPilot app uses to reach the Relay at home. Change it only if another app already holds 8443 — the log then shows bind: address already in use.
  • Additional mDNS logs (mdns_verbose_logs, off by default): brings back harmless notices from the discovery library. Only meant for troubleshooting.

Start it and pair it in the app

Start the app in Home Assistant. Then open the PoolPilot app on a phone on the same network: the Relay announces itself over mDNS, the app finds it automatically and walks you through pairing. You don’t need to touch the Home Assistant app’s console for this.

More on pairing and sharing under Pairing & household.

Your data and backups

The pairing, the controller registration and the Relay’s TLS identity live on the app’s own persistent storage (/data):

  • They survive restarts and app updates on their own.
  • They are included in your Home Assistant backups.

The TLS identity is what your paired phones trust. Lose it, and every phone has to pair again.

Updates

Updates arrive through the app store, like for any other Home Assistant app. The Supervisor owns the update process, so in Home Assistant the Relay does not update itself. How updates work on a Raspberry Pi is covered under Updates & settings.

Removing the app

If something’s off

  • The app can’t find the Relay: is the Home Assistant app started? Are Home Assistant and your phone on the same network? Is the port (default 8443) free?
  • The log shows bind: address already in use: another app holds the port. Set a different lan_port on the Configuration tab and restart the app. If the Relay was already paired, mind the port note above.
  • Logs: on the app’s Log tab.
  • Repeated RFC6762 lines in the log are harmless — see Help & commands.

Advanced: pairing and recovery codes

You normally don’t need this — the app finds the Relay on its own. If you do: the show-pairing (pairing code) and show-recovery (owner recovery code) commands run inside the Relay’s container. The image has no shell of its own, and Home Assistant has no “exec” button for apps. So you need a shell on the host, for example through the SSH & Web Terminal app with Protection mode off. The container name contains the repository’s ID, so the command finds it by substring:

docker exec "$(docker ps --filter name=poolpilot_relay --format '{{.Names}}')" \
  /usr/local/bin/poolpilot-relay show-pairing

For the recovery code, replace show-pairing with show-recovery.

The app runs on the host network so it can announce itself over mDNS, reach your pool controller on the local network and open the port for the PoolPilot app. Which other connections the Relay makes is listed under Technical & security.

Relay repository & docs