GarminDB — um DB para importar e analisar dados do Garmin Connect/relógios Garmin

 (github.com/tcgoetz)
2 pontos por GN⁺ 2025-02-04 | 2 comentários | Compartilhar no WhatsApp
  • GarminDB é um conjunto de scripts em Python que baixa dados de saúde e atividades do Garmin Connect, faz o parsing para um banco de dados SQLite e permite analisá-los e gerar gráficos pela linha de comando ou em Jupyter Notebook
  • Os dados que podem ser importados automaticamente incluem arquivos de monitoramento diário, sono, peso, frequência cardíaca em repouso e arquivos de atividades; alguns tipos de atividade são armazenados com mais detalhes, incluindo voltas e entradas de registros
  • Como os arquivos JSON e FIT baixados são preservados, é possível recriar o DB sem acessar novamente o Garmin Connect nem baixar tudo de novo
  • Pode ser instalado como pacote do PyPI; depois de configurar a conta do Garmin Connect e a data inicial em GarminConnectConfig.json, execute garmindb_cli.py --all --download --import --analyze para iniciar a coleta e análise completas dos dados
  • Por meio de plugins, é possível ampliar o escopo de processamento de apps Connect IQ e campos de dados de terceiros; após atualizações do esquema do DB, pode ser necessário reconstruir o DB usando os arquivos já baixados

O que o GarminDB faz

  • GarminDB é um conjunto de scripts em Python para fazer parsing e manipular dados de saúde em um banco de dados SQLite
  • SQLite é usado como um banco de dados leve que não exige servidor
  • Recursos compatíveis:
    • Baixa e importa automaticamente arquivos de monitoramento diário da página “Daily Summary” do Garmin Connect
      • Frequência cardíaca ao longo do dia
      • Atividades
      • Subida/descida
      • Estresse
      • Minutos de intensidade
    • Extrai dados de sono, peso e frequência cardíaca em repouso do Garmin Connect, salva em arquivos JSON e importa para o DB
    • Baixa e importa arquivos de atividades do Garmin Connect
      • Cria uma tabela de resumo de todas as atividades
      • Armazena dados mais detalhados para alguns tipos de atividade
      • Inclui voltas e entradas de registros por atividade
    • Resume os dados em um DB com tabelas de resumo diárias, semanais, mensais e anuais
    • Exibe os dados em gráficos pela linha de comando ou em Jupyter Notebook
    • Preserva os arquivos JSON e FIT baixados, permitindo recriar o DB sem acessar novamente o Garmin Connect nem baixar tudo de novo
    • Pode exportar atividades como arquivos TCX

Exploração e análise de dados

  • Depois que os dados estiverem no DB, é possível explorá-los e trabalhar com eles usando os Jupyter Notebooks fornecidos, Jupyter Notebooks de terceiros ou um navegador SQLite
  • Exemplos de navegadores SQLite que podem ser usados:
  • Os scripts criam views padrão no DB para facilitar a exploração dos dados

Instalação e fluxo básico de uso

  • As releases do GarminDb estão no PyPI e exigem Python 3.x
  • Instalar a release mais recente:
    • pip install garmindb
  • Configuração inicial:
    • Copie GarminConnectConfig.json.example para ~/.GarminDb/GarminConnectConfig.json
    • Edite o arquivo para adicionar o nome de usuário e a senha do Garmin Connect
    • Ajuste a data inicial de acordo com as datas dos dados existentes no Garmin Connect
  • Comando para baixar todos os dados e criar o DB na primeira execução:
    • garmindb_cli.py --all --download --import --analyze
  • Comando de atualização incremental para baixar e importar apenas os dados mais recentes depois disso:
    • garmindb_cli.py --all --download --import --analyze --latest
  • Faça backup do DB ocasionalmente com o comando:
    • garmindb_cli.py --backup
  • Atualizar para a release mais recente:
    • pip install --upgrade garmindb

Executando a partir do código-fonte

  • Os scripts da árvore de código-fonte são automatizados com Make
  • Procedimento para uso a partir do código-fonte:
    • Clone o repositório GarminDB via SSH
    • Por causa dos submódulos, é necessário usar SSH em vez de HTTPS
    • Na árvore clonada, execute make setup para preparar os scripts para processar os dados
    • Copie GarminConnectConfig.json.example para ~/.GarminDb/GarminConnectConfig.json e configure a conta e a data inicial
    • Para a primeira importação e processamento dos dados, execute make create_dbs uma vez
    • Depois disso, para manter os dados locais atualizados, execute apenas make periodicamente
  • Uso adicional está na documentação de uso da wiki

