GarminDB - une base de données qui importe et analyse les données des connecteurs/montres Garmin

 (github.com/tcgoetz)
2 points par GN⁺ 2025-02-04 | 2 commentaires | Partager sur WhatsApp
  • GarminDB est un ensemble de scripts Python qui télécharge les données de santé et d’activité depuis Garmin Connect, les convertit en base de données SQLite et permet de les analyser et de les visualiser en graphiques en ligne de commande ou dans Jupyter Notebook
  • Les données récupérables automatiquement incluent les fichiers de suivi quotidien, le sommeil, le poids, la fréquence cardiaque au repos et les fichiers d’activité ; pour certains types d’activité, l’outil stocke aussi plus en détail les tours et entrées d’enregistrement
  • Les fichiers JSON et FIT téléchargés sont conservés, ce qui permet de recréer la base sans se reconnecter à Garmin Connect ni retélécharger les données
  • Le package peut être installé via PyPI ; après avoir configuré le compte Garmin Connect et la date de début dans GarminConnectConfig.json, on peut lancer la collecte et l’analyse complètes avec garmindb_cli.py --all --download --import --analyze
  • Grâce aux plugins, il est possible d’étendre la prise en charge aux applications Connect IQ et champs de données tiers ; après une mise à jour du schéma de la base, il peut être nécessaire de la reconstruire à partir des fichiers déjà téléchargés

Ce que fait GarminDB

  • GarminDB est un ensemble de scripts Python destiné à analyser et manipuler des données de santé dans une base de données SQLite
  • SQLite est utilisée comme base de données légère ne nécessitant pas de serveur
  • Fonctionnalités prises en charge :
    • Téléchargement et import automatiques des fichiers de suivi quotidien depuis la page « Daily Summary » de Garmin Connect
      • fréquence cardiaque sur toute la journée
      • activités
      • dénivelé positif/négatif
      • stress
      • minutes d’intensité
    • Extraction des données de sommeil, poids et fréquence cardiaque au repos depuis Garmin Connect, enregistrement au format JSON puis import dans la base
    • Téléchargement et import des fichiers d’activité depuis Garmin Connect
      • création d’une table récapitulative de toutes les activités
      • stockage plus détaillé pour certains types d’activité
      • inclusion des tours et des entrées d’enregistrement par activité
    • Synthèse des données dans une base contenant des tables récapitulatives quotidiennes, hebdomadaires, mensuelles et annuelles
    • Affichage des données sous forme de graphiques en ligne de commande ou via Jupyter Notebook
    • Conservation des fichiers JSON et FIT téléchargés afin de pouvoir recréer la base sans se reconnecter à Garmin Connect ni retélécharger les données
    • Export des activités au format TCX

Exploration et analyse des données

  • Une fois les données importées dans la base, il est possible de les explorer et de les exploiter avec les Jupyter Notebook fournis, des Jupyter Notebook tiers ou un navigateur SQLite
  • Exemples de navigateurs SQLite utilisables :
  • Les scripts créent des views de base dans la base afin de faciliter l’exploration des données

Installation et flux d’utilisation de base

  • Les versions de GarminDb sont publiées sur PyPI et nécessitent Python 3.x
  • Installation de la dernière version :
    • pip install garmindb
  • Configuration initiale :
    • copier GarminConnectConfig.json.example vers ~/.GarminDb/GarminConnectConfig.json
    • modifier le fichier pour ajouter le nom d’utilisateur et le mot de passe Garmin Connect
    • ajuster la date de début pour qu’elle corresponde à la période des données présentes dans Garmin Connect
  • Commande à exécuter au premier lancement pour télécharger toutes les données et créer la base :
    • garmindb_cli.py --all --download --import --analyze
  • Commande de mise à jour incrémentale pour ne récupérer et importer que les données récentes :
    • garmindb_cli.py --all --download --import --analyze --latest
  • Sauvegarde de la base, à lancer de temps à autre :
    • garmindb_cli.py --backup
  • Mise à jour vers la dernière version :
    • pip install --upgrade garmindb

