GarminDB - DB para importar y procesar datos desde conectores/relojes Garmin

 (github.com/tcgoetz)
2 puntos por GN⁺ 2025-02-04 | 2 comentarios | Compartir por WhatsApp
  • GarminDB es una colección de scripts de Python que descarga datos de salud y actividad de Garmin Connect, los procesa en una base de datos SQLite y permite analizarlos y graficarlos desde la línea de comandos o en Jupyter Notebook
  • Los datos que puede importar automáticamente incluyen archivos de monitoreo diario, sueño, peso, frecuencia cardiaca en reposo y archivos de actividad; algunos tipos de actividad también guardan con más detalle laps y entradas de registros
  • Conserva los archivos JSON y FIT descargados, por lo que es posible reconstruir la base de datos sin volver a entrar a Garmin Connect ni volver a descargar todo
  • Puede instalarse desde PyPI y, tras configurar la cuenta de Garmin Connect y la fecha de inicio en GarminConnectConfig.json, se puede iniciar la recolección y el análisis completos con garmindb_cli.py --all --download --import --analyze
  • Mediante plugins puede ampliar el procesamiento de apps y campos de datos de Connect IQ de terceros, y después de actualizar el esquema de la DB puede ser necesario reconstruirla a partir de los archivos ya descargados

Qué hace GarminDB

  • GarminDB es una colección de scripts de Python para procesar y manipular datos de salud en una base de datos SQLite
  • SQLite se usa como una base de datos ligera que no requiere servidor
  • Funciones compatibles:
    • Descarga e importa automáticamente archivos de monitoreo diario desde la página “Daily Summary” de Garmin Connect
      • Frecuencia cardiaca durante todo el día
      • Actividades
      • Ascenso/descenso
      • Estrés
      • Minutos de intensidad
    • Extrae datos de sueño, peso y frecuencia cardiaca en reposo desde Garmin Connect, los guarda como archivos JSON y los importa a la DB
    • Descarga e importa archivos de actividad desde Garmin Connect
      • Crea una tabla de resumen de todas las actividades
      • Algunos tipos de actividad almacenan datos más detallados
      • Incluye laps y entradas de registros por actividad
    • Resume los datos en una DB con tablas de resumen diarias, semanales, mensuales y anuales
    • Grafica los datos desde la línea de comandos o con Jupyter Notebook
    • Conserva los archivos JSON y FIT descargados para poder reconstruir la DB sin volver a entrar a Garmin Connect ni volver a descargar los datos
    • Puede exportar actividades como archivos TCX

Exploración y análisis de datos

  • Una vez que los datos están en la DB, se pueden explorar y trabajar usando los Jupyter Notebook incluidos, Jupyter Notebook de terceros o un navegador de SQLite
  • Algunos navegadores de SQLite que se pueden usar son:
  • Los scripts crean views básicas dentro de la DB para facilitar la exploración de datos

Instalación y flujo de uso básico

  • Las versiones de GarminDb están en PyPI y requieren Python 3.x
  • Instalar la versión más reciente:
    • pip install garmindb
  • Configuración inicial:
    • Copiar GarminConnectConfig.json.example a ~/.GarminDb/GarminConnectConfig.json
    • Editar el archivo para agregar el usuario y la contraseña de Garmin Connect
    • Ajustar la fecha de inicio según las fechas de los datos presentes en Garmin Connect
  • Comando para descargar todos los datos y crear la DB al empezar por primera vez:
    • garmindb_cli.py --all --download --import --analyze
  • Comando de actualización incremental para descargar e importar solo los datos más recientes:
    • garmindb_cli.py --all --download --import --analyze --latest
  • De vez en cuando, hacer un respaldo de la DB con el siguiente comando:
    • garmindb_cli.py --backup
  • Actualizar a la versión más reciente:
    • pip install --upgrade garmindb

Ejecutarlo desde el código fuente

  • Los scripts del árbol de código fuente están automatizados con Make
  • Procedimiento de uso desde el código fuente:
    • Clonar el repositorio de GarminDB usando SSH
    • Debe usarse SSH y no HTTPS debido a los submódulos
    • En el árbol clonado, ejecutar make setup para preparar los scripts para procesar datos
    • Copiar GarminConnectConfig.json.example a ~/.GarminDb/GarminConnectConfig.json y configurar la cuenta y la fecha de inicio
    • Para la primera importación y procesamiento de datos, ejecutar una vez make create_dbs
    • Después, para mantener actualizados los datos locales, basta con ejecutar make periódicamente
  • Hay más instrucciones de uso en la documentación de uso del wiki