Jupyter Notebook e plugins

  • Os Jupyter Notebooks para analisar os dados do banco de dados ficam no diretório Jupyter da árvore de código-fonte
  • Links de Notebooks enviados por usuários estão na página de projetos relacionados da wiki
  • Plugins permitem ampliar os tipos de dados processados e armazenados no DB
  • O GarminDb já inclui vários plugins para processar dados de apps Connect IQ e campos de dados de terceiros
  • Mais detalhes sobre plugins estão em GarminDbPlugins

Cuidados operacionais

  • Após uma atualização do código, pode ocorrer uma exceção de versão do DB
    • Isso significa que o esquema do DB foi atualizado
    • É necessário reconstruir o DB com garmindb_cli.py --rebuild_db
    • O DB é recriado a partir dos arquivos de dados baixados anteriormente, sem baixar todos os dados da Garmin novamente
  • Os scripts foram desenvolvidos em MacOS, e informações de uso em outras plataformas ou patches são bem-vindos
  • Quando a atualização do banco de dados termina, um resumo dos dados do DB é salvo em stats.txt
    • Inclui o intervalo de datas dos arquivos de monitoramento diário e das atividades baixadas
    • Inclui a quantidade de registros de monitoramento diário, atividades, sono, frequência cardíaca em repouso, peso etc.
    • Pode ser usado para verificar se todos os dados foram baixados do Garmin Connect
    • Se houver dados ausentes, ajuste as datas em GarminConnectConfig.json e execute o download novamente
  • Em GarminConnectConfig.json, o elemento steps de course_views é uma lista de IDs de percursos para criar views de DB por percurso
    • Essas views de DB permitem comparar todas as atividades do mesmo percurso

Relato de bugs e contribuição

  • Se houver um problema, registre o bug na aba Issues do projeto
  • Execute make bugreport ou garmindb_bug_report.py e inclua o bugreport.txt gerado no relato de bug
  • Além do erro exibido na tela, um dos primeiros lugares para verificar informações adicionais é o arquivo de log garmindb.log
  • Se o problema ocorrer com um arquivo de dados específico, considere compartilhar esse arquivo para depuração e para adicionar suporte
  • Contribuições devem ser enviadas como Pull Request direcionado ao branch develop
  • Antes de enviar, execute make flake8 no diretório de nível superior e corrija todos os erros

Leituras relacionadas

