GarminDB - DB untuk mengambil dan mem-parsing data dari konektor/jam tangan Garmin

 (github.com/tcgoetz)
2 poin oleh GN⁺ 2025-02-04 | 2 komentar | Bagikan ke WhatsApp
  • GarminDB adalah kumpulan skrip Python untuk mengunduh data kesehatan dan aktivitas dari Garmin Connect, lalu mem-parsing-nya ke database SQLite agar bisa dianalisis dan divisualisasikan lewat command line atau Jupyter Notebook
  • Data yang bisa diambil secara otomatis mencakup file pemantauan harian, tidur, berat badan, detak jantung saat istirahat, dan file aktivitas; beberapa jenis aktivitas juga disimpan lebih rinci hingga lap dan entri rekaman
  • Karena file JSON dan FIT yang diunduh tetap disimpan, DB bisa dibuat ulang tanpa harus masuk lagi ke Garmin Connect atau mengunduh ulang
  • Bisa dipasang sebagai paket PyPI, lalu setelah mengatur akun Garmin Connect dan tanggal mulai di GarminConnectConfig.json, pengumpulan dan analisis data penuh dapat dimulai dengan garmindb_cli.py --all --download --import --analyze
  • Melalui plugin, cakupan pemrosesan untuk aplikasi Connect IQ dan data field pihak ketiga bisa diperluas, dan setelah pembaruan skema DB, DB mungkin perlu dibangun ulang dari file yang sudah diunduh

Apa yang dilakukan GarminDB

  • GarminDB adalah kumpulan skrip Python untuk mem-parsing dan memanipulasi data kesehatan ke dalam database SQLite
  • SQLite digunakan sebagai database ringan yang tidak memerlukan server
  • Fitur yang didukung:
    • Mengunduh dan mengimpor file pemantauan harian secara otomatis dari halaman “Daily Summary” di Garmin Connect
      • Detak jantung sepanjang hari
      • Aktivitas
      • Kenaikan/penurunan elevasi
      • Stres
      • Waktu intensitas
    • Mengekstrak data tidur, berat badan, detak jantung saat istirahat dari Garmin Connect, menyimpannya sebagai file JSON, lalu mengimpornya ke DB
    • Mengunduh dan mengimpor file aktivitas dari Garmin Connect
      • Membuat tabel ringkasan untuk semua aktivitas
      • Menyimpan data lebih detail untuk beberapa jenis aktivitas
      • Termasuk lap per aktivitas dan entri rekaman
    • Merangkum data ke dalam DB yang mencakup tabel ringkasan harian, mingguan, bulanan, dan tahunan
    • Menampilkan grafik data melalui command line atau Jupyter Notebook
    • Menyimpan file JSON dan FIT yang diunduh sehingga DB dapat dibuat ulang tanpa harus masuk lagi ke Garmin Connect atau mengunduh ulang
    • Mengekspor aktivitas sebagai file TCX

Eksplorasi dan analisis data

  • Setelah data masuk ke DB, data bisa dieksplorasi dan diolah menggunakan Jupyter Notebook yang disediakan, Jupyter Notebook pihak ketiga, atau browser SQLite
  • Contoh browser SQLite yang bisa digunakan:
  • Skrip ini membuat views dasar di dalam DB untuk memudahkan eksplorasi data

Instalasi dan alur penggunaan dasar

  • Rilis GarminDb tersedia di PyPI dan memerlukan Python 3.x
  • Memasang rilis terbaru:
    • pip install garmindb
  • Konfigurasi awal:
    • Salin GarminConnectConfig.json.example menjadi ~/.GarminDb/GarminConnectConfig.json
    • Edit file tersebut untuk menambahkan nama pengguna dan kata sandi Garmin Connect
    • Sesuaikan tanggal mulai agar cocok dengan tanggal data yang ada di Garmin Connect
  • Perintah untuk pertama kali mengunduh semua data dan membuat DB:
    • garmindb_cli.py --all --download --import --analyze
  • Setelah itu, perintah pembaruan inkremental yang hanya mengunduh dan mengimpor data terbaru:
    • garmindb_cli.py --all --download --import --analyze --latest
  • Pencadangan DB sesekali dijalankan dengan perintah berikut
    • garmindb_cli.py --backup
  • Memperbarui ke rilis terbaru:
    • pip install --upgrade garmindb

Menjalankan dari source

  • Skrip di source tree diotomatisasi dengan Make
  • Prosedur penggunaan berbasis source:
    • Kloning repositori GarminDB dengan metode klon SSH
    • Karena ada submodule, harus menggunakan SSH, bukan HTTPS
    • Di tree hasil kloning, jalankan make setup agar skrip siap memproses data
    • Salin GarminConnectConfig.json.example menjadi ~/.GarminDb/GarminConnectConfig.json, lalu atur akun dan tanggal mulai
    • Untuk pengambilan dan pemrosesan data pertama kali, jalankan make create_dbs sekali
    • Setelah itu, untuk menjaga data lokal tetap mutakhir, cukup jalankan make secara berkala
  • Penggunaan tambahan tersedia di dokumentasi penggunaan di wiki

Jupyter Notebook dan plugin

  • Jupyter Notebook untuk menganalisis data dalam database ada di direktori Jupyter pada source tree
  • Tautan Notebook yang dikirim pengguna tersedia di halaman proyek terkait di wiki
  • Plugin memungkinkan perluasan jenis data yang diproses dan disimpan ke DB
  • GarminDb sudah memiliki beberapa plugin untuk memproses data dari aplikasi Connect IQ dan data field pihak ketiga
  • Detail lebih lanjut terkait plugin tersedia di GarminDbPlugins

Hal yang perlu diperhatikan saat operasional

  • Setelah pembaruan kode, pengecualian versi DB bisa terjadi
    • Ini berarti skema DB telah diperbarui
    • DB harus dibangun ulang dengan garmindb_cli.py --rebuild_db
    • DB dibuat ulang dari file data yang sebelumnya telah diunduh, tanpa mengunduh ulang semua data dari Garmin
  • Skrip ini dikembangkan di MacOS dan menerima informasi penggunaan atau patch untuk platform lain
  • Setelah pembaruan database selesai, ringkasan data DB disimpan di stats.txt
    • Mencakup rentang tanggal file pemantauan harian dan aktivitas yang diunduh
    • Mencakup jumlah record untuk pemantauan harian, aktivitas, tidur, detak jantung saat istirahat, berat badan, dan lainnya
    • Bisa digunakan untuk memeriksa apakah semua data telah diunduh dari Garmin Connect
    • Jika ada yang hilang, sesuaikan tanggal di GarminConnectConfig.json lalu jalankan ulang pengunduhan
  • Dalam GarminConnectConfig.json, elemen steps dari course_views adalah daftar ID course yang akan dibuatkan DB view per course
    • Dengan DB view tersebut, semua aktivitas pada course yang sama dapat dibandingkan

Laporan bug dan kontribusi

  • Jika ada masalah, daftarkan bug di tab Issues proyek
  • Jalankan make bugreport atau garmindb_bug_report.py, lalu sertakan bugreport.txt yang dihasilkan dalam laporan bug
  • Selain error yang muncul di layar, salah satu tempat pertama untuk memeriksa informasi tambahan adalah file log garmindb.log
  • Jika masalah terjadi pada file data tertentu, pertimbangkan membagikan file tersebut untuk debugging dan penambahan dukungan
  • Untuk berkontribusi, kirim Pull Request yang menargetkan branch develop
  • Sebelum mengirim, jalankan make flake8 di direktori teratas dan perbaiki semua error

Bacaan terkait