Jupyter Notebook y plugins

  • Los Jupyter Notebook para analizar los datos de la base de datos están en el directorio Jupyter del árbol de código fuente
  • Los enlaces a notebooks enviados por usuarios están en la página de proyectos relacionados del wiki
  • Los plugins permiten ampliar los tipos de datos que se procesan y almacenan en la DB
  • GarminDb ya incluye varios plugins para procesar datos de apps y campos de datos de Connect IQ de terceros
  • Más detalles sobre plugins están en GarminDbPlugins

Puntos a tener en cuenta en operación

  • Después de una actualización de código puede ocurrir una excepción de versión de DB
    • Esto significa que se actualizó el esquema de la DB
    • Debe reconstruirse la DB con garmindb_cli.py --rebuild_db
    • La DB se vuelve a crear a partir de los archivos de datos descargados previamente, sin volver a descargar todos los datos desde Garmin
  • Los scripts fueron desarrollados en MacOS y se acepta información de uso o parches para otras plataformas
  • Cuando termina la actualización de la base de datos, se guarda un resumen de datos de la DB en stats.txt
    • Incluye el rango de fechas de los archivos de monitoreo diario y las actividades descargadas
    • Incluye el número de registros de monitoreo diario, actividades, sueño, frecuencia cardiaca en reposo, peso, etc.
    • Puede usarse para verificar si se descargaron todos los datos desde Garmin Connect
    • Si falta algo, se ajusta la fecha en GarminConnectConfig.json y se vuelve a ejecutar la descarga
  • En GarminConnectConfig.json, el elemento steps de course_views es una lista de IDs de rutas para las que se crearán views de DB por ruta
    • Con esas views de DB se pueden comparar todas las actividades de la misma ruta

Reportes de errores y contribuciones

  • Si hay un problema, se debe registrar un bug en la pestaña Issues del proyecto
  • Ejecutar make bugreport o garmindb_bug_report.py e incluir el bugreport.txt generado en el reporte de error
  • Además de los errores mostrados en pantalla, uno de los primeros lugares para revisar información adicional es el archivo de logs garmindb.log
  • Si el problema ocurre con un archivo de datos específico, conviene considerar compartir ese archivo para depuración y para agregar soporte
  • Las contribuciones deben enviarse como Pull Request dirigidos a la rama develop
  • Antes de enviar, se debe ejecutar make flake8 en el directorio raíz y corregir todos los errores

Lecturas relacionadas

