piezza/garminexport
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

README: update with new script names and pipenv use

Browse Source
This commit is contained in:
Peter Gardfjäll 2020-04-07 20:41:45 +02:00
parent 94872ae543
commit f2225bb3b3
1 changed files with 56 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
README.md
View File

@ -1,84 +1,61 @@
[![Build Status](https://travis-ci.org/petergardfjall/garminexport.svg?branch=master)](https://travis-ci.org/petergardfjall/garminexport) [![Build Status](https://travis-ci.org/petergardfjall/garminexport.svg?branch=master)](https://travis-ci.org/petergardfjall/garminexport)
Garmin Connect activity backup tool # About
=================================== `garminexport` is both a library and a utility script for downloading/backing up
``garminbackup.py`` is a program that downloads activities for a [Garmin Connect](http://connect.garmin.com/) activities to a local disk.
given [Garmin Connect](http://connect.garmin.com/) account and stores
them in a backup directory locally on the user's computer. The first time The main utility script is called `garmin-backup` and performs incremental
the program is run, it will download *all* activities. After that, it will backups of your Garmin account to a local directory. The first time
`garmin-backup` is run, it will download *all* activities. After that, it will
do incremental backups of your account. That is, the script will only download do incremental backups of your account. That is, the script will only download
activities that haven't already been downloaded to the backup directory. activities that haven't already been downloaded to the backup directory.
The library contains a simple utility program, ``get_activity.py`` for
downloading a single Garmin Connect activity. Run ``./get_activity.py --help``
for more details.
The library also contains a ``garminclient`` module that could be used by third-party # Installation
projects that need to communicate over the Garmin Connect API. See the `garminexport` is available on [PyPi](https://pypi.org/) and can be installed
Library Import section below for more details. with [pip](http://pip.readthedocs.org):
pip install garminexport
It requires Python 3.5+.
Prerequisites # Usage
=============
The instructions below for running the program (or importing the module)
assumes that you have Python 2.7 or Python 3+,
[pip](http://pip.readthedocs.org/en/latest/installing.html), and
[virtualenv](http://virtualenv.readthedocs.org/en/latest/virtualenv.html#installation)
(not required with Python 3) installed.
It also assumes that you have registered an account at
[Garmin Connect](http://connect.garmin.com/).
Getting started ## Prerequisites
=============== To be of any use you need to register an account at [Garmin
Create and activate a new virtual environment to create an isolated development Connect](http://connect.garmin.com/) and populate it with some activities.
environment (that contains the required dependencies and nothing else).
# using Python 2
virtualenv venv.garminexport
# using Python 3
python -m venv venv.garminexport
Activate the virtual environment
. venv.garminexport/bin/activate
Install the required dependencies in this virtual environment:
pip install -r requirements.txt
## As a command-line tool (garmin-backup)
Running The backup program is run as follows (use the `--help` flag for a full list of
======= available options):
The backup program is run as follows (use the ``--help`` flag for a full list
of available options):
./garminbackup.py --backup-dir=activities <username or email> garmin-backup --backup-dir=activities <username or email>
Once started, the program will prompt you for your account password and then Once started, the program will prompt you for your account password and then log
log in to your Garmin Connect account to download activities to the specified in to your Garmin Connect account to download activities to the specified backup
backup directory on your machine. The program will only download activities directory on your machine. The program will only download activities that aren't
that aren't already in the backup directory. already in the backup directory.
Activities can be exported in any of the formats outlined below. Note that Activities can be exported in any of the formats outlined below. Note that
by default, the program downloads all formats for every activity. Use the by default, the program downloads all formats for every activity. Use the
``--format`` option to narrow the selection. `--format` option to narrow the selection.
Supported export formats: Supported export formats:
- ``gpx``: activity GPX file (XML). - `gpx`: activity GPX file (XML).
<sub>[GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) is an open <sub>[GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) is an open
format, mainly for storing GPS routes/tracks. It does support extensions format, mainly for storing GPS routes/tracks. It does support extensions
and Garmin appears to annotate the GPS data with, for example, heart-rate and Garmin appears to annotate the GPS data with, for example, heart-rate
and cadence, when available on your device.</sub> and cadence, when available on your device.</sub>
- ``tcx``: an activity TCX file (XML). - `tcx`: an activity TCX file (XML).
*Note: a ``.tcx`` file may not always be possible to export, for example *Note: a `.tcx` file may not always be possible to export, for example
if an activity was uploaded in gpx format. In that case, Garmin won't try if an activity was uploaded in gpx format. In that case, Garmin won't try
to synthesize a tcx file.* to synthesize a tcx file.*
@ -87,8 +64,8 @@ Supported export formats:
of GPX which includes more metrics and divides the GPS track into "laps" of GPX which includes more metrics and divides the GPS track into "laps"
as recorded by your device (with "lap summaries" for each metric).</sub> as recorded by your device (with "lap summaries" for each metric).</sub>
- ``fit``: activity FIT file (binary format). - `fit`: activity FIT file (binary format).
*Note: a ``.fit`` file may not always be possible to export, for example *Note: a `.fit` file may not always be possible to export, for example
if an activity was entered manually rather than imported from a Garmin device.* if an activity was entered manually rather than imported from a Garmin device.*
<sub>The [FIT](https://www.thisisant.com/resources/fit/) format is the <sub>The [FIT](https://www.thisisant.com/resources/fit/) format is the
@ -96,37 +73,47 @@ Supported export formats:
metrics your device is capable of tracking (GPS, heart rate, cadence, metrics your device is capable of tracking (GPS, heart rate, cadence,
etc). It's a binary format, so tools are needed to read its content.</sub> etc). It's a binary format, so tools are needed to read its content.</sub>
- ``json_summary``: activity summary file (JSON). - `json_summary`: activity summary file (JSON).
<sub>Provides summary data for an activity. Seems to lack a formal schema <sub>Provides summary data for an activity. Seems to lack a formal schema
and should not be counted on as a stable data format (it may change at any and should not be counted on as a stable data format (it may change at any
time). Only included since it *may* contain additional data that could be time). Only included since it *may* contain additional data that could be
useful for developers of analysis tools.</sub> useful for developers of analysis tools.</sub>
- ``json_details``: activity details file (JSON). - `json_details`: activity details file (JSON).
<sub>Provides detailed activity data in a JSON format. Seems to lack a <sub>Provides detailed activity data in a JSON format. Seems to lack a
formal schema and should not be counted on as a stable data format (it may formal schema and should not be counted on as a stable data format (it may
change at any time). Only included since it *may* contain additional data change at any time). Only included since it *may* contain additional data
that could be useful for developers of analysis tools.</sub> that could be useful for developers of analysis tools.</sub>
All files are written to the same directory (``activities/`` by default). All files are written to the same directory (`activities/` by default). Each
Each activity file is prefixed by its upload timestamp and its activity id. activity file is prefixed by its upload timestamp and its activity id.
`garminexport` also contains a few smaller utility programs:
Library import - `garmin-get-activity`: download a single Garmin Connect activity. Run with
============== `--help`for more details.
To install the development version of this library in your local Python - `garmin-upload-activity`: uplad a single Garmin Connect activity file (`.fit`,
environment, run: `.gpx`, or `.tcx`). Run with `--help`for more details.
`pip install -e git://github.com/petergardfjall/garminexport.git#egg=garminexport`
If you prefer to use a `requirements.txt` file, add the following line ## As a library
to your list of dependencies:
`-e git://github.com/petergardfjall/garminexport.git#egg=garminexport` To build your own tools around the Garmin Connect API you can import the
`garminclient` module. It handles authentication to establish a secure session
with Garmin Connect. For example use, have a look at the command-line tools
under [garminexport/cli](garminexport/cli).
and run pip with you dependency file as input:
`pip install -r requirements.txt` # Contribute
To work on the code base you need (besides the basic prerequisites outlined
above) to have [pipenv](https://github.com/pypa/pipenv) installed. Create a
`virtualenv` (an isolated development environment) and install the required
dependencies like so:
make venv
# or similarly: pipenv install