Exécution depuis les sources

  • Les scripts de l’arborescence source sont automatisés avec Make
  • Procédure d’utilisation depuis les sources :
    • cloner le dépôt GarminDB en SSH
    • il faut utiliser SSH plutôt que HTTPS à cause des sous-modules
    • dans l’arborescence clonée, exécuter make setup pour préparer les scripts au traitement des données
    • copier GarminConnectConfig.json.example vers ~/.GarminDb/GarminConnectConfig.json, puis définir le compte et la date de début
    • pour le premier import et traitement des données, exécuter une fois make create_dbs
    • ensuite, pour maintenir les données locales à jour, exécuter simplement make périodiquement
  • Davantage d’informations d’utilisation sont disponibles dans la documentation d’usage du wiki

Jupyter Notebook et plugins

  • Les Jupyter Notebook destinés à analyser les données de la base se trouvent dans le répertoire Jupyter de l’arborescence source
  • Des liens vers des Notebook soumis par les utilisateurs sont disponibles sur la page des projets liés du wiki
  • Les plugins permettent d’étendre les types de données traités et enregistrés dans la base
  • GarminDb inclut déjà plusieurs plugins pour traiter les données d’applications Connect IQ et de champs de données tiers
  • Plus d’informations sur les plugins sont disponibles dans GarminDbPlugins

Points d’attention en exploitation

  • Après une mise à jour du code, une exception de version de base peut survenir
    • cela signifie que le schéma de la base a été mis à jour
    • il faut reconstruire la base avec garmindb_cli.py --rebuild_db
    • la base est recréée à partir des fichiers de données précédemment téléchargés, sans retélécharger toutes les données depuis Garmin
  • Les scripts ont été développés sur MacOS et le projet accepte les retours d’usage sur d’autres plateformes ainsi que les correctifs
  • Une fois la mise à jour de la base terminée, un récapitulatif des données de la base est enregistré dans stats.txt
    • il inclut les plages de dates des fichiers de suivi quotidien et des activités téléchargés
    • il inclut le nombre d’enregistrements pour le suivi quotidien, les activités, le sommeil, la fréquence cardiaque au repos, le poids, etc.
    • il peut servir à vérifier que toutes les données ont bien été téléchargées depuis Garmin Connect
    • en cas de manque, il faut ajuster la date dans GarminConnectConfig.json et relancer le téléchargement
  • Dans GarminConnectConfig.json, l’élément steps de course_views est une liste d’identifiants de parcours pour lesquels créer des vues de base
    • ces vues permettent de comparer toutes les activités d’un même parcours

Signalement de bugs et contribution

  • En cas de problème, ouvrir un bug dans l’onglet Issues du projet
  • Exécuter make bugreport ou garmindb_bug_report.py, puis joindre le fichier bugreport.txt au signalement
  • Au-delà des erreurs affichées à l’écran, l’un des premiers endroits où chercher des informations supplémentaires est le fichier de log garmindb.log
  • Si un problème survient avec un fichier de données spécifique, envisager de partager ce fichier pour faciliter le débogage et l’ajout de support
  • Les contributions doivent être soumises via une Pull Request ciblant la branche develop
  • Avant soumission, exécuter make flake8 à la racine du projet et corriger toutes les erreurs

À lire aussi

