Intégration HACS pour contrôler une pompe à vitesse variable GoPool / GoPiscine AG1, IG1 ou IG2 dans Home Assistant — 100 % locale une fois configurée.
Ces pompes utilisent la puce Wi-Fi Tuya. Jusqu'ici, les contrôler dans Home
Assistant demandait de passer par localTuya et de récupérer soi-même le
device_id la local_key et les nombreux Data Point ID via un compte développeur Tuya IoT — des étapes
techniques et fastidieuses pour un nouvel utilisateur. Cette intégration
automatise cette récupération grâce à une simple connexion (par QR code)
à votre compte Smart Life / Tuya Smart, puis fonctionne ensuite
entièrement en local.
- Votre pompe doit déjà être ajoutée dans l'application Smart Life (ou Tuya Smart), tel que décrit dans le manuel d'instructions fourni avec la pompe.
- Votre pompe doit être connectée à votre réseau local en Wi-Fi et se
trouver sur le même sous-réseau que Home Assistant. Par exemple, si
votre Home Assistant est sur
192.168.1.2, l'adresse IP de votre pompe doit commencer par192.168.1.x. - Pas besoin de connaître l'adresse IP à l'avance — l'intégration la détecte automatiquement sur le réseau local lors de la configuration (avec possibilité de la corriger manuellement si la détection échoue). Une IP statique reste une bonne pratique, mais n'est plus indispensable : si l'IP de la pompe change par la suite, l'intégration essaie automatiquement de la retrouver sur le réseau local (voir Problèmes de connexion locale).
- Avoir votre téléphone ou votre tablette avec l'application Smart Life (ou Tuya Smart) à portée de main pendant la configuration de cette intégration.
- Home Assistant 2026.3.0 ou plus récent.
- HACS installé.
Cette intégration n'est pas (encore) dans le dépôt par défaut de HACS — ajoutez-la comme dépôt personnalisé :
Cliquez sur ce bouton:
Ou manuellement:
- HACS → menu (⋮) en haut à droite → Dépôts personnalisés.
- URL :
https://github.com/alray31/gopool-pump, catégorie Intégration. - Recherchez "GoPool Variable Speed Pump" dans HACS et installez-la.
- Redémarrez Home Assistant.
Réglages → Appareils et services → Ajouter une intégration → GoPool Variable Speed Pump. Le config flow vous guide à travers 3 étapes :
- Lier votre compte — entrez le code utilisateur de votre app Smart Life (Profil → Réglages → Compte et sécurité → Code utilisateur).
- Scanner le QR code affiché, avec l'app Smart Life.
- Choisir votre pompe dans la liste des appareils liés, et confirmer son adresse IP locale.
Chaque étape contient ses propres explications détaillées (avec captures animées) directement dans l'interface — inutile de les répéter ici.
⚠️ Important : cette étape de connexion au cloud Smart Life n'est nécessaire qu'une seule fois, pour récupérer automatiquement les identifiants locaux de la pompe. Ensuite, l'intégration ne communique plus jamais avec le cloud. Vous pouvez supprimer l'application Smart Life de votre téléphone si vous le souhaitez — mais ne supprimez jamais la pompe de votre compte Smart Life : cela changerait salocal_key. Si ça arrive quand même, pas besoin de tout reconfigurer : Home Assistant affichera une notification « Nouvelle authentification requise », qui relance automatiquement une connexion QR (identique à l'étape 2 ci-dessus) pour récupérer la nouvellelocal_keyet mettre à jour l'intégration existante.
| Type | Entité |
|---|---|
switch (contrôle) |
Power, Schedule, Quick Clean |
switch (configuration) |
No Load Protection, Winterized |
number (contrôle) |
Pump Speed |
number (configuration) |
Quick Clean Speed, Quick Clean Duration, Timeout Duration, Stage 1-4 Speed, Stage 1-4 Duration |
select (configuration) |
Stage 1-4 Start Time (heure + minute combinées en un seul sélecteur, valeurs limitées aux paliers de 10 minutes acceptés par la pompe) |
sensor |
Power Draw (W), Energy (kWh) — calculés à partir du RPM commandé et du modèle de pompe choisi à la configuration (voir Contribuer pour IG2) |
Seuls les DP (data points) confirmés fonctionnels localement sur ces pompes sont exposés — les DP inertes (fault, schedule, motor_operation_state, etc.) sont volontairement exclus.
- Communication locale via tinytuya, protocole Tuya version 3.5 (seule version confirmée sur cette ligne de pompes — fixe, pas un choix à faire à l'installation).
- Récupération des identifiants via tuya-device-sharing-sdk,
le même mécanisme que l'intégration Tuya officielle de Home Assistant
pour son propre login QR, en réutilisant l'identifiant client public de
Home Assistant (
HA_3y9q4ak7g4ephrvke) — pas un secret propre à ce projet, ni besoin de créer un compte développeur Tuya IoT. - Un polling local toutes les 3 secondes maintient l'état à jour, avec reconnexion automatique en cas d'échec ponctuel — même en cas d'échec ponctuel, les entités gardent leur dernière valeur connue au lieu de devenir indisponibles. La première tentative échouée d'une panne est journalisée en avertissement ; les répétitions suivantes de la même panne passent en debug (pas de spam dans les logs si la pompe reste injoignable longtemps), avec un dernier avertissement confirmant le retour en ligne.
- Winterized (switch, Configuration) : à activer quand la pompe est débranchée pour l'hiver (courant sur cette gamme de pompes, vendue exclusivement au Canada). Fait sauter complètement le polling réseau tant qu'il est actif — aucune tentative de connexion, aucune entrée de log — plutôt que d'essayer de joindre une pompe volontairement hors ligne toutes les 3 secondes pendant des mois. N'affecte jamais la pompe elle-même (ce n'est pas un DP, rien n'est envoyé à la pompe) ; l'état est mémorisé par Home Assistant et survit à un redémarrage — y compris un redémarrage de HA qui arrive pendant que la pompe est débranchée, auquel cas la configuration réussit quand même au lieu de rester bloquée en "Nouvel essai" indéfiniment. Important : à activer avant de débrancher la pompe pour l'hiver — si l'intégration redémarre alors qu'elle n'a encore jamais été activée avec la pompe hors ligne, elle reste bloquée en attente d'une première connexion réussie (voir Limitations connues).
- Les capteurs Power Draw (W) et Energy (kWh) sont calculés directement par l'intégration (interpolation d'une courbe RPM→W, puis intégration trapézoïdale dans le temps) — aucun template ou aide HA n'est nécessaire.
- Le mécanisme de QR login réutilise un identifiant client appartenant à Home Assistant. Cela fonctionne aujourd'hui (confirmé par la communauté), mais Tuya pourrait un jour limiter cet usage tiers sans préavis.
- Testé sur GoPool AG1 et IG1 (fonctionnement confirmé sur le terrain par plusieurs utilisateurs pour l'IG1) ; les DP de l'IG2 sont supposément identiques mais pas encore confirmés sur le terrain.
- Les capteurs Power Draw / Energy affichent indisponible pour IG2 : la courbe de calibration RPM→W n'existe pour l'instant que pour les AG1 et IG1 (voir Contribuer ci-dessous).
- L'entité Pump Speed ne descend pas sous 1150 RPM, même si la pompe peut physiquement atteindre 1000 RPM (manuellement au panneau, ou via un palier programmé/horaire). C'est une restriction du firmware du fabricant sur la commande de vitesse « en direct » spécifiquement (confirmé via le schéma Tuya officiel de la pompe) — toute valeur inférieure à 1150 envoyée à cette entité, en local ou via le cloud Tuya, est silencieusement ignorée par la pompe. Rien à voir avec cette intégration ni avec Home Assistant.
- Cette même restriction fausse les capteurs Power Draw / Energy
dans deux cas précis, puisqu'ils sont calculés à partir de la vitesse
rapportée par Pump Speed (DP103) :
- Quick Clean Speed accepte 1000-3450 RPM par incréments de 10, alors que Pump Speed n'accepte que des incréments de 50 à partir de 1150. Si la vitesse Quick Clean choisie n'est pas un multiple de 50 (ou est sous 1150), Pump Speed ne reflétera pas la vitesse réelle pendant le cycle, et Power Draw / Energy seront donc inexacts pour sa durée.
- Stage 1-4 Speed (les horaires programmés) acceptent 1000-3450 RPM. Un palier réglé sous 1150 RPM tournera bel et bien à cette vitesse sur la pompe, mais Pump Speed n'en sera jamais informé — Power Draw / Energy seront donc inexacts pendant toute la durée de ce palier. C'est d'ailleurs le cas d'usage le plus probable pour des vitesses sous 1150 RPM (filtration lente de nuit / hors-pointe pour économiser de l'énergie), donc à garder en tête si la précision d'Energy vous importe pour ces plages horaires.
- Idéalement, activez Winterized avant de débrancher la pompe, pendant qu'elle répond encore — le switch lui-même n'existe pas tant que la configuration n'a pas réussi au moins une fois. Si vous vous retrouvez quand même bloqué en « Nouvel essai » avec la pompe déjà débranchée (pas besoin de la rebrancher) : allez dans Paramètres → Appareils et services → GoPool Variable Speed Pump → Configurer (l'engrenage) — ce menu reste accessible même si l'intégration n'a jamais fini de démarrer — et cochez Hivernisée là. Valider relance automatiquement la configuration, qui réussit cette fois puisque l'option est déjà enregistrée avant même la première tentative de connexion.
Si la pompe est injoignable après configuration :
- Vérifiez que la pompe et Home Assistant sont sur le même sous-réseau (particulièrement si la pompe est derrière un pont/bridge Wi-Fi).
- Confirmez que le port 6668 n'est pas bloqué par un pare-feu ou une isolation VLAN entre les deux appareils.
- Si la pompe a été retirée/rajoutée dans Smart Life entretemps, sa
local_keya changé — inutile de retirer l'intégration : Home Assistant affichera automatiquement une notification de réauthentification pour cette intégration, qui relance une connexion QR pour récupérer la nouvellelocal_key. - Si c'est plutôt l'adresse IP de la pompe qui a changé (aucune IP statique assignée, ou routeur redémarré), l'intégration essaie de la retrouver automatiquement : après plusieurs cycles de sondage échoués consécutifs, elle relance un scan du réseau local, et si la pompe répond à une nouvelle adresse, la configuration est mise à jour toute seule (l'intégration se recharge brièvement, sans action de votre part). En attendant que ce scan aboutisse, ou pour corriger l'adresse tout de suite vous-même, un bouton Reconfigurer est aussi disponible : Réglages → Appareils et services → cette intégration → menu (⋮) → Reconfigurer, pour entrer la nouvelle IP manuellement.
Vous possédez une pompe IG2 ? Les capteurs Power Draw (W) et Energy (kWh) reposent sur une courbe de calibration RPM → Watts mesurée directement sur une pompe réelle. Pour l'instant, seule la courbe des AG1 et IG1 est disponible ; ces deux capteurs affichent donc « indisponible » sur IG2. Si votre pompe affiche la puissance directement sur son écran, votre contribution serait très appréciée : notez la valeur affichée (en watts) à au minimum ces deux paliers,
- Minimum RPM
- Maximum RPM
et idéalement aux mêmes RPM intermédiaires déjà mesurés pour la AG1 (1500, 2000, 2450 et 2850 RPM), pour une interpolation aussi précise que celle de la AG1. Ouvrez une issue GitHub avec le modèle exact de votre pompe et vos mesures (RPM → watts), et j'ajouterai la courbe de calibration correspondante — aucune réinstallation ne sera nécessaire de votre côté, juste une mise à jour via HACS.
Les retours, rapports de bogue et suggestions sont aussi les bienvenus via les mêmes issues GitHub de ce dépôt.
GoPool et GoPiscine sont des marques de commerce appartenant à leurs propriétaires respectifs. Leur usage ici (nom, logo) est un usage nominatif (« fair use ») à des fins d'identification uniquement, dans un contexte strictement non commercial — cette intégration est un logiciel libre et gratuit. Ce projet n'est ni affilié, ni approuvé, ni sponsorisé par GoPool / GoPiscine, et ne cherche en aucune façon à générer un revenu à partir de cette marque de commerce.
Voir LICENSE.
HACS integration to control a GoPool / GoPiscine AG1, IG1, or IG2 variable-speed pool pump in Home Assistant — fully local once configured.
These pumps use a Tuya Wi-Fi chip. Until now, controlling them in Home
Assistant meant going through localTuya and retrieving the device_id
, local_key and a large amount of Data Point ID yourself via a Tuya IoT developer account — technical
and tedious steps for a new user. This integration automates that
retrieval through a simple (QR-code) connection to your Smart Life /
Tuya Smart account, then runs entirely locally afterward.
- Your pump must already be added to the Smart Life app (or Tuya Smart), as described in the instruction manual that came with the pump.
- Your pump must be connected to your local network over Wi-Fi and be on
the same subnet as Home Assistant. For example, if your Home Assistant
instance is at
192.168.1.2, your pump's IP address must start with192.168.1.x. - No need to know the IP address ahead of time — the integration auto-detects it on your local network during setup (with a manual fallback field if detection doesn't find it). A static IP is still good practice, but no longer required: if the pump's IP changes later, the integration automatically tries to find it again on your local network (see Local connection issues).
- Have your phone or tablet with the Smart Life app (or Tuya Smart) within reach while setting up this integration.
- Home Assistant 2026.3.0 or newer.
- HACS installed.
This integration isn't (yet) in HACS's default store — add it as a custom repository:
Use this button:
Or manually:
- HACS → (⋮) menu in the top right → Custom repositories.
- URL:
https://github.com/alray31/gopool-pump, category Integration. - Search for "GoPool Variable Speed Pump" in HACS and install it.
- Restart Home Assistant.
Settings → Devices & services → Add integration → GoPool Variable Speed Pump. The config flow walks you through 3 steps:
- Link your account — enter your Smart Life app's user code (Profile → Settings → Account and Security → User Code).
- Scan the QR code shown, using the Smart Life app.
- Select your pump from the list of linked devices, and confirm its local IP address.
Each step has its own detailed explanations (with animated screen captures) built right into the interface — no need to repeat them here.
⚠️ Important: this Smart Life cloud connection step is only needed once, to automatically retrieve the pump's local credentials. Afterward, the integration never talks to the cloud again. You can safely delete the Smart Life app from your phone if you'd like — but never remove the pump from your Smart Life account: doing so would change itslocal_key. If that happens anyway, there's no need to reconfigure from scratch: Home Assistant will show a "Reauthentication required" notification that walks you through a fresh QR login (identical to step 2 above) to fetch the newlocal_keyand update the existing integration in place.
| Type | Entity |
|---|---|
switch (control) |
Power, Schedule, Quick Clean |
switch (configuration) |
No Load Protection, Winterized |
number (control) |
Pump Speed |
number (configuration) |
Quick Clean Speed, Quick Clean Duration, Timeout Duration, Stage 1-4 Speed, Stage 1-4 Duration |
select (configuration) |
Stage 1-4 Start Time (hour + minute combined into a single picker, restricted to the 10-minute steps the pump accepts) |
sensor |
Power Draw (W), Energy (kWh) — calculated from the commanded RPM and the pump model chosen during setup (see Contributing for IG2) |
Only data points (DPs) confirmed to work locally on these pumps are exposed — dead DPs (fault, schedule, motor_operation_state, etc.) are intentionally excluded.
- Local communication via tinytuya, Tuya protocol version 3.5 (the only version confirmed on this pump line — fixed, not a choice made during setup).
- Credential retrieval via tuya-device-sharing-sdk,
the same mechanism Home Assistant's own official Tuya integration uses
for its own QR login, reusing Home Assistant's public client ID
(
HA_3y9q4ak7g4ephrvke) — not a secret belonging to this project, and no need to create a Tuya IoT developer account. - Local polling every 3 seconds keeps state up to date, with automatic reconnection on a one-off failure — even on a failed poll, entities keep their last known value instead of going unavailable. The first failed attempt of an outage is logged as a warning; further repeats of the same outage drop to debug level (no log spam if the pump stays unreachable for a long stretch), with one final warning confirming it's back online.
- Winterized (switch, Configuration): turn this on when the pump is unplugged for the winter (common on this pump line, sold exclusively in Canada). Skips network polling entirely while on — no connection attempt, no log entry — instead of trying to reach an intentionally offline pump every 3 seconds for months. Never touches the pump itself (not a DP, nothing is sent to it); the state is remembered by Home Assistant and survives a restart — including one that happens while the pump is unplugged, in which case setup still succeeds instead of getting stuck retrying forever. Important: turn it on before unplugging the pump — if the integration restarts while it's never been turned on with the pump offline, it gets stuck waiting for a first successful connection (see Known limitations).
- The Power Draw (W) and Energy (kWh) sensors are computed directly by the integration (interpolating an RPM→W curve, then trapezoidal integration over time) — no HA template or helper needed.
- The QR login mechanism reuses a client identifier that belongs to Home Assistant. This works today (confirmed by the community), but Tuya could restrict this third-party usage at some point without notice.
- Tested on the GoPool AG1 and IG1 (field-confirmed working by several users for the IG1); IG2 DPs are presumed identical but not yet confirmed in the field.
- The Power Draw / Energy sensors show as unavailable on IG2: an RPM→W calibration curve currently exists only for the AG1 and IG1 (see Contributing below).
- The Pump Speed entity won't go below 1150 RPM, even though the pump can physically reach 1000 RPM (manually at the panel, or via a programmed stage/schedule). This is a manufacturer firmware restriction on the "direct" live speed command specifically (confirmed against the pump's official Tuya schema) — any value below 1150 sent to this entity, locally or via Tuya's cloud, is silently ignored by the pump. Nothing to do with this integration or Home Assistant.
- That same restriction throws off the Power Draw / Energy
sensors in two specific cases, since they're computed from the speed
reported by Pump Speed (DP103):
- Quick Clean Speed accepts 1000-3450 RPM in steps of 10, while Pump Speed only accepts steps of 50 starting at 1150. If the chosen Quick Clean speed isn't a multiple of 50 (or is below 1150), Pump Speed won't reflect the actual speed for the duration of the cycle, so Power Draw / Energy will be inaccurate for that stretch.
- Stage 1-4 Speed (the programmed schedule) accepts 1000-3450 RPM. A stage set below 1150 RPM does run at that speed on the pump, but Pump Speed never finds out — Power Draw / Energy will be inaccurate for the whole time that stage runs. This is arguably the most likely case for a sub-1150 speed in the first place (slow overnight/off-peak filtration to save energy), so worth keeping in mind if Energy accuracy during those windows matters to you.
- Ideally, turn Winterized on before unplugging the pump, while it's still reachable — the switch itself doesn't exist until setup has succeeded at least once. If you do end up stuck retrying with the pump already unplugged (no need to reconnect it): go to Settings → Devices & services → GoPool Variable Speed Pump → Configure (the gear icon) — this stays reachable even when the integration has never finished setting up — and check Winterized there instead. Saving automatically reloads the entry, which now succeeds since the option is already stored before the first connection attempt even runs.
If the pump is unreachable after setup:
- Confirm the pump and Home Assistant are on the same subnet (especially if the pump is behind a Wi-Fi bridge/extender).
- Confirm port 6668 isn't blocked by a firewall or VLAN isolation between the two devices.
- If the pump was removed and re-added in Smart Life in the meantime,
its
local_keyhas changed — no need to remove the integration: Home Assistant will automatically show a reauthentication notification for this integration, which relaunches a QR login to fetch the newlocal_key. - If instead the pump's IP address changed (no static IP assigned, or the router rebooted), the integration tries to find it automatically: after several consecutive failed poll cycles, it reruns a local network scan, and if the pump answers at a new address, the config entry is updated on its own (the integration briefly reloads — no action needed from you). While waiting for that scan to succeed, or to fix the address right away yourself, a Reconfigure option is also available: Settings → Devices & services → this integration → (⋮) menu → Reconfigure, to enter the new IP manually.
Do you own an IG2 pump? The Power Draw (W) and Energy (kWh) sensors rely on an RPM → Watts calibration curve measured directly on a real pump. Right now, only the AG1 and IG1 curve are available, so these two sensors show as "unavailable" on IG2. If your pump displays its power draw directly on its screen (like the AG1 does), your contribution would be very welcome: note down the displayed value (in watts) at least at these two points,
- Minimum RPM (minimum)
- Maximum RPM (maximum)
and ideally at the same intermediate RPM steps already measured for the AG1 (1500, 2000, 2450, and 2850 RPM), for interpolation as accurate as the AG1's. Open a GitHub issue with your pump's exact model and your measurements (RPM → watts), and I'll add the matching calibration curve — no reinstall needed on your end, just a HACS update.
Feedback, bug reports, and suggestions are also welcome via the same GitHub issues for this repository.
GoPool and GoPiscine are trademarks belonging to their respective owners. Their use here (name, logo) is nominative use ("fair use") for identification purposes only, in a strictly non-commercial context — this integration is free, open-source software. This project is not affiliated with, endorsed by, or sponsored by GoPool / GoPiscine, and does not seek to generate any revenue from this trademark in any way.
See LICENSE.