GarminDB - Garmin Connect／ウォッチからデータを取得して解析するDB
(github.com/tcgoetz)- GarminDBは、Garmin Connectの健康・アクティビティデータをダウンロードして SQLiteデータベース に解析し、コマンドラインやJupyter Notebookで分析・グラフ化できるようにするPythonスクリプト集
- 自動で取得できるデータは、日次モニタリングファイル、睡眠、体重、安静時心拍数、アクティビティファイルで、一部のアクティビティタイプでは ラップ・記録エントリ までより詳細に保存する
- ダウンロードした JSONおよびFITファイル を保持するため、Garmin Connectに再接続したり再ダウンロードしたりせずにDBを再生成できる
- PyPIパッケージとしてインストールでき、
GarminConnectConfig.jsonにGarmin Connectアカウントと開始日を設定したうえで、garmindb_cli.py --all --download --import --analyzeにより全データの収集と分析を開始する - プラグインにより、サードパーティの Connect IQアプリとデータフィールド の処理範囲を拡張でき、DBスキーマ更新後には既存のダウンロード済みファイルからDBをリビルドする必要がある場合がある
GarminDBができること
- GarminDBは、健康データを SQLite データベースに解析し操作するための Python スクリプト集
- SQLiteはサーバー不要の軽量データベースとして使われる
- 対応機能:
- Garmin Connectの「Daily Summary」ページから日次モニタリングファイルを自動ダウンロードして取り込む
- 1日を通した心拍数
- アクティビティ
- 上昇／下降
- ストレス
- 強度時間
- Garmin Connectから 睡眠、体重、安静時心拍数 データを抽出してJSONファイルとして保存し、DBに取り込む
- Garmin Connectからアクティビティファイルをダウンロードして取り込む
- すべてのアクティビティのサマリーテーブルを作成
- 一部のアクティビティタイプでは、より詳細なデータを保存
- アクティビティごとのラップと記録エントリを含む
- 日別、週別、月別、年別のサマリーテーブルを含むDBとしてデータを要約する
- コマンドラインまたはJupyter Notebookでデータをグラフ表示する
- ダウンロードしたJSONおよびFITファイルを保持し、Garmin Connectに再接続したり再ダウンロードしたりせずにDBを再生成できる
- アクティビティを TCXファイル としてエクスポートできる
- Garmin Connectの「Daily Summary」ページから日次モニタリングファイルを自動ダウンロードして取り込む
データ探索と分析
- DBにデータが入った後は、提供されているJupyter Notebook、サードパーティのJupyter Notebook、SQLiteブラウザを使ってデータを探索・操作できる
- 利用できるSQLiteブラウザの例は次のとおり
- スクリプトはDB内に基本的な views を作成し、データ探索を容易にする
インストールと基本的な利用フロー
- GarminDbのリリースは PyPI にあり、Python 3.x が必要
- 最新リリースのインストール:
pip install garmindb
- 初期設定:
GarminConnectConfig.json.exampleを~/.GarminDb/GarminConnectConfig.jsonにコピーする- ファイルを編集してGarmin Connectのユーザー名とパスワードを追加する
- Garmin Connectにあるデータの日付に合わせて開始日を調整する
- 初回起動時に全データをダウンロードしてDBを作成するコマンド:
garmindb_cli.py --all --download --import --analyze
- 以後、最新データだけをダウンロードして取り込む増分更新コマンド:
garmindb_cli.py --all --download --import --analyze --latest
- DBバックアップは、ときどき次のコマンドで実行する
garmindb_cli.py --backup
- 最新リリースへの更新:
pip install --upgrade garmindb
ソースから実行する
- ソースツリーのスクリプトは Make で自動化されている
- ソースベースの利用手順:
- SSHクローン方式でGarminDBリポジトリをクローンする
- サブモジュールのため、HTTPSではなくSSHを使う必要がある
- クローンしたツリーで
make setupを実行し、スクリプトがデータを処理できるよう準備する GarminConnectConfig.json.exampleを~/.GarminDb/GarminConnectConfig.jsonにコピーし、アカウントと開始日を設定する- 初回のデータ取得と処理は
make create_dbsを一度実行する - 以後、ローカルデータを最新状態に保つには定期的に
makeだけを実行する
- 追加の使い方は wikiの利用ドキュメント にある
Jupyter Notebookとプラグイン
- データベース内のデータを分析するための Jupyter Notebook は、ソースツリーの
Jupyterディレクトリにある - ユーザーが提出したNotebookリンクは、wikiの関連プロジェクトページ にある
- プラグインにより、処理してDBに保存するデータタイプを拡張できる
- GarminDbには、サードパーティの Connect IQアプリとデータフィールド のデータを処理するためのプラグインがすでに複数ある
- プラグインに関する詳細は GarminDbPlugins にある
運用時の注意点
- コード更新後にDBバージョン例外が発生する場合がある
- これはDBスキーマが更新されたことを意味する
garmindb_cli.py --rebuild_dbでDBをリビルドする必要がある- DBは以前にダウンロードしたデータファイルから再作成され、すべてのデータをGarminから再ダウンロードするわけではない
- スクリプトは MacOS で開発されており、他のプラットフォームでの利用情報やパッチを受け付けている
- データベース更新が終わると、DBデータの要約が
stats.txtに保存される- ダウンロードされた日次モニタリングファイルとアクティビティの日付範囲が含まれる
- 日次モニタリング、アクティビティ、睡眠、安静時心拍数、体重などのレコード数が含まれる
- すべてのデータがGarmin Connectからダウンロードされたか確認するために使える
- 欠落がある場合は、
GarminConnectConfig.jsonの日付を調整してダウンロードを再実行する
GarminConnectConfig.jsonでcourse_viewsのsteps要素は、コース別DBビューを作成するコースIDの一覧- 該当DBビューにより、同じコースのすべてのアクティビティを比較できる
バグ報告と貢献
- 問題がある場合は、プロジェクトのIssuesタブにバグを登録する
make bugreportまたはgarmindb_bug_report.pyを実行し、生成されたbugreport.txtをバグ報告に含める- 画面に表示されるエラー以外で追加情報を確認する最初の場所の一つは ログファイル
garmindb.log - 特定のデータファイルで問題が発生する場合は、デバッグとサポート追加のためにそのファイルの共有を検討する
- 貢献は
developブランチを対象にPull Requestを提出する - 提出前に最上位ディレクトリで
make flake8を実行し、すべてのエラーを修正する
2件のコメント
Hacker Newsのコメント
これを使おうとする人は、認証にGarth(https://github.com/matin/garth)を使っている点を知っておくとよい
Androidアプリのふりをし、しかも単一インスタンスであるかのように偽装してWebフォームのログインを回避するという、かなりハッキーな認証をしている
Garminは本当に連携しづらい会社で、なぜここまで厳しく閉じているのかわからない。公式APIやSDKへのアクセス権を得ても、品質はひどいことが多い
Garminは2020年にランサムウェア攻撃を受け、数日間サービスが停止した末に1,000万ドルを支払ったが、その問題をきちんと扱いもしなかった
企業がデータを囲い込む理由はどこも似たようなものだ。ユーザーが商品であり、縛り続けてデータを食わせたいのだ
競合のより良いデバイスが出たときに、ユーザーが自分のデータを持って去っては困るからで、そうなるともっと真剣に競争しなければならない
Garminは、実際に誰かが競争を仕掛けてくるまでは非常に怠惰な歴史がある。スマートウォッチ市場が熱くなると機能やより良いモデルが突然どっと増え、自転車コンピュータもWahoo、Bryton、Coros、Hammerheadが迫ってくるまでは何年も更新がなかった
Stravaも似たようなものだ。以前はデータの入出力がかなり自由だったが、その後閉じてしまい、データのエクスポートがほぼ不可能になった
今は無料に見えるが、依然として承認が必要だ
https://developer.garmin.com/gc-developer-program/overview/
個人用途でデータを使ったり、あるサービスから別のサービスへ送ったりするなら、tapiriikがよかった。何年も使っていないので今もそうかはわからない
https://tapiriik.com/
設計と安定性も非常に良かった。コールバックベースのイベント/ポイント報告システムは堅牢で、自分のコードが壊れたり不安定でもGarmin側で再試行してくれたし、Webhook失敗時に何が起きるか見られるデバッグインターフェースも素晴らしかった。サポートも速くはないが最高水準だった
実装初期にWebhookで妙なバグがあり、すべてのイベントが2回届き、そのうち1つはイベントのタイムスタンプが秒単位の整数に切り詰められていた。ユーザーエージェントを見ると、切り詰められている側が数バージョン古いソフトウェアだということもわかった
この分析をメールで送ったところ、約12時間後に修正され、さらに12時間ほど後に実際のエンジニアから返信があり、説明への感謝とともに、なぜどう発生したのか、そして修正内容を教えてくれた
InReach、特にInReach Professional APIは純粋な消費者向け製品というよりプロ向け製品に近いが、Garminはこういうことができる会社だ
友人がGarmin/Strava関連のデータ遊び向けにIntervals(https://intervals.icu)を教えてくれて、かなり満足して使っている
ローイングをする立場として、よくある自転車/ランニング指標だけでなく、ローイング関連の指標が出るレポートを作れるのがよかった
ただ、最近Hyroxのワークアウトを追跡しようとして別の問題があった。epix gen 2(800ユーロ)があるのに、きちんと追跡するのが難しく、ワークアウトを定義することはできても手間がかかりすぎて、しかもあまりうまく動かなかった
結局自分でアプリを作った。すべてのGarminウォッチで動作し、固定されたワークアウトを定義したうえで、各ワークアウトごとの成果を分析できる
https://multisports.creatness.studio - まだGarminのアプリストア提出の承認待ちだが、すでにダウンロードしてGarminウォッチにサイドロードでき、ここ数週間自分で使っている
インターバル活動を記録するとき、途中の休憩区間は一緒に記録しない形式を求めていた気がして、不便だった
修正: 勘違いしていた。これはIntervals.icuではなく、runalyzeと混同していた
Garmin Connectからすべての生データをFITファイルとして取り出すには、データのエクスポート（https://support.garmin.com/en-US/?faq=W1TvTPW8JZ6LfJSfK512Q8）を使えばよい。
こうしたファイルを読み取って解釈する優れたオープンソースライブラリもある。たとえば Python 用の https://github.com/polyvertex/fitdecode、Go 用の https://github.com/tormoder/fit がある。
現在のデータが欲しいなら、デバイス（時計、サイクルコンピューターなど）をコンピューターに接続してファイルシステムとしてマウントし、現在の .FIT ファイルを取得できる。
以前まさにそれを行うサイドプロジェクトを始めたが、途中でやめてしまった。
https://github.com/jo-m/garmin-disconnect
196個の json ファイル、合計 228MB で、すべて上位レベルの要約だけだった。
ハッキーなサードパーティ製エクスポートライブラリの1つを使ってようやく実際の fit ファイルを取得でき、5708個のファイルで 373MB だった。それでも欠落ファイル、空ファイル、重複ファイルがあり、非常にうんざりした。
オンラインサービスのエクスポートが完全であるとか、期待した形式であると信じてはいけない、という教訓を得た。依存しているサービスなら、実際にエクスポートしてみて、欲しいデータが入っているか確認することを強く勧める。
Garmin はこうした流れを本当に受け入れるべきだ。代替手段がスマートフォンアプリ依存になるなら、長期的には Garmin が押し負けるだろう。
Garmin のサイクルコンピューターのような専用ハードウェアを買う大きな利点は、データに対するコントロール権がより大きいことにある。
ドキュメントは信じられないほどひどく、半分は試行錯誤で把握するしかなく、それでも自分の持っている時計以外の機種でどうビルドしてテストすればいいのかわからない。
喜んでアプリを磨いてストアに出したいし、一部の人には役立つと思うが、必要な労力が価値をはるかに上回っているように見える。
ある程度のシナジーを期待していたが、何もなかった。同じアクティビティを2台で同時に記録すると、重複が生じるだけだ。たとえば2台のデバイスが測定した距離の合計が記録される。
むしろ異なるブランドのデバイスを2台使うより悪い。
自分のデータにアクセスしようとするユーザーを邪魔しない、似たようなデバイスはあるのか？
Garmin の古い SDK の中にどれだけ多くのデータが閉じ込められているのか、いつも驚かされる。
たとえば、すべてのサイクルコンピューターでワークアウトプログラム作成に使われるFITファイル形式は、1つか2つのアプリでしかサポートされていない。
結局のところ、こちらの責任かもしれないし、SDK の上に自分たちで直接作る必要があるのかもしれない。
ワークアウト計画以外の目的なら、FIT ファイルを読んだり書いたりするアプリは2つどころではなく、ずっと多い。私もその1つを作った。
API へのアクセスが難しいだけでなく、Garmin はコミュニティの声を聞かない。
たとえば装備なしのワークアウトでフィルタリングできない。ときどき自転車やシューズを追加し忘れるので、そういうフィルタがあると助かる。
アプリや Connect Web サイトにそのフィルタを追加するのはとても簡単なはずだが、コミュニティマネージャーがいないので参加が不可能だ。
公開トラッカーを用意して、人々が機能をリクエストできるようにしていれば、Garmin はそれを検討してより良い製品を作り、売上ももっと伸ばせたはずだ。
今週、新しい Garmin Vivoactive5 を買った。以前の Vivoactive3 が壊れたからだ。
今のところかなり満足しているが、Garmin の API と可能性が決して最適ではないことを理解したうえで買った。
Apple Watch Series 10 も検討したが、結局やめた。バッテリーが1.5日以上持たず、健康機能以外ではメッセージングやスマートアプリを特に使うこともなく、Vivoactive より価格が2倍だったからだ。
ハック可能で、優れた API があり、ダッシュボードをセルフホストすることもでき、アプリもそこそこ良いオープンな時計があればいいのにと思う。私のような人向けの市場はあると感じる。Pebble の復活がこの空白を埋めるかもしれない。
デバイスから直接データを取得して追跡する方法だと期待していたが、見たところ Connect API と通信する方式なので、依然として公式アプリに縛られている。
ファイル形式も gpx、fit、tcx から選べる。
数か月前にこれを設定した。データをローカルのsqlite データベースに保存し、1日1回新しいデータを取得するスクリプトを動かしている。
思ったよりかなり時間がかかる。時計が同じデータをスマートフォンと同期するのには1秒ほどしかかからないので、内部に深刻な非効率があるように見える。まだ中身を詳しく見る機会はなかった。
ありがとうございます。おかげさまでうまく適用できました。