From f2225bb3b3b9fa81ac5cea2b49852f0e90576eae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20Gardfj=C3=A4ll?= Date: Tue, 7 Apr 2020 20:41:45 +0200 Subject: [PATCH] README: update with new script names and pipenv use --- README.md | 125 ++++++++++++++++++++++++------------------------------ 1 file changed, 56 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index a9af816..d7a5b80 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,61 @@ [![Build Status](https://travis-ci.org/petergardfjall/garminexport.svg?branch=master)](https://travis-ci.org/petergardfjall/garminexport) -Garmin Connect activity backup tool -=================================== -``garminbackup.py`` is a program that downloads activities for a -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 program is run, it will download *all* activities. After that, it will +# About +`garminexport` is both a library and a utility script for downloading/backing up +[Garmin Connect](http://connect.garmin.com/) activities to a local disk. + +The main utility script is called `garmin-backup` and performs incremental +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 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 -projects that need to communicate over the Garmin Connect API. See the -Library Import section below for more details. +# Installation +`garminexport` is available on [PyPi](https://pypi.org/) and can be installed +with [pip](http://pip.readthedocs.org): + + pip install garminexport + +It requires Python 3.5+. -Prerequisites -============= -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/). +# Usage -Getting started -=============== -Create and activate a new virtual environment to create an isolated development -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 +## Prerequisites +To be of any use you need to register an account at [Garmin +Connect](http://connect.garmin.com/) and populate it with some activities. +## 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 + garmin-backup --backup-dir=activities -Once started, the program will prompt you for your account password and then -log in to your Garmin Connect account to download activities to the specified -backup directory on your machine. The program will only download activities -that aren't already in the backup directory. +Once started, the program will prompt you for your account password and then log +in to your Garmin Connect account to download activities to the specified backup +directory on your machine. The program will only download activities that aren't +already in the backup directory. 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 -``--format`` option to narrow the selection. +`--format` option to narrow the selection. Supported export formats: - - ``gpx``: activity GPX file (XML). + - `gpx`: activity GPX file (XML). [GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) is an open 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 cadence, when available on your device. - - ``tcx``: an activity TCX file (XML). - *Note: a ``.tcx`` file may not always be possible to export, for example + - `tcx`: an activity TCX file (XML). + *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 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" as recorded by your device (with "lap summaries" for each metric). - - ``fit``: activity FIT file (binary format). - *Note: a ``.fit`` file may not always be possible to export, for example + - `fit`: activity FIT file (binary format). + *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.* 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, etc). It's a binary format, so tools are needed to read its content. - - ``json_summary``: activity summary file (JSON). + - `json_summary`: activity summary file (JSON). 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 time). Only included since it *may* contain additional data that could be useful for developers of analysis tools. - - ``json_details``: activity details file (JSON). + - `json_details`: activity details file (JSON). 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 change at any time). Only included since it *may* contain additional data that could be useful for developers of analysis tools. -All files are written to the same directory (``activities/`` by default). -Each activity file is prefixed by its upload timestamp and its activity id. +All files are written to the same directory (`activities/` by default). Each +activity file is prefixed by its upload timestamp and its activity id. +`garminexport` also contains a few smaller utility programs: -Library import -============== -To install the development version of this library in your local Python -environment, run: +- `garmin-get-activity`: download a single Garmin Connect activity. Run with + `--help`for more details. +- `garmin-upload-activity`: uplad a single Garmin Connect activity file (`.fit`, + `.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 -to your list of dependencies: +## As a library - `-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