2 comentários

 
GN⁺ 2025-02-04
Comentários do Hacker News

  • Quem pretende usar isto deve saber que a autenticação usa o Garth (https://github.com/matin/garth)
    Ele faz uma autenticação bem gambiarrosa, fingindo ser o app Android e ainda se passando por uma única instância para contornar o login por formulário web
    A Garmin é uma empresa realmente sofrida para integrar, e não sei por que trava tudo de forma tão extrema. Mesmo quando se consegue acesso à API oficial ou ao SDK, a qualidade costuma ser péssima

    • Uso o hardware da Garmin porque ele é muito confiável, mas o mercado precisa desesperadamente de uma alternativa open source
      A Garmin sofreu um ataque de ransomware em 2020 e, depois de ficar com os serviços fora do ar por vários dias, pagou US$ 10 milhões, mas nem tratou esse problema direito
    • A Garmin não é nada comparada à Strava. Se você integra com a Strava e depois o usuário desconecta, precisa apagar todos os dados vindos da Strava; se não fizer isso, pode perder o acesso à API
      Os motivos pelos quais as empresas trancam os dados são todos parecidos. O usuário é o produto, e elas querem mantê-lo preso para continuar alimentando os dados
      Quando aparece um dispositivo melhor de um concorrente, elas não querem que o usuário vá embora levando seus próprios dados, porque aí teriam que competir com mais empenho
      A Garmin tem um histórico de ser muito preguiçosa até alguém realmente competir com ela. Quando o mercado de smartwatches esquentou, recursos e modelos melhores começaram a surgir de repente; e os ciclocomputadores ficaram anos sem atualização até Wahoo, Bryton, Coros e Hammerhead começarem a bater à porta
      A Strava é parecida. Antes, a entrada e saída de dados era bem livre, mas depois eles fecharam tudo, tornando a exportação de dados quase impossível
    • A integração com a Garmin ainda é tão ruim assim? Alguns anos atrás, quando criei uma integração para fazer pôsteres com dados de GPS de rotas, era quase igual à Strava ou à RunKeeper, mas depois os termos de uso mudaram e passaram a exigir cerca de US$ 10 mil como custo de conexão
      Agora parece ser gratuito, mas ainda exige aprovação
      https://developer.garmin.com/gc-developer-program/overview/
      Para usar dados para fins pessoais ou enviá-los de um serviço para outro, o tapiriik era bom. Não uso há alguns anos, então não sei se ainda é assim
      https://tapiriik.com/
    • Minha experiência foi totalmente oposta. Uso a InReach API há anos; o preço era razoável, não havia custo adicional além da assinatura do InReach, e o acesso foi fácil: depois de enviar um e-mail, recebi a documentação da API e as permissões de acesso em um a três dias
      O design e a estabilidade também eram muito bons. O sistema de eventos/relatórios de pontos baseado em callbacks era sólido; se meu código quebrasse ou ficasse instável, a Garmin tentava novamente; e havia uma ótima interface de debug para ver o que acontecia quando um webhook falhava. O suporte, embora não fosse rápido, era de altíssimo nível
      No início da implementação havia um bug estranho nos webhooks: todos os eventos chegavam duas vezes, e em um deles o timestamp do evento vinha truncado para um inteiro em segundos. Pelo user agent, também dava para ver que o lado truncado era de um software algumas versões mais antigo
      Enviei essa análise por e-mail e, cerca de 12 horas depois, foi corrigido; mais umas 12 horas depois, um engenheiro de verdade respondeu agradecendo a explicação e contando por que e como tinha acontecido, além do que foi corrigido
      O InReach, especialmente a InReach Professional API, é mais próximo de um produto profissional do que de um produto puramente de consumo, mas a Garmin é uma empresa que sabe fazer esse tipo de coisa
    • Acho que o lado consumidor/varejo da Garmin é uma bagunça. Recentemente pedi um HRM no site da Garmin, e o status do pedido ficou em “ordered” por mais de uma semana; no fim, cancelei e comprei na Amazon

  • Um amigo me indicou o Intervals (https://intervals.icu) para brincar com dados relacionados a Garmin/Strava, e tenho usado com bastante satisfação
    Para mim, como remador, foi bom poder criar relatórios que mostram não só métricas comuns de ciclismo/corrida, mas também métricas relacionadas ao remo

    • É um bom app, e eu não conhecia o serviço. Para ciclismo, parece bem sofisticado
      Mas recentemente tive outro problema ao tentar acompanhar treinos de Hyrox. Mesmo tendo um epix gen 2 (€800), era difícil rastrear corretamente; até dá para definir o treino, mas é trabalhoso demais e nem funciona bem
      No fim, criei meu próprio app. Ele funciona em todos os relógios Garmin, permite definir treinos fixos e analisar o desempenho em cada exercício
      https://multisports.creatness.studio - ainda estou esperando a aprovação da submissão à loja de apps da Garmin, mas já é possível baixar e fazer sideload no relógio Garmin, e eu mesmo venho usando há algumas semanas
    • Usei alguns anos atrás e lembro de ter ficado frustrado com a forma como ele exigia o formato dos intervalos de corrida
      Ao registrar uma atividade intervalada, eu queria um formato em que os períodos de descanso no meio não fossem registrados junto, e isso era inconveniente
      Correção: me enganei. Não era o Intervals.icu; confundi com o runalyze
    • O Intervals.icu é excelente e vale muito a pena pagar para apoiar. É divertido ver a evolução do progresso ao longo do tempo, e também gosto da possibilidade de personalizar os gráficos
    • Saí imediatamente quando vi a frase: “podemos usar seus dados pessoais para enviar newsletters, marketing ou materiais promocionais e outras informações que possam ser do seu interesse”

  • Para extrair todos os dados brutos do Garmin Connect como arquivos FIT, basta usar a exportação de dados (https://support.garmin.com/en-US/?faq=W1TvTPW8JZ6LfJSfK512Q8)
    Também existem boas bibliotecas open source para ler e interpretar esses arquivos. Por exemplo, https://github.com/polyvertex/fitdecode para Python e https://github.com/tormoder/fit para Go
    Se quiser obter os dados atuais, dá para conectar o dispositivo (relógio, ciclocomputador etc.) ao computador, montá-lo como sistema de arquivos e pegar os arquivos .FIT atuais
    Há algum tempo comecei um projeto paralelo que fazia exatamente isso, mas acabei abandonando no meio
    https://github.com/jo-m/garmin-disconnect

    • Você já tentou exportar todos os dados brutos da Garmin? Tenho 15 anos de histórico e, nesse dump, não havia nenhum arquivo fit/gpx/tcx
      Eram 196 arquivos json, somando 228 MB, e todos eram apenas resumos de alto nível
      Só consegui baixar os arquivos fit de verdade usando uma daquelas bibliotecas de exportação de terceiros meio hacky: foram 5708 arquivos, com 373 MB. Mesmo assim havia arquivos ausentes, arquivos vazios e arquivos duplicados, o que foi muito frustrante
      A lição que aprendi foi não confiar que a exportação de um serviço online será completa ou virá no formato esperado. Se você depende de um serviço, recomendo fortemente fazer uma exportação de verdade e verificar se os dados que quer estão lá

  • A Garmin realmente deveria abraçar esse fluxo. Se a alternativa for depender de apps de smartphone, a Garmin vai perder espaço no longo prazo
    Uma grande vantagem de comprar hardware dedicado, como um ciclocomputador Garmin, é ter mais controle sobre os dados

    • Eu gostaria que a Garmin melhorasse o SDK e a documentação. Fiz um app simples para uso pessoal, e passei a respeitar muito mais quem cria apps para relógios Garmin
      A documentação é incrivelmente ruim, metade das coisas tive que descobrir por tentativa e erro, e ainda não sei como compilar e testar em relógios diferentes do que eu tenho
      Eu até estaria disposto a polir o app e publicá-lo na loja, e acho que seria útil para algumas pessoas, mas o esforço necessário parece muito maior do que o valor gerado
    • Tenho dois dispositivos Garmin: um relógio e um ciclocomputador. Ambos se conectam ao mesmo app e reúnem os dados em uma única conta do Garmin Connect
      Eu esperava algum grau de sinergia, mas não há nada. Se registro a mesma atividade nos dois dispositivos ao mesmo tempo, só aparecem duplicatas. Por exemplo, ele soma as distâncias medidas pelos dois dispositivos
      É pior do que usar dois dispositivos de marcas diferentes
    • O app WorkOutDoors e o Strava oferecem acesso completo aos dados gpx
    • No site dá para ver e baixar tudo

  • Existe algum dispositivo parecido que não atrapalhe usuários que querem acessar seus próprios dados?

    • Quando a Apple bloqueia tudo, vem o marketing da Apple — ou a reação das pessoas que compraram esse marketing — dizendo “é bom porque é seguro”; quando Garmin/Google/outras empresas fazem isso, vira “idiotice, eu deveria poder usar o que é meu”

  • Sempre me surpreende o quanto de dados fica preso no SDK antigo da Garmin
    Por exemplo, o formato de arquivo FIT, usado em todos os ciclocomputadores para criar treinos, é suportado por apenas um ou dois apps
    Talvez a culpa seja nossa, no fim das contas, e talvez tenhamos que construir diretamente em cima do SDK

    • O site Garmin Connect parece funcionar bem para criar treinos estruturados. Também é possível sincronizar com o TrainingPeaks. O que mais seria necessário?
      Para finalidades que não sejam planos de treino, há muito mais do que dois apps que leem ou escrevem arquivos FIT. Eu mesmo criei um deles

  • Não é só que o acesso à API seja difícil; a Garmin não ouve a comunidade
    Por exemplo, não dá para filtrar por atividades sem equipamento. Às vezes esqueço de adicionar uma bicicleta ou um tênis, então esse filtro ajudaria
    Seria muito fácil adicionar esse filtro ao app ou ao site Connect, mas, como não há um gerente de comunidade, é impossível participar
    Se houvesse um rastreador público onde as pessoas pudessem pedir recursos, a Garmin poderia avaliar isso, criar produtos melhores e ganhar mais dinheiro

  • Comprei um Garmin Vivoactive5 novo esta semana, porque meu antigo Vivoactive3 quebrou
    Por enquanto estou bem satisfeito, mas comprei já sabendo que a API da Garmin e suas possibilidades não são nada ideais
    Também considerei o Apple Watch Series 10, mas acabei desistindo. A bateria não dura mais de 1,5 dia, eu não teria muito uso para mensagens ou apps inteligentes além dos recursos de saúde, e ele custava o dobro do Vivoactive
    Eu gostaria que existisse um relógio aberto, hackeável, com boa API, possibilidade de auto-hospedar dashboards e apps decentes. Sinto que há um mercado para pessoas como eu. Talvez o renascimento do Pebble consiga preencher essa lacuna

  • Eu esperava que fosse um método para trazer os dados diretamente do dispositivo e rastreá-los, mas, pelo visto, ele se comunica com a API do Connect, então ainda fica preso ao app oficial

    • Os dados de atividades são apenas arquivos FIT acessíveis via USB
    • Desisti desse método e agora uso http://www.rungap.com/ para extrair os dados da Garmin pela API e colocá-los no armazenamento do iCloud
      Também dá para escolher o formato dos arquivos entre gpx, fit e tcx

  • Configurei isso há alguns meses. Armazeno os dados em um banco de dados sqlite local e rodo um script uma vez por dia para buscar novos dados
    Leva bem mais tempo do que eu esperava. Como o relógio leva só cerca de 1 segundo para sincronizar os mesmos dados com o celular, parece haver alguma ineficiência séria por dentro. Ainda não tive oportunidade de investigar os detalhes internos
 
qor0923 3 일 전

Obrigado. Graças a isso, consegui aplicar tudo direitinho.