Pairing

Most of the time it’s one tap: open the PoolPilot app on a phone on the same network as the Relay. The app finds it automatically and offers “Set up relay” — just follow the prompts.

Pairing deliberately only works on your home network: to add a Relay to your household, you have to be there.

If the app doesn’t find the Relay

Show the pairing code right on the Relay:

sudo poolpilot-relay show-pairing

This prints three things:

a QR code — scan it with the PoolPilot app or simply your phone’s camera,
the same link as text — open it on your phone (tap it or open it in the phone’s browser) and it opens the PoolPilot app,
the Relay’s fingerprint — that’s what you type into the app by hand.

The command changes nothing on the Relay and is always safe to run again. It only needs sudo because it reads the Relay’s private files. If your Relay runs in Home Assistant, the matching command is on the Home Assistant page.

Owners and members

Every paired phone has a role in the household, fixed when it pairs:

The owner is the phone that set the Relay up — and any phone that took the owner role back with a recovery code.
A member is a phone that joined through an invite from the owner.

Everyone in the household sees the pool, its readings and alerts, operates it, and uses the pool controller’s web interface including the settings it offers there. And everyone can remove themselves from the Relay.

Only the owner changes the Relay itself:

adding, changing or removing pool controllers, and renewing a controller’s remote link,
changing alert rules,
removing another phone,
installing updates, switching automatic updates on or off, and setting the poll interval (see Updates & settings),
resetting the household or the Relay.

If a member phone asks for one of these, the Relay refuses and nothing changes.

Through the Relay you share your pool with up to 10 devices — iPhone and Android mixed, Pro features included. This works with every supported pool controller, the VIOLET too. The owner invites the others from the PoolPilot app; each invited phone joins as a member.

Lost owner access

If no phone can act as the owner any more — say the owner’s phone is gone — create a one-time recovery code on the Relay and scan it with the phone that should become the owner:

sudo poolpilot-relay show-recovery

The code is valid for a few minutes and once only.
It only works on a Relay that has been paired before. A brand-new Relay you just pair as usual.
Whoever can run this command already has full access to the device — that’s exactly the trust this rests on.

When Pro lapses

If your household’s Pro subscription is no longer active, the Relay parks its tunnel: it pauses remote access through the Relay and keeps everything else — pairing, settings and credentials. It checks again regularly, and right away when you open the app at home. Once Pro is active again it resumes by itself — no need to pair again.

Under the hood: when the Relay forgets its household

The Relay writes a relay lifecycle: line to its log for each change. These are the cases:

state=suspended (“parking the tunnel; credentials kept”): the subscription isn’t active — see above.
state=unknown: the PoolPilot Cloud didn’t recognise the Relay several times over a few hours. The Relay pauses remote access the same way and keeps checking. If it doesn’t clear up, the household most likely no longer exists in the cloud. Pairing again won’t work while the old phones are still paired, so do a factory reset and set the Relay up again.
“household deleted in the cloud”: the household was deleted, for example with “Delete all my data” in the app. The Relay forgets everything that belonged to it (paired phones, pool controllers, cloud credentials) but keeps its own identity — the QR code and fingerprint stay the same. Just set it up again from the app.
“household reset over the LAN API”: the same, only right away. If you delete your data while your phone is on the same network as the Relay, the app asks the Relay directly. If that doesn’t work at that moment, the Relay still notices by itself — within minutes with a pool controller set up, within about a day without one.

The Relay only gets a new identity — for example before you give the device away — through a factory reset.