2 comentarios

 
GN⁺ 2025-02-04
Comentarios de Hacker News

  • A quien quiera usar esto le conviene saber que para la autenticación usa Garth(https://github.com/matin/garth)
    Hace una autenticación bastante hacky: finge ser la app de Android, y además se hace pasar por una instancia única para saltarse el inicio de sesión por formulario web
    Garmin es una empresa realmente molesta para integrarse, y no entiendo por qué bloquea tanto las cosas. Incluso si consigues acceso a la API o al SDK oficial, la calidad suele ser bastante mala

    • Sigo usando el hardware de Garmin porque es muy confiable, pero el mercado necesita con urgencia una alternativa open source
      Garmin sufrió un ataque de ransomware en 2020, sus servicios quedaron caídos durante varios días y terminaron pagando 10 millones de dólares, pero ni siquiera manejaron bien ese problema
    • Garmin no es nada comparado con Strava. Si te integras con Strava y luego el usuario desconecta la cuenta, tienes que borrar todos los datos que vinieron de Strava o podrías perder el acceso a la API
      Las empresas bloquean los datos por la misma razón de siempre: el producto es el usuario, y quieren mantenerlo atado para seguir alimentándose de sus datos
      No pueden permitir que el usuario se vaya con sus datos cuando aparezca un dispositivo mejor de la competencia, porque entonces tendrían que competir más en serio
      Garmin tiene un largo historial de volverse muy flojo hasta que alguien de verdad le compite. Cuando el mercado de los smartwatches se puso caliente, de repente empezaron a salir funciones y modelos mejores; y en las computadoras para bicicleta pasaban años sin renovaciones hasta que Wahoo, Bryton, Coros y Hammerhead empezaron a tocar la puerta
      Con Strava pasa algo parecido. Antes era bastante libre para importar y exportar datos, pero después lo cerraron y ahora exportar datos es casi imposible
    • ¿La integración con Garmin sigue siendo tan mala? Hace unos años hice una integración que generaba pósters con datos GPS de rutas, y en ese momento era casi igual que Strava o RunKeeper, pero después cambiaron los términos de uso y empezaron a pedir unos 10 mil dólares por el costo de conexión
      Ahora parece ser gratis, pero igual sigue requiriendo aprobación
      https://developer.garmin.com/gc-developer-program/overview/
      Para usar tus datos de forma personal o moverlos de un servicio a otro, tapiriik era bueno. No lo he usado en años, así que no sé si todavía siga así
      https://tapiriik.com/
    • Mi experiencia fue totalmente la contraria. Llevo años usando la InReach API y el precio era razonable, no había costos extra aparte de la suscripción de InReach, y el acceso fue fácil: mandé un correo y entre uno y tres días después ya tenía la documentación y el acceso a la API
      El diseño y la estabilidad también eran muy buenos. El sistema de reportes de eventos/puntos basado en callbacks era sólido; aunque mi código se rompiera o fuera inestable, del lado de Garmin reintentaban, y la interfaz de depuración para ver qué pasaba cuando fallaba un webhook también era excelente. El soporte, aunque no era rápido, era de primer nivel
      Al principio de la implementación hubo un bug raro en los webhooks: todos los eventos llegaban dos veces, y uno de ellos tenía el timestamp del evento truncado a un entero en segundos. Viendo el user agent también se notaba que la versión truncada venía de un software con varias versiones de antigüedad
      Les mandé este análisis por correo y unas 12 horas después ya estaba corregido; y otras 12 horas después un ingeniero de verdad respondió agradeciendo la explicación y detallando por qué había ocurrido, cómo, y qué habían corregido
      InReach, especialmente la InReach Professional API, está más cerca de un producto profesional que de uno puramente de consumo, pero Garmin sí es una empresa capaz de hacer este tipo de cosas
    • Yo diría que la parte de consumo/retail de Garmin es un desastre. Hace poco pedí un HRM en el sitio web de Garmin y el estado del pedido se quedó más de una semana en “ordered”; al final lo cancelé y lo compré en Amazon

  • Un amigo me recomendó Intervals(https://intervals.icu) para nerdar con datos de Garmin/Strava y lo he estado usando con bastante satisfacción
    Desde el punto de vista del remo, me gustó porque permite crear reportes con métricas relacionadas con remo, no solo las métricas típicas de ciclismo o running

    • Buena app, no conocía el servicio. Para ciclismo se ve bastante sofisticado
      Pero hace poco tuve otro problema al intentar registrar entrenamientos de Hyrox. Aunque tengo un epix gen 2 (800 euros), era difícil hacer un seguimiento adecuado; puedes definir entrenamientos, pero es demasiado engorroso y tampoco funciona muy bien
      Al final hice mi propia app. Funciona en todos los relojes Garmin, te deja definir entrenamientos fijos y analizar el rendimiento en cada ejercicio
      https://multisports.creatness.studio - sigo esperando la aprobación del envío a la tienda de apps de Garmin, pero ya se puede descargar y sideloadear en relojes Garmin, y yo mismo la llevo usando varias semanas
    • La probé hace unos años y recuerdo que me frustró la forma en que exigía un formato de intervalos para correr
      Al registrar actividades por intervalos, creo que yo quería un formato que no incluyera los tramos de descanso intermedios, así que me resultaba incómodo
      Edit: me equivoqué. No era Intervals.icu, lo confundí con runalyze
    • Intervals.icu es excelente, y vale totalmente la pena pagar para apoyarlo. Es divertido ver el progreso con el tiempo, y también me gusta que puedas personalizar los gráficos
    • Vi la frase “puede usar datos personales para enviar boletines, marketing o material promocional y otra información que pueda ser de su interés” y me salí de inmediato

  • Para extraer todos los datos sin procesar de Garmin Connect como archivos FIT, se puede usar la exportación de datos(https://support.garmin.com/en-US/?faq=W1TvTPW8JZ6LfJSfK512Q8)
    También hay buenas bibliotecas open source para leer e interpretar esos archivos. Por ejemplo, https://github.com/polyvertex/fitdecode para Python y https://github.com/tormoder/fit para Go
    Si quieres obtener los datos actuales, puedes conectar el dispositivo (reloj, ciclocomputador, etc.) a una computadora, montarlo como sistema de archivos y tomar los archivos .FIT actuales
    Hace tiempo empecé un proyecto paralelo que hacía exactamente eso, pero lo dejé a medias
    https://github.com/jo-m/garmin-disconnect

    • ¿Has exportado alguna vez todos los datos sin procesar desde Garmin? Yo tenía 15 años de historial, y en ese volcado no había ni un solo archivo fit/gpx/tcx
      Eran 196 archivos json, 228 MB en total, y todo era solo resúmenes de alto nivel
      Solo pude conseguir los archivos fit reales usando una de esas bibliotecas de exportación de terceros medio hacky, y fueron 5708 archivos con 373 MB. Incluso así, había archivos faltantes, vacíos y duplicados, lo que fue muy frustrante
      La lección fue que no hay que asumir que la exportación de un servicio en línea será completa o vendrá en el formato esperado. Si es un servicio del que dependes, recomiendo mucho hacer una exportación real y verificar que incluya los datos que quieres

  • Garmin realmente necesita aceptar este flujo. Si la alternativa es depender de una app de smartphone, a largo plazo Garmin va a quedar atrás
    Una gran ventaja de comprar hardware dedicado como un ciclocomputador Garmin es tener más control sobre tus datos

    • Ojalá Garmin mejorara su SDK y su documentación. Hice una app sencilla para uso personal, y ahora respeto mucho más a la gente que desarrolla apps para relojes Garmin
      La documentación es increíblemente mala, la mitad hubo que descubrirla por prueba y error, y aun así no sé cómo compilar y probar en otros relojes además del que tengo
      Me gustaría pulir la app y subirla a la tienda, y creo que podría servirle a algunas personas, pero el esfuerzo requerido parece mucho mayor que el valor que aportaría
    • Tengo dos dispositivos Garmin: un reloj y un ciclocomputador, ambos conectados a la misma app para reunir los datos en una sola cuenta de Garmin Connect
      Esperaba cierta sinergia, pero no hubo nada. Si registras la misma actividad al mismo tiempo con ambos dispositivos, solo se generan duplicados. Por ejemplo, termina contando la suma de la distancia medida por ambos
      Es peor que usar dos dispositivos de marcas distintas
    • La app WorkOutDoors y Strava ambas dan acceso completo a los datos gpx
    • Todo se puede ver y descargar desde el sitio web

  • ¿Hay dispositivos parecidos que no les pongan trabas a los usuarios que quieren acceder a sus propios datos?

    • Si Apple bloquea todo, salen el marketing de Apple diciendo que “es bueno porque es seguro” o personas que compraron ese discurso; pero si Garmin/Google/u otra empresa hacen lo mismo, la reacción es “qué estupidez, debería poder usar mis cosas como quiera”

  • Siempre me sorprende cuántos datos quedan encerrados dentro del viejo SDK de Garmin
    Por ejemplo, el formato de archivo FIT que se usa para crear programas de entrenamiento en todos los ciclocomputadores solo es compatible con una o dos apps
    Al final puede que sea culpa nuestra, y quizá tengamos que construirlo nosotros mismos encima del SDK

    • El sitio web de Garmin Connect parece funcionar bien para crear entrenamientos estructurados. También se puede sincronizar con TrainingPeaks. ¿Hace falta algo más?
      Para fines distintos a la planificación de entrenamientos, hay muchas más de dos apps que leen o escriben archivos FIT. Yo hice una de ellas

  • No es solo que el acceso a la API sea difícil; Garmin tampoco escucha a la comunidad
    Por ejemplo, no se puede filtrar por entrenamientos sin equipamiento. A veces se me olvida agregar la bicicleta o los zapatos, así que un filtro así ayudaría
    Sería muy fácil añadir ese filtro en la app o en el sitio web de Connect, pero como no hay un community manager, es imposible participar
    Si tuvieran un rastreador público donde la gente pudiera pedir funciones, Garmin podría revisarlas, hacer un mejor producto y ganar más dinero

  • Esta semana compré un Garmin Vivoactive5 nuevo porque mi antiguo Vivoactive3 se rompió
    Por ahora estoy bastante satisfecho, aunque lo compré sabiendo que la API y las posibilidades de Garmin claramente no son óptimas
    También consideré el Apple Watch Series 10, pero al final lo descarté porque la batería no dura más de 1.5 días, aparte de las funciones de salud no tengo mucho uso para mensajería o apps inteligentes, y costaba el doble que el Vivoactive
    Ojalá existiera un reloj abierto con posibilidad de hackearlo, una buena API, la opción de autoalojar un dashboard y apps decentes. Siento que hay mercado para gente como yo. Tal vez el regreso de Pebble podría llenar ese vacío

  • Esperaba que fuera una forma de extraer y rastrear datos directamente desde el dispositivo, pero por lo que veo se comunica con la API de Connect, así que sigue atado a la app oficial

    • Los datos de actividad no son más que archivos FIT accesibles por USB
    • Abandoné ese enfoque y ahora uso http://www.rungap.com/ para sacar los datos de Garmin desde la API y ponerlos en almacenamiento de iCloud
      También puedes elegir el formato de archivo entre gpx, fit y tcx

  • Configuré esto hace unos meses. Guarda los datos en una base de datos local de sqlite y ejecuta un script una vez al día para traer los datos nuevos
    Tarda bastante más de lo que esperaba. Como el reloj sincroniza esos mismos datos con el teléfono en alrededor de un segundo, parece que por dentro hay una ineficiencia importante. Todavía no he tenido oportunidad de revisar el interior en detalle
 
qor0923 3 일 전

Gracias. Gracias a eso pude aplicarlo bien.