Intégration domotique Tractive, gratuite et open source
Traceurs GPS Tractive pour chiens et chats : maison ou non, distance, batterie, activité, buzzer.
Publiée par guim31
- Appareils
- Version 1.0.1
- Nécessite Gladys >=5.2.0
- ★ 0
Suivez le traceur GPS Tractive de votre chien ou de votre chat dans Gladys : est-il à la maison, à quelle distance, batterie, activité du jour, et le buzzer et la lumière pour le retrouver. Intégration non officielle, sans lien avec Tractive.
Développée sans le matériel : vos retours sont les bienvenus. L'intégration s'appuie sur l'API qu'utilise l'appli Tractive, telle que la lisent la bibliothèque libre aiotractive et l'intégration Home Assistant, et elle est testée sur leurs réponses enregistrées, pas sur un vrai traceur. Dites ce qui marche et ce qui ne marche pas dans les issues.
Présentation
- Un appareil par animal équipé d'un traceur Tractive sur votre compte : batterie, charge, distance de la maison, précision de la position, à la maison ou non, traceur en ligne, économie d'énergie, activité et repos du jour, objectif d'activité.
- Commandes : suivi en direct, buzzer et lumière (LED), si le traceur et l'abonnement le permettent.
- Temps réel : batterie, positions et interrupteurs arrivent au fil de l'eau, par le flux d'évènements qu'écoute l'appli Tractive.
- Déclencheurs de scène : Animal parti de la maison, Animal rentré à la maison, Batterie Tractive faible.
- Widget de tableau de bord Animal Tractive, avec boutons buzzer et lumière.
La position elle-même (latitude, longitude) n'est jamais enregistrée dans Gladys, qui n'a pas de fonctionnalité pour cela : Gladys garde la distance à votre maison, calculée par l'intégration.
Prérequis
- Gladys Assistant 5.2.0 ou plus récent.
- Un traceur Tractive avec un abonnement actif, et l'adresse e-mail et le mot de passe du compte Tractive auquel il appartient. Un compte créé avec « Se connecter avec Apple » ou Google n'a pas de mot de passe : définissez-en un d'abord dans l'appli Tractive (réglages du compte).
- Pour la distance et « à la maison » : une maison de Gladys avec une position (Paramètres → Maisons, placez la maison sur la carte).
- Gladys doit accéder à Internet (
graph.tractive.com,aps-api.tractive.com,channel.tractive.com).
Configuration
- Dans Gladys, ouvrez Intégrations → Installer depuis GitHub (ou le catalogue) et installez Tractive. L'écran d'installation demande à lire la position de vos maisons : elle sert à calculer la distance.
- Dans Configuration, renseignez :
- l'Adresse e-mail et le Mot de passe de votre compte Tractive ;
- la Maison depuis laquelle la distance est mesurée (vide : la première maison qui a une position) ;
- le Rayon de la maison (m) : en deçà de cette distance, l'animal est à la maison (100 m par défaut). Il est parti une fois 20 % plus loin (25 m au moins), pour que les sauts du GPS en bordure ne le fassent pas aller et venir ;
- le Seuil de batterie faible (%) : 15 % par défaut ;
- l'Intervalle de rafraîchissement (min) : le rafraîchissement complet (15 min par défaut, de 5 à 60) ;
- la Langue des noms de fonctionnalités : français par défaut, utilisée aussi pour les erreurs de commande.
- Enregistrez, puis utilisez Tester la connexion : il liste les animaux trouvés.
- Ouvrez l'onglet Découverte et ajoutez vos animaux.
L'intégration garde un jeton de session dans son propre volume /data : un
redémarrage ne refait pas de connexion. Le mot de passe reste dans la
configuration de Gladys.
Ce que fait chaque appareil
Un appareil par animal, au nom de l'animal. Les fonctionnalités dépendent du traceur : un traceur sans lumière n'a pas de fonctionnalité lumière, par exemple.
| Fonctionnalité | Ce qu'elle montre |
|---|---|
| Batterie | Niveau de batterie du traceur (%) |
| En charge | 1 pendant la charge (traceurs qui l'indiquent) |
| Distance de la maison | Distance entre la dernière position et la maison choisie (m) |
| Précision de la position | Incertitude de la dernière position, donnée par Tractive (m) |
| À la maison | 1 dans le rayon de la maison, 0 en dehors |
| Traceur en ligne | 0 quand le traceur ne remonte plus rien ou a été éteint |
| Économie d'énergie | 1 quand le traceur économise sa batterie (en veille sur le Wi-Fi maison) |
| Activité aujourd'hui | Minutes actives depuis minuit |
| Repos aujourd'hui | Minutes de calme depuis minuit (traceurs qui suivent le sommeil) |
| Objectif d'activité | L'objectif réglé dans l'appli Tractive (minutes) |
| Suivi en direct | Interrupteur : mode suivi en direct, une position toutes les secondes |
| Buzzer | Interrupteur : le traceur sonne, pour retrouver l'animal tout près |
| Lumière (LED) | Interrupteur : la lumière du traceur, pour voir l'animal dans le noir |
Commandes
Suivi en direct, Buzzer et Lumière (LED) sont envoyés au traceur par Tractive. Le buzzer et la lumière s'arrêtent d'eux-mêmes au bout d'un moment sur le traceur ; Gladys les affiche éteints dès que Tractive le dit. Le suivi en direct vide la batterie : coupez-le une fois l'animal retrouvé.
Une commande est refusée avec un message clair quand :
- le traceur dort dans sa zone d'économie d'énergie (Wi-Fi de la maison) : il n'y accepte pas de commande ;
- l'abonnement ou le modèle de traceur ne permet pas la fonction ;
- l'intégration n'est pas connectée à Tractive.
Rien ici n'ouvre, ne déverrouille ni ne désarme quoi que ce soit.
Widget de tableau de bord
Ajoutez le widget Animal Tractive à un tableau de bord et choisissez l'animal dans ses réglages. Il montre :
- la distance de la maison et la batterie (en direct) ;
- l'activité du jour face à l'objectif ;
- à la maison ou non, l'âge de la dernière position, et l'état du traceur (en ligne, hors ligne, économie d'énergie) ;
- un bouton buzzer et un bouton lumière (si le traceur les a). Une fonction en marche affiche une coche : appuyez de nouveau pour l'arrêter.
Déclencheurs de scène
| Déclencheur | Quand | Variables |
|---|---|---|
| Animal parti de la maison | L'animal dépasse le rayon de la maison plus la marge | nom de l'animal, distance (m) |
| Animal rentré à la maison | L'animal revient dans le rayon de la maison | nom de l'animal, distance (m) |
| Batterie Tractive faible | La batterie passe sous le seuil, une fois (de nouveau seulement après 5 points au-dessus), pas en charge | nom de l'animal, batterie (%) |
Chaque déclencheur peut se limiter à un animal (vide : n'importe lequel). Ils apportent aux fonctionnalités À la maison et Batterie ce qu'un état d'appareil ne dit pas : un évènement par vrai passage, le nom de l'animal pour un message, les positions moins précises que 500 m ignorées (une position par antenne relais ne fait jamais « partir » un chat endormi), rien sur la première valeur après un redémarrage.
Test de la connexion
Le bouton Tester la connexion se connecte à Tractive avec la configuration enregistrée et répond avec les animaux trouvés, l'état des mises à jour en temps réel, et l'absence éventuelle de maison située. C'est aussi lui qui relance la connexion après un mot de passe refusé, une fois corrigé.
Exemples de scènes
- Le chien a fugué : déclencheur Animal parti de la maison pour le chien → envoyer un message « {{triggerEvent.data.pet_name}} est parti, à {{triggerEvent.data.distance}} m » → allumer Suivi en direct.
- Bon retour : déclencheur Animal rentré à la maison → éteindre Suivi en direct et envoyer « {{triggerEvent.data.pet_name}} est rentré ».
- Recharger le traceur : déclencheur Batterie Tractive faible → envoyer « Rechargez le traceur de {{triggerEvent.data.pet_name}} ({{triggerEvent.data.battery}} %) ».
- Contrôle du soir : chaque soir à 22 h, si À la maison vaut 0 → envoyer un message.
Rafraîchissement et limites de l'API
Tractive n'offre pas d'API publique : l'intégration utilise celle de l'appli Tractive, comme Home Assistant, et veille à ne pas la surcharger.
- Le temps réel d'abord : une seule connexion longue au flux d'évènements de Tractive apporte batterie, positions et interrupteurs. Perdue, elle se reconnecte après 10 s, puis jusqu'à toutes les 5 minutes tant qu'elle échoue.
- Rafraîchissement complet toutes les 15 minutes (réglable, de 5 à 60) : traceur, batterie, position et activité des animaux ajoutés à Gladys seulement, une requête après l'autre, 2 secondes entre deux animaux. Le planificateur de Gladys n'est pas sollicité : l'intégration a son propre minuteur.
- Une seule connexion au compte par durée de vie du jeton : il est gardé
dans
/dataet renouvelé une heure avant d'expirer. Un mot de passe refusé n'est pas réessayé tant que vous ne changez pas la configuration ou n'appuyez pas sur Tester la connexion. - Une réponse « trop de requêtes » (429) est réessayée après 8 secondes, puis jusqu'à 60 secondes, trois fois au plus.
- Seules les valeurs qui changent sont envoyées à Gladys, plus un rappel toutes les 6 heures des valeurs inchangées.
Dépannage
- « Tractive refuse l'adresse e-mail ou le mot de passe » : vérifiez-les dans l'appli Tractive ou sur my.tractive.com. Un compte Google ou Apple a besoin d'un mot de passe défini dans l'appli Tractive.
- Aucun animal dans Découverte : l'animal doit avoir un traceur attribué sur votre compte ; un traceur partagé avec vous par un autre compte n'est pas listé. Appuyez sur Tester la connexion.
- Distance et « À la maison » restent vides : donnez une position à la maison (Paramètres → Maisons), ou choisissez une maison située dans la configuration.
- Une commande échoue : lisez le message ; dans la zone Wi-Fi de la maison, le traceur dort et n'accepte pas de commande.
- Les valeurs semblent anciennes : le traceur remonte moins souvent en
économie d'énergie ; vérifiez-le dans l'appli Tractive.
LOG_LEVEL=debugsur l'intégration montre chaque mise à jour dans ses journaux.
Limites
- Développée sans le matériel : testée seulement sur des réponses enregistrées de l'API.
- L'API est celle de l'appli Tractive, pas une API publique : Tractive peut la changer sans prévenir et casser l'intégration jusqu'à sa mise à jour.
- Pas de carte : Gladys n'a pas de fonctionnalité pour une position, seulement la distance à une maison.
- L'état des interrupteurs (buzzer, lumière, suivi en direct) n'est connu qu'une fois signalé par le flux en temps réel.
- L'activité est celle du jour, comptée par Tractive.
- Un seul compte Tractive par Gladys.
- Les zones (geofences), l'historique Tractive et les alertes santé de l'appli ne sont pas disponibles.
Paramètres de configuration
Voici les paramètres demandés par Tractive dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Votre compte Tractive | section | Non | L'adresse e-mail et le mot de passe que vous utilisez dans l'appli Tractive. Il faut un traceur avec un abonnement actif. Intégration non officielle, sans lien avec Tractive. |
| Adresse e-mail | string | Oui | |
| Mot de passe | secret | Oui | Conservé dans la configuration de Gladys seulement ; l'intégration garde un jeton de session dans son volume /data, jamais le mot de passe. |
| Maison | section | Non | La distance et « à la maison » sont calculées dans Gladys à partir de la position d'une maison de Gladys (Paramètres, Maisons). La position elle-même n'est jamais enregistrée dans Gladys. |
| Maison | select | Non | Vide : la première maison qui a une position. |
| Rayon de la maison (m) | number | Non | En deçà de cette distance, l'animal est à la maison. Il est parti une fois 20 % plus loin (25 m au moins), contre les sauts du GPS. |
| Seuil de batterie faible (%) | number | Non | Sous ce niveau, le déclencheur de scène « Batterie Tractive faible » se déclenche une fois. |
| Intervalle de rafraîchissement (min) | number | Non | Positions et batterie arrivent en temps réel. Ce rafraîchissement complet lit l'activité et couvre les moments sans temps réel. |
| Langue des noms de fonctionnalités | select | Non | Utilisée pour les appareils ajoutés désormais, et pour les erreurs de commande. |
Comment installer Tractive dans Gladys
- Dans Gladys, ouvrez Intégrations : Tractive apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/guim31/gladys-tractive:1.0.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/guim31/gladys-tractive.
Tractive nécessite Gladys >=5.2.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.
Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.
À propos des intégrations externes
Tractive est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par guim31, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation