How updates work
The Relay regularly asks the PoolPilot Cloud whether a newer version is available. If there is one, it downloads it and checks the signature. A small helper then installs the new version and restarts the Relay. If it doesn’t come up cleanly, the helper rolls back automatically to the version that ran before — so a bad update can’t leave you stranded.
Every update is cryptographically signed, and the key to check it is built into the program. So neither a hacked download server nor a hacked cloud can slip the Relay code — it only installs versions with a valid signature.
When updates happen
- Automatically, overnight: a ready update installs between 03:00 and 05:00 local time, at a fixed per-device time within that window — so not every Relay restarts in the same second. A new version usually arrives within a day.
- Right away, from the app: don’t want to wait? Open the Relay in the PoolPilot app and tap Update now — a waiting update installs immediately.
Controlling updates
In the app — recommended
The Relay’s page in the app has an automatic updates toggle:
- On (default): updates install by themselves overnight.
- Off: the Relay installs nothing on its own, but Update now still works — for example to pull in a security fix on your own schedule.
That way the device always stays updatable, which is why most people want this setting.
On the device — switch it off entirely
To take a device out of updates completely, set this in the config file:
UPDATE_DISABLED=1
and restart the Relay:
sudo systemctl restart poolpilot-relay
If an update seems stuck
That’s rare, because the helper rolls back on its own after a failure. What happened is in its log:
journalctl -u poolpilot-relay-updater
The surest way back is to run the installer again (command above). It reinstalls the current version, keeps your configuration and pairing, and does no harm to a healthy device.
Poll interval
The owner sets how often the Relay reads your pool controller right in the app (Settings → Relay), between 3 seconds and 10 minutes. No SSH, no restart: the Relay uses the new value from the next read on and keeps it across restarts and updates.
- The default is 60 seconds (or whatever
POLL_INTERVALsays in the config file). A value set in the app takes precedence. - The value belongs to the Relay, not to the household. A factory reset clears it.
- Going slower makes sense if your pool controller (or a hosting setup in front of it) reacts badly to frequent requests, or if your connection is metered.
- If the controller can’t be reached, the Relay tries again at the next scheduled read — never sooner.
How the interval affects alerts
Alerts are checked once per read, so the interval sets how quickly they react:
- A measurement alert (and its all-clear) fires only once the value has been out of (or back in) range for a number of reads in a row — 3 by default. That’s about 3 minutes at 60 seconds, 30 minutes at 10 minutes and 9 seconds at 3 seconds.
- The “no fresh data” alert fires after a set time without a successful read (90 minutes by default). With a slow interval it can arrive up to one interval later. If you set that time shorter than the interval, a single failed read is enough to trigger it — so keep it longer than the interval.
- Reminders about a problem that persists (every 6 hours by default) don’t depend on the interval.
A few background jobs wait for the next read too: an alert that couldn’t be delivered to the cloud, a change to your pool controllers the cloud doesn’t know about yet, and the first readings of a newly added controller. At 10 minutes, each of these can take up to 10 minutes.
Under the hood: the config file
Most people never need this — everything important is set in the app. On a Raspberry Pi or Linux box the configuration lives in one file:
/etc/poolpilot-relay/config
It’s a plain KEY=value file. Lines starting with # are comments; to enable a setting, remove the #. Restart the Relay after every change:
sudo systemctl restart poolpilot-relay
| Setting | Default | What it does |
|---|---|---|
CLOUD_BASE_URL |
https://api.poolpilot.eu |
The PoolPilot Cloud the Relay talks to. Written by the installer — only change it if support tells you to. |
LAN_LISTEN |
:8443 |
Address and port the app uses to reach the Relay at home. Only change it if 8443 is already taken on the device. |
POLL_INTERVAL |
60s |
The default poll interval, e.g. 30s or 2m. A value from the app takes precedence. |
UPDATE_DISABLED |
(unset) | 1 switches updates off entirely — see above. |
This is what the file looks like after installing:
# PoolPilot Relay agent configuration (systemd EnvironmentFile).
CLOUD_BASE_URL=https://api.poolpilot.eu
# LAN_LISTEN=:8443
# TUNNEL_LISTEN=127.0.0.1:8480
# POLL_INTERVAL=60s
# Self-update runs automatically at night; manage it from the PoolPilot app, or
# set UPDATE_DISABLED=1 here to opt this device out entirely.
# UPDATE_DISABLED=1
Advanced settings
A few more variables exist mainly for development, testing and support: TUNNEL_LISTEN, CTRL_FILTER_LISTEN, STATE_PATH, MDNS_DISABLED, MDNS_VERBOSE_LOGS, FRPS_AUTH_TOKEN, PAIR_URL_BASE and REPO_DL_BASE — plus RESTART_ON_RESET and HA_OPTIONS, which only the Home Assistant image sets. A normal install needs none of them, and set wrong they can stop the Relay from working. Only touch them if you know why.
The one you might actually need: MDNS_VERBOSE_LOGS=1 brings back the discovery library’s notices (see Help & commands).
How the Relay identifies itself
Every request the Relay sends — to your pool controller, to the PoolPilot Cloud and for update downloads — carries the header User-Agent: PoolPilot-Relay/<version> (+https://poolpilot.eu). That helps with pool controllers that sit on the internet behind a web firewall: many block Go’s default sender as a bot. A controller on your own network doesn’t care. When you open the controller’s web interface while you’re away, the Relay passes your app’s or browser’s own user agent through unchanged.