Intégration domotique TomTom Travel Time, gratuite et open source
Connecteur non officiel : durée de trajet et retard dû au trafic par l'API TomTom Routing.
Publiée par LM1LC3N7
- Appareils
- Version 0.1.1
- Nécessite Gladys >=5.1.0
- ★ 0
Connecteur non officiel, sans lien avec TomTom. Pour chaque trajet que vous saisissez, Gladys reçoit la durée avec le trafic en temps réel, le retard dû au trafic, la distance et la durée sans trafic, lus par l'API officielle TomTom Routing (Calculate Route) avec une clé gratuite.
Cette intégration n'a jamais été testée avec une vraie clé TomTom : elle suit la documentation officielle de TomTom et ses tests simulent les réponses de l'API. Vos retours sont les bienvenus.
Elle remplace l'idée d'une intégration Waze : l'API de Waze n'est accessible qu'en contournant sa protection anti-robots. Une intégration Mapbox Traffic de qleg existe déjà et fait la même chose avec Mapbox (fil n° 11024 du forum : https://community.gladysassistant.com/t/11024) : choisissez celle dont le fournisseur vous convient.
L'ergonomie (un trajet avec un nom, une origine et une destination, relevé périodiquement) s'inspire de l'intégration « Waze Travel Time » de Home Assistant (Apache-2.0). Aucun code n'en est repris.
Créer la clé gratuite
- Créez un compte sur https://my.tomtom.com/ (aucune carte bancaire demandée) et confirmez l'adresse e-mail.
- Ouvrez https://my.tomtom.com/keys : une clé nommée My first API key est créée d'office avec le compte et donne accès aux API, Routing comprise.
- Copiez-la (ou créez-en une nouvelle avec l'accès à la Routing API).
- Collez-la dans le champ Clé d'API TomTom de l'intégration.
L'offre gratuite permet 2 500 requêtes par jour, partagées par tous les usages de la même clé : si vous l'utilisez aussi ailleurs (un site, une autre application), ces requêtes comptent aussi, et l'intégration ne les voit pas. Utilisez de préférence une clé dédiée. Si votre compte est passé à l'offre payante « Pay As You Grow », les requêtes au-delà des 2 500 gratuites peuvent être facturées : l'intégration s'arrête d'elle-même à 2 500 par jour, mais pas les autres usages de la clé.
La clé est gardée par
Gladys dans sa base, jamais réaffichée, et envoyée seulement à
api.tomtom.com. Elle n'apparaît ni dans les journaux, ni dans les messages,
ni dans les statuts.
Saisir les trajets
Champ Trajets : un trajet par entrée, séparés par ;. Chaque trajet est
un nom, l'origine et la destination en latitude,longitude (point décimal),
séparés par | :
Travail | 48.85661,2.35222 | 48.89198,2.23881; École | 48.80000,2.30000 | 48.81000,2.31000
- Pour trouver des coordonnées : clic droit sur un point dans Google Maps ou OpenStreetMap, puis copier les deux nombres.
- Vingt trajets au maximum ; deux trajets ne peuvent pas avoir le même nom.
- Un trajet invalide est ignoré et nommé dans le statut, jamais avec ses
coordonnées : les nombres du nom sont masqués, et une entrée sans nom
utilisable apparaît par sa position (
#2). Le nom doit contenir au moins une lettre latine ou un chiffre et ne pas être lui-même des coordonnées. - Le nom identifie l'appareil : renommer un trajet crée un nouvel appareil (l'ancien garde son historique). Changer ses coordonnées garde l'appareil.
- Les adresses ne sont pas prises en charge pour l'instant (pas d'appel à l'API Search de TomTom) : donnez des coordonnées.
Options communes à tous les trajets :
- Véhicule : voiture, ou camion (routes et vitesses d'un camion, sans ses dimensions ni son poids).
- Éviter les péages, Éviter les autoroutes.
- Le départ est toujours maintenant, avec le trafic en temps réel.
Les appareils
Après l'enregistrement, chaque trajet apparaît dans l'onglet Découverte. Ajoutez-le pour obtenir :
| Fonction | Catégorie Gladys | Unité |
|---|---|---|
| Durée avec trafic | duration | minutes |
| Retard dû au trafic | duration | minutes |
| Distance | distance-sensor | km |
| Durée sans trafic | duration | minutes |
Les valeurs sont arrondies au dixième. La durée sans trafic est celle que
TomTom calcule sans aucun trafic (noTrafficTravelTimeInSeconds).
Le quota et la fréquence
Chaque relevé d'un trajet coûte une requête. Requêtes par jour = trajets × (minutes de la plage de relevé ÷ intervalle).
| Intervalle | Requêtes par trajet et par jour (toute la journée) | Trajets possibles |
|---|---|---|
| 5 min (minimum) | 288 | 8 |
| 10 min (défaut) | 144 | 17 |
| 15 min | 96 | 20 |
- Le statut de l'intégration affiche le nombre de requêtes par jour prévu après chaque enregistrement.
- Une configuration qui prévoit plus de 2 500 requêtes par jour est refusée : rien n'est lu et le statut dit quoi changer.
- L'intégration compte elle-même ses requêtes par jour UTC et n'en envoie
jamais plus de 2 500, relevés de scène et bouton de test compris. Le compte
survit à un redémarrage (fichier dans
/data). - Les relevés manuels (scènes et bouton de test) ont leur propre plafond par jour UTC : 100, et jamais plus que ce que les relevés prévus laissent des 2 500 (par exemple 2 500 − 2 448 = 52). Au-delà, l'action de scène rend les dernières valeurs sans requête. Une configuration qui prévoit exactement 2 500 requêtes ne laisse aucun relevé manuel : l'action de scène et le bouton de test ne rendent alors que les dernières valeurs.
- Un trajet n'est jamais relu plus vite que l'intervalle par les relevés périodiques, même après une erreur, une reconnexion ou un redémarrage ; un relevé manuel au plus toutes les 2 minutes par trajet.
- Si le dossier
/datan'est pas inscriptible, le statut le signale et les premiers relevés attendent un intervalle entier après chaque démarrage. - Une réponse 429 de TomTom suspend toutes les requêtes (Retry-After, sinon 1 minute doublée à chaque fois, entre 1 minute et 6 heures). Un 403 pour le quota du jour les suspend jusqu'au prochain minuit UTC (au moins 1 heure). Une clé refusée arrête les relevés, avec un nouvel essai toutes les 6 heures jusqu'à ce que la clé change. Ces pauses survivent à un redémarrage.
Plage de relevé (facultatif)
Pour économiser le quota, relevez les trajets seulement entre deux heures,
par exemple de 6 h à 20 h (14 heures : 84 requêtes par trajet à 10 minutes).
De 0 à 24 relève toute la journée ; une plage peut passer minuit (de 22 à 6).
Les heures sont celles du fuseau horaire indiqué (celui de votre Gladys,
Europe/Paris par défaut). Hors de la plage, les dernières valeurs restent
affichées et ne sont plus renvoyées.
Scène : rafraîchir un trajet maintenant
L'action de scène Rafraîchir un trajet TomTom maintenant relève le trajet
choisi tout de suite, sauf s'il l'a été il y a moins de 2 minutes, ou si
les relevés manuels du jour sont épuisés (voir plus haut) : elle rend alors ses
dernières valeurs sans requête. Plusieurs appels simultanés n'envoient qu'une
requête. Une scène en boucle consomme donc au plus les relevés manuels du jour,
jamais les relevés périodiques. Elle fonctionne aussi hors de la plage de
relevé. Sorties, utilisables par les actions suivantes : refreshed (relevé
maintenant ou non), age_minutes (ancienneté des valeurs), travel_time_minutes,
traffic_delay_minutes, distance_km, no_traffic_time_minutes. Le relevé
périodique suivant vient un intervalle entier plus tard.
Exemple : chaque matin de semaine à 7 h 30, rafraîchir « Travail », puis
envoyer un message si traffic_delay_minutes dépasse 10.
Bouton « Tester TomTom »
Relève le premier trajet (un relevé manuel, au plus une fois toutes les 2 minutes), puis affiche le nombre de requêtes prévu, celles utilisées aujourd'hui (dont les relevés manuels), et les dernières valeurs de chaque trajet.
Confidentialité
Les coordonnées de vos trajets (souvent votre domicile) et la clé sont
envoyées à TomTom (api.tomtom.com) à chaque relevé, et à personne d'autre.
Le fichier /data/tomtom-state.json garde le compte du jour, les pauses, une
empreinte de la clé (jamais la clé) et l'heure du dernier relevé de chaque
trajet.
Dépannage
- « TomTom a refusé la clé » : vérifiez la clé sur https://my.tomtom.com/keys et qu'elle a accès à la Routing API. Un 403 que TomTom n'explique pas (proxy, CDN) n'est pas pris pour un refus : une pause qui double à chaque fois.
- « aucun itinéraire entre les points » : un point est loin de toute route, ou les points ne sont pas reliés par la route ; réessayé toutes les heures au plus.
- Configuration refusée : augmentez l'intervalle, réduisez la plage horaire ou retirez des trajets.
- Journaux de l'intégration : depuis l'interface de Gladys.
Licence
Apache-2.0. TomTom est une marque de TomTom N.V. ; ce connecteur n'est ni affilié ni approuvé par TomTom.
Paramètres de configuration
Voici les paramètres demandés par TomTom Travel Time dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Temps de trajet TomTom dans Gladys | section | Non | Connecteur non officiel, sans lien avec TomTom. Pour chaque trajet saisi, un appareil donne la durée avec le trafic en temps réel, le retard dû au trafic, la distance et la durée sans trafic, lus par l'API officielle TomTom Routing. Créez un compte gratuit sur my.tomtom.com : sa clé « My first API key » convient (2 500 requêtes par jour, partagées par tous les usages de la clé). Chaque trajet coûte une requête par relevé : toutes les 10 minutes par défaut, 5 au minimum. Jamais testé avec une vraie clé TomTom pour l'instant. |
| Clé d'API TomTom | secret | Oui | Gardée par Gladys dans sa base, jamais réaffichée, envoyée seulement à api.tomtom.com. |
| Trajets | string | Non | Un trajet par entrée, séparés par « ; » : un nom, l'origine et la destination en « latitude,longitude » (point décimal), séparés par « | ». Vingt trajets au maximum. Un appareil garde son nom : renommer un trajet crée un nouvel appareil. |
| Intervalle de relevé de chaque trajet (minutes) | number | Non | Requêtes par jour = trajets × (minutes de la plage de relevé ÷ intervalle). Toute la journée : 144 par trajet à 10 minutes (17 trajets possibles), 288 à 5 minutes (8 trajets possibles). Le statut affiche le nombre prévu après l'enregistrement ; une configuration au-delà de 2 500 par jour est refusée. |
| Véhicule | select | Non | Camion : les routes et vitesses d'un camion, sans ses dimensions ni son poids. |
| Éviter les péages | boolean | Non | |
| Éviter les autoroutes | boolean | Non | |
| Plage de relevé (facultatif) | section | Non | Pour économiser le quota, ne relever les trajets qu'entre deux heures, par exemple de 6 à 20. De 0 à 24 relève toute la journée ; une plage peut passer minuit (de 22 à 6). Le départ est toujours maintenant. |
| De (heure) | number | Non | |
| Jusqu'à (heure) | number | Non | |
| Fuseau horaire de la plage | string | Non | Le fuseau de votre Gladys (Paramètres → Système). Nom IANA, ex. Europe/Brussels. |
Comment installer TomTom Travel Time dans Gladys
- Dans Gladys, ouvrez Intégrations : TomTom Travel Time 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/lm1lc3n7/gladys-tomtom-travel-time:0.1.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/LM1LC3N7/gladys-tomtom-travel-time.
TomTom Travel Time nécessite Gladys >=5.1.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
TomTom Travel Time 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 LM1LC3N7, 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