2 commentaires

 
GN⁺ 2025-02-04
Avis de Hacker News

  • Ceux qui veulent l’utiliser devraient savoir qu’il s’appuie sur Garth (https://github.com/matin/garth) pour l’authentification.
    C’est une authentification assez hacky : elle contourne la connexion par formulaire web en se faisant passer pour l’app Android, et même comme une instance unique.
    Garmin est une entreprise vraiment pénible à intégrer, et je ne comprends pas pourquoi ils verrouillent autant les choses. Même quand on obtient un accès à l’API officielle ou au SDK, la qualité est généralement médiocre.

    • Le matériel Garmin est très fiable, donc je l’utilise, mais le marché a cruellement besoin d’une alternative open source.
      Garmin a subi une attaque par ransomware en 2020, ses services ont été indisponibles pendant plusieurs jours et l’entreprise a fini par payer 10 millions de dollars, sans vraiment traiter le problème correctement.
    • Garmin, ce n’est rien comparé à Strava. Si vous vous intégrez à Strava et que l’utilisateur révoque la connexion, vous devez supprimer toutes les données provenant de Strava, sinon vous risquez de perdre votre accès à l’API.
      Les raisons pour lesquelles les entreprises verrouillent les données sont toujours à peu près les mêmes. L’utilisateur est le produit, et elles veulent le garder captif pour continuer à se nourrir de ses données.
      Quand un concurrent sort un meilleur appareil, il ne faut pas que l’utilisateur puisse partir avec ses données, sinon il faudrait se battre davantage sur la concurrence.
      Garmin a historiquement été très paresseux tant que personne ne lui faisait vraiment concurrence. Quand le marché des smartwatches s’est emballé, les fonctionnalités et les meilleurs modèles sont soudain arrivés en masse ; les compteurs de vélo, eux aussi, restaient des années sans mise à jour jusqu’à ce que Wahoo, Bryton, Coros et Hammerhead viennent frapper à la porte.
      Strava est similaire. Avant, l’entrée et la sortie des données étaient assez libres, puis ils ont tout verrouillé, au point que l’export des données est devenu presque impossible.
    • L’intégration Garmin est-elle encore si mauvaise ? Il y a quelques années, quand j’avais créé une intégration pour faire des posters à partir de données GPS de parcours, c’était à peu près comparable à Strava ou RunKeeper, mais leurs conditions d’utilisation ont ensuite changé et ils demandaient environ 10 000 dollars pour se connecter.
      Aujourd’hui, ça semble gratuit, mais il faut toujours une approbation.
      https://developer.garmin.com/gc-developer-program/overview/
      Pour utiliser ses données à titre personnel ou les envoyer d’un service à un autre, tapiriik était bien. Je ne l’ai pas utilisé depuis des années, donc je ne sais pas si c’est toujours le cas.
      https://tapiriik.com/
    • Mon expérience est complètement inverse. J’utilise l’API InReach depuis plusieurs années : le prix est raisonnable, il n’y avait aucun coût supplémentaire en dehors de l’abonnement InReach, et l’accès a été facile — après avoir envoyé un e-mail, j’ai reçu la documentation de l’API et les accès en un à trois jours.
      La conception et la stabilité étaient aussi très bonnes. Le système de reporting d’événements/points basé sur des callbacks était robuste ; même si mon code cassait ou devenait instable, Garmin réessayait de son côté, et l’interface de debug permettant de voir ce qui se passe en cas d’échec de webhook était excellente. Le support, sans être rapide, était de tout premier ordre.
      Au début de l’implémentation, il y avait un bug étrange dans les webhooks : tous les événements arrivaient deux fois, et l’un des deux avait son horodatage d’événement tronqué en entier à la seconde. En regardant le user-agent, on voyait aussi que celui tronqué provenait d’un logiciel plus ancien de quelques versions.
      J’ai envoyé cette analyse par e-mail ; environ 12 heures plus tard, c’était corrigé, puis encore une douzaine d’heures plus tard un vrai ingénieur m’a répondu pour me remercier de l’explication et me dire pourquoi et comment c’était arrivé, ainsi que ce qui avait été corrigé.
      InReach, en particulier l’API InReach Professional, est certes plus proche d’un produit professionnel que d’un pur produit grand public, mais Garmin sait faire ce genre de choses.
    • Je pense que la partie grand public/retail de Garmin est catastrophique. Récemment, j’ai commandé un HRM sur le site de Garmin ; le statut de la commande est resté sur « ordered » pendant plus d’une semaine, puis j’ai fini par annuler et l’acheter sur Amazon.

  • Un ami m’a parlé d’Intervals (https://intervals.icu) pour geekery de données Garmin/Strava, et je l’utilise avec pas mal de satisfaction.
    En tant que rameur, j’ai apprécié de pouvoir générer des rapports avec des métriques liées à l’aviron, et pas seulement les indicateurs habituels de vélo/course à pied.

    • C’est une bonne app, je ne connaissais pas ce service. Pour le vélo, ça a l’air assez sophistiqué.
      En revanche, récemment, j’ai eu un autre problème en essayant de suivre des entraînements Hyrox. Même avec une epix gen 2 (800 euros), c’était difficile de les suivre correctement ; on peut définir des séances, mais c’est trop fastidieux et ça ne marche pas très bien.
      J’ai fini par créer ma propre app. Elle fonctionne sur toutes les montres Garmin, permet de définir des entraînements fixes puis d’analyser les performances pour chaque exercice.
      https://multisports.creatness.studio — j’attends encore l’approbation de soumission sur l’app store de Garmin, mais on peut déjà la télécharger et la sideload sur une montre Garmin, et je l’utilise moi-même depuis plusieurs semaines.
    • Je l’avais essayé il y a quelques années, et je me souviens avoir été frustré par la manière dont il imposait un format d’intervalles de course.
      Quand on enregistrait une activité par intervalles, il me semble qu’il voulait un format où les phases de repos intermédiaires n’étaient pas enregistrées avec le reste, ce qui était gênant.
      Correction : je me trompais. Je confondais avec runalyze, ce n’était pas Intervals.icu.
    • Intervals.icu est excellent, et mérite largement d’être soutenu financièrement. C’est plaisant de voir l’évolution de ses progrès au fil du temps, et j’aime aussi pouvoir personnaliser les graphiques.
    • Je suis parti immédiatement en voyant la phrase : « nous pouvons utiliser vos données personnelles pour vous envoyer des newsletters, des communications marketing ou promotionnelles et d’autres informations susceptibles de vous intéresser ».

  • Pour extraire toutes les données brutes de Garmin Connect sous forme de fichiers FIT, il suffit d’utiliser l’export de données (https://support.garmin.com/en-US/?faq=W1TvTPW8JZ6LfJSfK512Q8)
    Il existe aussi de bonnes bibliothèques open source pour lire et interpréter ces fichiers. Par exemple https://github.com/polyvertex/fitdecode pour Python, ou https://github.com/tormoder/fit pour Go
    Si vous voulez obtenir les données actuelles, vous pouvez connecter l’appareil (montre, compteur de vélo, etc.) à l’ordinateur, le monter comme système de fichiers, puis récupérer les fichiers .FIT actuels
    J’avais commencé un projet perso qui faisait exactement ça, mais je l’ai abandonné en cours de route
    https://github.com/jo-m/garmin-disconnect

    • As-tu déjà essayé d’exporter toutes les données brutes depuis Garmin ? J’ai 15 ans d’historique, et ce dump ne contenait aucun fichier fit/gpx/tcx
      Il y avait 196 fichiers json, 228 Mo au total, et tout n’était que des résumés de haut niveau
      Ce n’est qu’en utilisant l’une de ces bibliothèques d’export tierces un peu hacky que j’ai pu récupérer les vrais fichiers fit : 5708 fichiers pour 373 Mo. Et même là, il y avait des fichiers manquants, vides et en double, ce qui était très frustrant
      J’en ai tiré la leçon qu’il ne faut pas croire que l’export d’un service en ligne sera complet ou dans le format attendu. Si c’est un service dont vous dépendez, je recommande fortement de faire réellement l’export et de vérifier que les données voulues s’y trouvent

  • Garmin devrait vraiment adopter ce mouvement. Si l’alternative consiste à dépendre d’une app smartphone, Garmin finira par se faire distancer à long terme
    L’un des grands avantages d’acheter du matériel dédié comme un compteur de vélo Garmin, c’est d’avoir davantage de contrôle sur ses données

    • J’aimerais que Garmin améliore son SDK et sa documentation. J’ai fait une petite app pour mon usage personnel, et ça m’a donné beaucoup plus de respect pour les gens qui créent des apps pour montres Garmin
      La documentation est incroyablement mauvaise, il faut découvrir la moitié des choses par essais et erreurs, et je ne sais toujours pas comment builder et tester sur d’autres montres que la mienne
      J’aurais volontiers peaufiné l’app et l’aurais publiée sur le store, et je pense qu’elle pourrait être utile à certaines personnes, mais l’effort nécessaire semble largement supérieur à la valeur apportée
    • J’ai deux appareils Garmin : une montre et un compteur de vélo, tous deux connectés à la même app et qui agrègent les données dans un seul compte Garmin Connect
      Je m’attendais à une certaine synergie, mais il n’y en a aucune. Si j’enregistre la même activité avec les deux appareils en même temps, ça ne crée que des doublons. Par exemple, la distance retenue est la somme des distances mesurées par les deux appareils
      C’est même pire que d’utiliser deux appareils de marques différentes
    • L’app WorkOutDoors et Strava donnent toutes deux un accès complet aux données gpx
    • On peut tout consulter et télécharger depuis le site web

  • Existe-t-il des appareils similaires qui n’entravent pas les utilisateurs souhaitant accéder à leurs propres données ?

    • Quand Apple verrouille tout, le marketing d’Apple, ou les gens qui s’y laissent prendre, répondent que « c’est bien parce que c’est sûr » ; quand Garmin/Google/les autres le font, ça devient « c’est idiot, je devrais pouvoir utiliser ce qui m’appartient »

  • Je suis toujours surpris de voir à quel point beaucoup de données sont enfermées dans le vieux SDK de Garmin
    Par exemple, le format de fichier FIT, utilisé pour créer des programmes d’entraînement sur tous les compteurs de vélo, n’est pris en charge que par une ou deux apps
    Au final, c’est peut-être de notre faute, et il faudrait peut-être construire directement par-dessus le SDK

    • Le site Garmin Connect semble bien fonctionner pour créer des entraînements structurés. Il peut aussi se synchroniser avec TrainingPeaks. De quoi d’autre aurait-on besoin ?
      En dehors de la planification d’entraînements, il y a bien plus de deux apps qui lisent ou écrivent des fichiers FIT. J’en ai moi-même créé une

  • Le problème n’est pas seulement que l’accès à l’API est difficile : Garmin n’écoute pas la communauté
    Par exemple, il est impossible de filtrer les activités sans équipement. Comme j’oublie parfois d’ajouter un vélo ou des chaussures, un tel filtre serait utile
    Ajouter ce filtre dans l’app ou sur le site Connect serait très simple, mais comme il n’y a pas de community manager, il est impossible de participer
    S’ils avaient un tracker public permettant aux gens de demander des fonctionnalités, Garmin pourrait les examiner, améliorer son produit et gagner plus d’argent

  • J’ai acheté cette semaine une nouvelle Garmin Vivoactive5, parce que mon ancienne Vivoactive3 est tombée en panne
    Pour l’instant j’en suis plutôt satisfait, mais je l’ai achetée en sachant que l’API de Garmin et ses possibilités ne sont pas du tout optimales
    J’ai aussi envisagé l’Apple Watch Series 10, mais j’ai fini par renoncer : la batterie ne tient pas plus de 1,5 jour, je n’ai pas vraiment l’usage de la messagerie ou des apps intelligentes en dehors des fonctions santé, et elle coûtait deux fois plus cher que la Vivoactive
    J’aimerais qu’il existe une montre ouverte, hackable, avec une bonne API, permettant aussi d’auto-héberger son tableau de bord, et avec des apps correctes. J’ai le sentiment qu’il existe un marché pour des gens comme moi. Peut-être que le retour de Pebble pourra combler ce vide

  • J’espérais que ce serait une méthode pour récupérer et suivre les données directement depuis l’appareil, mais d’après ce que je vois, ça communique avec l’API Connect, donc on reste lié à l’app officielle

    • Les données d’activité ne sont que des fichiers FIT accessibles en USB
    • J’ai abandonné cette approche, et j’utilise maintenant http://www.rungap.com/ pour extraire les données Garmin via l’API et les mettre dans le stockage iCloud
      On peut aussi choisir le format de fichier entre gpx, fit et tcx

  • J’ai configuré ça il y a quelques mois. Les données sont stockées dans une base sqlite locale, et je lance un script une fois par jour pour récupérer les nouvelles données
    Ça prend pas mal de temps, plus que je ne l’aurais cru. Comme la montre ne met qu’environ une seconde à synchroniser les mêmes données avec le téléphone, il doit y avoir de grosses inefficacités en interne. Je n’ai pas encore eu l’occasion d’aller voir ça en détail
 
qor0923 17 시간 전

Merci. Grâce à vous, j’ai pu l’appliquer correctement.