2 komentar

 
GN⁺ 2025-02-04
Pendapat Hacker News

  • Orang yang ingin memakai ini sebaiknya tahu bahwa autentikasinya menggunakan Garth(https://github.com/matin/garth)
    Autentikasinya cukup hacky: berpura-pura sebagai aplikasi Android, bahkan menyamar seperti satu instance tunggal, untuk melewati login formulir web
    Garmin benar-benar perusahaan yang menyakitkan untuk diintegrasikan, dan saya tidak tahu kenapa mereka menguncinya separah ini. Bahkan kalau mendapatkan akses ke API resmi atau SDK, kualitasnya cenderung buruk

    • Saya memakai hardware Garmin karena sangat bisa diandalkan, tetapi pasar sangat membutuhkan alternatif open source
      Garmin terkena serangan ransomware pada 2020 dan setelah layanannya lumpuh selama beberapa hari, mereka membayar 10 juta dolar, tetapi mereka bahkan tidak benar-benar menangani masalah itu dengan baik
    • Garmin juga tidak ada apa-apanya dibanding Strava. Kalau Anda mengintegrasikan dengan Strava lalu pengguna memutus koneksi, Anda harus menghapus semua data yang berasal dari Strava; kalau tidak, Anda bisa kehilangan akses API
      Alasan perusahaan mengunci data pada dasarnya sama. Pengguna adalah produk, dan mereka ingin terus mengikat pengguna agar terus memasok data
      Mereka tidak ingin pengguna membawa datanya sendiri dan pergi ketika ada perangkat yang lebih baik dari pesaing, karena kalau begitu mereka harus bersaing lebih keras
      Garmin punya sejarah sangat malas sampai ada pihak yang benar-benar bersaing. Begitu pasar smartwatch memanas, fitur dan model yang lebih baik tiba-tiba membanjir, dan komputer sepeda mereka juga bertahun-tahun tidak diperbarui sampai Wahoo, Bryton, Coros, dan Hammerhead mengetuk pintu
      Strava juga mirip. Dulu keluar-masuk data cukup bebas, tetapi kemudian mereka menguncinya sehingga ekspor data hampir tidak mungkin dilakukan
    • Apakah integrasi Garmin masih seburuk itu? Beberapa tahun lalu saat saya membuat integrasi untuk membuat poster dari data GPS rute, rasanya hampir sama dengan Strava atau RunKeeper, tetapi kemudian ketentuan layanannya berubah dan mereka meminta sekitar 10 ribu dolar sebagai biaya koneksi
      Sekarang tampaknya gratis, tetapi tetap perlu persetujuan
      https://developer.garmin.com/gc-developer-program/overview/
      Untuk memakai data secara pribadi atau mengirimnya dari satu layanan ke layanan lain, tapiriik dulu bagus. Saya sudah beberapa tahun tidak memakainya, jadi tidak tahu apakah masih begitu sekarang
      https://tapiriik.com/
    • Pengalaman saya justru sepenuhnya berlawanan. Saya sudah memakai InReach API selama beberapa tahun, harganya masuk akal, tidak ada biaya tambahan selain langganan InReach, dan aksesnya mudah; setelah mengirim email, dalam satu sampai tiga hari saya menerima dokumentasi API dan hak akses
      Desain dan stabilitasnya juga sangat bagus. Sistem pelaporan event/point berbasis callback-nya solid, pihak Garmin melakukan retry meskipun kode saya rusak atau tidak stabil, dan antarmuka debug untuk melihat apa yang terjadi saat webhook gagal juga luar biasa. Dukungannya juga kelas atas, meskipun tidak cepat
      Di awal implementasi ada bug aneh pada webhook: semua event masuk dua kali, dan salah satunya memiliki timestamp event yang terpotong menjadi bilangan bulat dalam satuan detik. Dari user agent juga terlihat bahwa versi yang terpotong itu berasal dari software yang beberapa versi lebih lama
      Saya mengirim analisis ini lewat email, sekitar 12 jam kemudian sudah diperbaiki, lalu sekitar 12 jam setelah itu seorang engineer sungguhan membalas, berterima kasih atas penjelasannya dan memberi tahu mengapa serta bagaimana hal itu terjadi, juga apa yang diperbaiki
      InReach, terutama InReach Professional API, memang lebih dekat ke produk profesional daripada produk konsumen murni, tetapi Garmin adalah perusahaan yang tahu cara melakukan hal seperti ini
    • Menurut saya sisi konsumen/ritel Garmin berantakan. Baru-baru ini saya memesan HRM di situs Garmin, status pesanan tertahan di “ordered” lebih dari seminggu, dan akhirnya saya batalkan lalu membelinya di Amazon

  • Seorang teman memberi tahu saya tentang Intervals(https://intervals.icu) untuk oprek data Garmin/Strava, dan sejauh ini saya cukup puas memakainya
    Dari sudut pandang pendayung, saya suka karena bisa membuat laporan yang tidak hanya berisi metrik sepeda/lari yang umum, tetapi juga metrik terkait dayung

    • Aplikasi yang bagus, saya sebelumnya tidak tahu layanan ini. Untuk sepeda, kelihatannya cukup canggih
      Namun baru-baru ini saya mengalami masalah lain saat mencoba melacak latihan Hyrox. Walaupun punya epix gen 2 (800 euro), pelacakannya tetap sulit dilakukan dengan benar; latihan memang bisa didefinisikan, tetapi terlalu merepotkan dan tidak berjalan baik
      Akhirnya saya membuat aplikasi sendiri. Aplikasi ini berjalan di semua jam Garmin, bisa mendefinisikan latihan tetap, lalu menganalisis performa untuk tiap latihan
      https://multisports.creatness.studio - masih menunggu persetujuan submission ke app store Garmin, tetapi sudah bisa diunduh dan di-sideload ke jam Garmin, dan saya sendiri sudah memakainya selama beberapa minggu
    • Saya pernah mencobanya beberapa tahun lalu, dan ingat merasa frustrasi karena cara mereka meminta format interval lari
      Sepertinya saya tidak suka karena saat merekam aktivitas interval, mereka menginginkan format yang tidak ikut merekam segmen istirahat di antaranya
      Edit: saya keliru. Ini bukan Intervals.icu, saya tertukar dengan runalyze
    • Intervals.icu sangat bagus, dan sangat layak didukung dengan membayar. Menyenangkan melihat perubahan progres dari waktu ke waktu, dan saya juga suka karena chart-nya bisa dikustomisasi
    • Saya langsung keluar setelah melihat kalimat “kami dapat menggunakan data pribadi untuk mengirim newsletter, materi pemasaran atau promosi, serta informasi lain yang mungkin menarik bagi Anda”

  • Untuk mengekspor semua data mentah dari Garmin Connect sebagai file FIT, gunakan ekspor data (https://support.garmin.com/en-US/?faq=W1TvTPW8JZ6LfJSfK512Q8)
    Ada juga pustaka open source yang bagus untuk membaca dan menafsirkan file seperti ini. Misalnya https://github.com/polyvertex/fitdecode untuk Python, dan https://github.com/tormoder/fit untuk Go
    Jika ingin mendapatkan data saat ini, Anda bisa menghubungkan perangkat (jam tangan, komputer sepeda, dll.) ke komputer, me-mount-nya sebagai sistem file, lalu mengambil file .FIT yang ada
    Dulu saya pernah memulai proyek sampingan yang melakukan persis itu, tetapi berhenti di tengah jalan
    https://github.com/jo-m/garmin-disconnect

    • Pernahkah Anda mengekspor semua data mentah dari Garmin? Saya punya data riwayat 15 tahun, tetapi dump itu tidak berisi satu pun file fit/gpx/tcx
      Isinya 196 file json, total 228MB, dan semuanya hanya ringkasan tingkat tinggi
      Saya baru bisa mendapatkan file fit sebenarnya setelah memakai salah satu pustaka ekspor pihak ketiga yang hacky; hasilnya 5708 file berukuran 373MB. Itu pun masih ada file yang hilang, kosong, dan duplikat, jadi sangat menjengkelkan
      Pelajaran yang saya dapat: jangan percaya bahwa ekspor dari layanan online akan lengkap atau berbentuk seperti yang diharapkan. Jika itu layanan yang Anda andalkan, saya sangat menyarankan untuk benar-benar mencoba ekspornya dan memastikan data yang Anda inginkan ada di dalamnya

  • Garmin benar-benar harus menerima arus seperti ini. Jika alternatifnya bergantung pada aplikasi smartphone, dalam jangka panjang Garmin akan tersingkir
    Keuntungan besar membeli perangkat keras khusus seperti komputer sepeda Garmin adalah kontrol yang lebih besar atas data

    • Saya berharap Garmin memperbaiki SDK dan dokumentasinya. Saya membuat aplikasi sederhana untuk penggunaan pribadi, dan itu membuat saya jauh lebih menghormati orang-orang yang membuat aplikasi jam tangan Garmin
      Dokumentasinya luar biasa buruk, setengahnya harus ditemukan lewat trial-and-error, dan tetap saja saya tidak tahu bagaimana harus membangun dan menguji untuk jam tangan lain selain milik saya
      Saya sebenarnya bersedia memoles aplikasi itu dan mengunggahnya ke store, dan saya rasa itu akan berguna bagi sebagian orang, tetapi usaha yang dibutuhkan tampaknya jauh lebih besar daripada nilainya
    • Saya punya dua perangkat Garmin: jam tangan dan komputer sepeda, keduanya terhubung ke aplikasi yang sama dan mengumpulkan data ke satu akun Garmin Connect
      Saya mengharapkan semacam sinergi, tetapi tidak ada sama sekali. Jika aktivitas yang sama direkam bersamaan dengan dua perangkat, hasilnya hanya duplikasi. Misalnya, jarak yang dihitung menjadi jumlah jarak yang diukur kedua perangkat
      Ini malah lebih buruk daripada memakai dua perangkat dari merek berbeda
    • Aplikasi WorkOutDoors dan Strava sama-sama menyediakan akses penuh ke data gpx
    • Semuanya bisa dilihat dan diunduh dari situs web

  • Apakah ada perangkat serupa yang tidak menghalangi pengguna untuk mengakses data mereka sendiri?

    • Saat Apple mengunci semuanya, respons dari pemasaran Apple atau orang-orang yang termakan pemasaran itu adalah “bagus karena aman”; saat Garmin/Google/perusahaan lain melakukannya, responsnya menjadi “bodoh, saya harus bisa memakai barang milik saya sendiri”

  • Saya selalu terkejut melihat betapa banyak data yang terkunci di dalam SDK lama Garmin
    Misalnya, format file FIT yang dipakai untuk menulis program latihan di semua komputer sepeda hanya didukung oleh satu-dua aplikasi
    Pada akhirnya mungkin ini salah kita juga, dan kita mungkin harus membangunnya sendiri di atas SDK

    • Situs web Garmin Connect tampaknya berfungsi dengan baik untuk membuat latihan terstruktur. Sinkronisasi dengan TrainingPeaks juga bisa. Apa lagi yang dibutuhkan?
      Untuk tujuan selain rencana latihan, aplikasi yang membaca atau menulis file FIT jauh lebih banyak daripada dua. Saya juga membuat salah satunya

  • Masalahnya bukan hanya akses API yang sulit; Garmin juga tidak mendengarkan suara komunitas
    Misalnya, tidak bisa memfilter aktivitas tanpa perlengkapan. Kadang saya lupa menambahkan sepeda atau sepatu, jadi filter seperti itu akan berguna
    Menambahkan filter itu ke aplikasi atau situs Connect semestinya sangat mudah, tetapi karena tidak ada manajer komunitas, partisipasi jadi mustahil
    Jika mereka punya pelacak publik dan membiarkan orang meminta fitur, Garmin bisa meninjaunya, membuat produk yang lebih baik, dan menghasilkan lebih banyak uang

  • Minggu ini saya membeli Garmin Vivoactive5 baru karena Vivoactive3 lama saya rusak
    Saat ini saya cukup puas, tetapi saya membelinya dengan mengetahui bahwa API dan kemungkinan yang ditawarkan Garmin sama sekali tidak optimal
    Saya juga mempertimbangkan Apple Watch Series 10, tetapi akhirnya batal. Baterainya tidak bertahan lebih dari 1,5 hari, selain fitur kesehatan saya tidak terlalu butuh messaging atau aplikasi pintar, dan harganya dua kali lipat Vivoactive
    Saya berharap ada jam tangan terbuka yang bisa di-hack, punya API bagus, memungkinkan dashboard di-host sendiri, dan aplikasinya juga layak. Saya merasa ada pasar untuk orang seperti saya. Mungkin kebangkitan Pebble bisa mengisi kekosongan ini

  • Saya berharap ini adalah cara untuk mengambil dan melacak data langsung dari perangkat, tetapi ternyata caranya berkomunikasi dengan Connect API, jadi masih terikat pada aplikasi resmi

    • Data aktivitas hanyalah file FIT yang bisa diakses lewat USB
    • Saya sudah menyerah pada cara itu, dan sekarang memakai http://www.rungap.com/ untuk menarik data Garmin dari API lalu memasukkannya ke penyimpanan iCloud
      Format file juga bisa dipilih antara gpx, fit, dan tcx

  • Beberapa bulan lalu saya menyiapkan ini. Datanya disimpan di database sqlite lokal, dan saya menjalankan skrip sekali sehari untuk mengambil data baru
    Ternyata memakan waktu cukup lama. Jam tangan hanya butuh sekitar 1 detik untuk menyinkronkan data yang sama ke ponsel, jadi sepertinya ada inefisiensi serius di dalamnya. Saya belum sempat melihat bagian dalamnya secara detail
 
qor0923 3 hari lalu

Terima kasih. Berkat Anda, saya berhasil menerapkannya dengan baik.