├── README.md
└── compositor.json


/README.md:
--------------------------------------------------------------------------------
  1 | running-for-nerds
  2 | =================
  3 | 
  4 | _contribute! if you have facts to share, please submit a pull request or leave an issue_
  5 | 
  6 | Types of running websites:
  7 | 
  8 | * "Fitness Portals" offered by hardware companies, like Garmin and Polar
  9 | * "Fitness Portals" offered by web companies, like Strava and RunKeeper
 10 | * Connectors, like [Tapiriik](https://tapiriik.com/) and [IFFT](https://ifttt.com/)
 11 | 
 12 | ## tapiriik
 13 | 
 14 | [tapiriik](https://tapiriik.com/) is truly one of the best things for running nerds: it allows
 15 | you to automatically distribute your running data: upload just to Strava or to any of the supported
 16 | websites, and it can push runs to all of the others, as well as a linked Dropbox bucket.
 17 | It's really quite good.
 18 | 
 19 | ## Websites
 20 | 
 21 | 
 22 | * [Endomondo](https://www.endomondo.com/)
 23 |   * **tapiriik support**
 24 | * [RunKeeper](http://runkeeper.com/)
 25 |   * [API](http://developer.runkeeper.com/healthgraph/overview)
 26 |   * **tapiriik support**
 27 | * [Strava](http://www.strava.com/)
 28 |   * Actively developed.
 29 |   * **tapiriik support**
 30 |   * [API Reference](http://strava.github.io/api/)
 31 |   * Custom JSON encoding for activities
 32 |   * Strava's API is one of the most modern of the bunch, being that it's from a _real tech company_ and has some elite developers working on it. That said, it's frustratingly one-way: you can upload a GPX, FIT, or TCX file, but the only thing you can get back is Strava's custom, non-standard JSON encoding.
 33 | * [Garmin Connect](http://connect.garmin.com/)
 34 |   * Sporadic developer activity: Garmin is an old company that has had a really hard time modernizing at all, and as a result the interface has become a sort of trainwreck.
 35 |   * **tapiriik support**
 36 |   * [API Reference](http://developer.garmin.com/)
 37 | * [Polar Flow](https://flow.polar.com/)
 38 |   * **WALLED GARDEN**: AVOID
 39 |   * _unsupported in tapiriik_
 40 |   * [API Reference](http://www.polar.com/en/connect_with_polar/polar_accesslink)
 41 |   * Polar is probably the worst watch brand for nerds: it's clear that the company wants to lock down the data _you_ create with the watches _you_ buy
 42 | * [Nike+](http://nikeplus.nike.com/)
 43 |   * [API](https://developer.nike.com/)
 44 |   * _unsupported in tapiriik_
 45 |   * [IFTTT Support](https://ifttt.com/nikeplus)
 46 | * [Motivato](http://motivato.pl/#/): Polish Only
 47 |   * **tapiriik support**
 48 | * [Movescount](http://movescount.com/)
 49 |   * Can be synced directly to Strava and other third party apps, but no public API available.
 50 | * [Fitbit](http://www.fitbit.com/home)
 51 |   * [TCX output for some devices](https://dev.fitbit.com/docs/activity/#get-activity-tcx)
 52 |   * [Charges for data export](http://www.fitbit.com/premium/export)
 53 | 
 54 | 
 55 | ## Apps
 56 | 
 57 | * [Ghostracer](http://getghostracer.com/)
 58 |   * Excellent choice for use on Android Wear devices
 59 |   * Uploads to Strava and Runkeeper
 60 | 
 61 | ## Watches
 62 | 
 63 | Recommended:
 64 | 
 65 | * TomTom: connects to many services, can save files locally
 66 | * Garmin: supports a browser plugin that works on many websites - RunKeeper, Strava, Garmin Connect, etc.
 67 | * Suunto: locked to Movescountvia Moveslink, but has exports to Strava and can also download as Garmin FIT files.
 68 | * Fitbit Surge: uploads to Fitbit & RunKeeper
 69 | * [Sony Smartwatch 3](http://www.sonymobile.com/global-en/products/smartwear/smartwatch-3-swr50/): Runs on Android Wear and has built-in GPS, so you can use it as a stand-alone device.
 70 | * Polar M600: Android WearOS so can use any app available for WearOS (doesn't need to use the Polar Flow)
 71 | 
 72 | Not recommended:
 73 | 
 74 | * Polar: locked down to FlowSync (except M600, as above)
 75 | 
 76 | ## GPS
 77 | 
 78 | The basics of GPS:
 79 | 
 80 | GPS is one system, but there are others, and some devices use more than one. For instance, a new iPhone
 81 | connects to GPS, GLONASS (Russia's system), as well as local wifi access points to derive an accurate location.
 82 | 
 83 | GPS's accuracy has two user-facing problems
 84 | 
 85 | * Time to first lock
 86 | * Jitter
 87 | 
 88 | The first problem is often ameliorated by 'quickfix' tables - these store recent estimates of satellite
 89 | positions so that your receiver can make better guesses initially for where exactly you are.
 90 | 
 91 | The second is based on a few different problems - in cities, [multipath propagation](http://en.wikipedia.org/wiki/Multipath_propagation) will distort a signal that bounces off of a big
 92 | building, making the track end up offset from its original location.
 93 | 
 94 | ## Formats
 95 | 
 96 | Running data is fun because it's potentially 5-dimensional: within a single GPX or TCX file, you can have
 97 | 
 98 | * longitude & latitude & elevation `[x, y, z]`
 99 | * heart rate
100 | * time
101 | 
102 | But traditional GIS formats like Shapefiles can't store all of this data in a non-hacky way,
103 | since they only support attributes at the line level, not at the line-segment level.
104 | [toGeoJSON](https://github.com/mapbox/togeojson) converts GPX to GeoJSON with these properties
105 | put into arrays that work parallel to coordinates.
106 | 
107 | * [GPX](http://www.topografix.com/gpx.asp)
108 |   * [GPSBabel](http://www.gpsbabel.org/) is an essential swiss-army knife
109 | * [TCX](http://en.wikipedia.org/wiki/Training_Center_XML)
110 | * [Strava activity format](https://strava.github.io/api/v3/activities/)
111 | 
112 | ## Sensors
113 | 
114 | A few basic sensor types:
115 | 
116 | * Heart rate
117 | * Cadence (for cycling)
118 | 
119 | Most heart rate sensors work via [EKG](http://en.wikipedia.org/wiki/Electrocardiography), which means
120 | that a big part of their effectiveness comes from skin contact and they often work better with sweat moisture.
121 | 
122 | Not all do, however - for instance [Fitbit PurePulse](http://help.fitbit.com/articles/en_US/Help_article/Heart-rate-FAQs) uses an optical sensor to estimate blood flow and supposedly derives heart rate from this measurement. This system has [had mixed reviews based on its accuracy, which seems to be less than straps](http://recode.net/2015/02/02/three-new-fitbits-see-how-they-run/)
123 | 
124 | ### Protocols
125 | 
126 | * [Bluetooth Low Energy](http://en.wikipedia.org/wiki/Bluetooth_low_energy)
127 | * [Polar Wearlink](https://groups.google.com/forum/#!topic/btstack-dev/TusCxtbq7ug) - proprietary
128 | 
129 | #### ANT+
130 | 
131 | [ANT+](http://en.wikipedia.org/wiki/ANT%2B) is a licensed protocol for accessories to communicate with other devices.
132 | 
133 | * https://github.com/braiden/python-ant-downloader
134 | * https://github.com/Tigge/openant
135 | * https://github.com/Tigge/antfs-cli
136 | * https://github.com/mvillalba/python-ant
137 | 


--------------------------------------------------------------------------------
/compositor.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "tmcw/running-for-nerds",
 3 |   "version": "0.1.4",
 4 |   "libraries": {
 5 |     "xv": "^1.1.25"
 6 |   },
 7 |   "title": "Running for nerds",
 8 |   "branch": "master",
 9 |   "style": {
10 |     "name": "Brutalist",
11 |     "componentSet": {
12 |       "nav": "nav/BasicNav",
13 |       "header": "header/BasicHeader",
14 |       "article": "article/MarkdownArticle",
15 |       "footer": "footer/BasicFooter"
16 |     },
17 |     "fontFamily": "Consolas, \"Liberation Mono\", Menlo, Courier, monospace",
18 |     "heading": {},
19 |     "typeScale": [
20 |       48,
21 |       32,
22 |       20,
23 |       18,
24 |       16,
25 |       14,
26 |       12
27 |     ],
28 |     "layout": {
29 |       "maxWidth": 1024,
30 |       "fluid": true
31 |     },
32 |     "colors": {
33 |       "text": "#333",
34 |       "background": "#fff",
35 |       "primary": "#666",
36 |       "secondary": "#888",
37 |       "highlight": "#1f80ff",
38 |       "muted": "#f6f6f6",
39 |       "border": "#eee"
40 |     }
41 |   },
42 |   "content": [
43 |     {
44 |       "component": "nav",
45 |       "links": [
46 |         {
47 |           "href": "https://github.com/tmcw/running-for-nerds",
48 |           "text": "GitHub"
49 |         }
50 |       ]
51 |     },
52 |     {
53 |       "component": "header",
54 |       "heading": "running-for-nerds",
55 |       "subhead": "like running, but for nerds",
56 |       "children": [
57 |         {
58 |           "component": "ui/TweetButton",
59 |           "text": "running-for-nerds: like running, but for nerds",
60 |           "url": ""
61 |         },
62 |         {
63 |           "component": "ui/GithubButton",
64 |           "user": "tmcw",
65 |           "repo": "running-for-nerds"
66 |         }
67 |       ]
68 |     },
69 |     {
70 |       "component": "article",
71 |       "metadata": {
72 |         "source": "github.readme"
73 |       },
74 |       "html": "\n<p><em>contribute! if you have facts to share, please submit a pull request or leave an issue</em></p>\n<p>Types of running websites:</p>\n<ul>\n<li>&quot;Fitness Portals&quot; offered by hardware companies, like Garmin and Polar</li>\n<li>&quot;Fitness Portals&quot; offered by web companies, like Strava and RunKeeper</li>\n<li>Connectors, like <a href=\"https://tapiriik.com/\">Tapiriik</a> and <a href=\"https://ifttt.com/\">IFFT</a></li>\n</ul>\n<h2>tapiriik</h2>\n<p><a href=\"https://tapiriik.com/\">tapiriik</a> is truly one of the best things for running nerds: it allows\nyou to automatically distribute your running data: upload just to Strava or to any of the supported\nwebsites, and it can push runs to all of the others, as well as a linked Dropbox bucket.\nIt&apos;s really quite good.</p>\n<h2>Websites</h2>\n<ul>\n<li><a href=\"https://www.endomondo.com/\">Endomondo</a><ul>\n<li><strong>tapiriik support</strong></li>\n</ul>\n</li>\n<li><a href=\"http://runkeeper.com/\">RunKeeper</a><ul>\n<li><a href=\"http://developer.runkeeper.com/healthgraph/overview\">API</a></li>\n<li><strong>tapiriik support</strong></li>\n</ul>\n</li>\n<li><a href=\"http://www.strava.com/\">Strava</a><ul>\n<li>Actively developed.</li>\n<li><strong>tapiriik support</strong></li>\n<li><a href=\"http://strava.github.io/api/\">API Reference</a></li>\n<li>Custom JSON encoding for activities</li>\n<li>Strava&apos;s API is one of the most modern of the bunch, being that it&apos;s from a <em>real tech company</em> and has some elite developers working on it. That said, it&apos;s frustratingly one-way: you can upload a GPX, FIT, or TCX file, but the only thing you can get back is Strava&apos;s custom, non-standard JSON encoding.</li>\n</ul>\n</li>\n<li><a href=\"http://connect.garmin.com/\">Garmin Connect</a><ul>\n<li>Sporadic developer activity: Garmin is an old company that has had a really hard time modernizing at all, and as a result the interface has become a sort of trainwreck.</li>\n<li><strong>tapiriik support</strong></li>\n<li><a href=\"http://developer.garmin.com/\">API Reference</a></li>\n</ul>\n</li>\n<li><a href=\"https://flow.polar.com/\">Polar Flow</a><ul>\n<li><strong>WALLED GARDEN</strong>: AVOID</li>\n<li><em>unsupported in tapiriik</em></li>\n<li><a href=\"http://www.polar.com/en/connect_with_polar/polar_accesslink\">API Reference</a></li>\n<li>Polar is probably the worst watch brand for nerds: it&apos;s clear that the company wants to lock down the data <em>you</em> create with the watches <em>you</em> buy</li>\n</ul>\n</li>\n<li><a href=\"http://nikeplus.nike.com/\">Nike+</a><ul>\n<li><a href=\"https://developer.nike.com/\">API</a></li>\n<li><em>unsupported in tapiriik</em></li>\n<li><a href=\"https://ifttt.com/nikeplus\">IFTTT Support</a></li>\n</ul>\n</li>\n<li><a href=\"http://motivato.pl/#/\">Motivato</a>: Polish Only<ul>\n<li><strong>tapiriik support</strong></li>\n</ul>\n</li>\n<li><a href=\"http://movescount.com/\">Movescount</a><ul>\n<li>Can be synced directly to Strava and other third party apps, but no public API available.</li>\n</ul>\n</li>\n<li><a href=\"http://www.fitbit.com/home\">Fitbit</a><ul>\n<li><a href=\"https://dev.fitbit.com/docs/activity/#get-activity-tcx\">TCX output for some devices</a></li>\n<li><a href=\"http://www.fitbit.com/premium/export\">Charges for data export</a></li>\n</ul>\n</li>\n</ul>\n<h2>Apps</h2>\n<ul>\n<li><a href=\"http://getghostracer.com/\">Ghostracer</a><ul>\n<li>Excellent choice for use on Android Wear devices</li>\n<li>Uploads to Strava and Runkeeper</li>\n</ul>\n</li>\n</ul>\n<h2>Watches</h2>\n<p>Recommended:</p>\n<ul>\n<li>TomTom: connects to many services, can save files locally</li>\n<li>Garmin: supports a browser plugin that works on many websites - RunKeeper, Strava, Garmin Connect, etc.</li>\n<li>Suunto: locked to Movescountvia Moveslink, but has exports to Strava and can also download as Garmin FIT files.</li>\n<li>Fitbit Surge: uploads to Fitbit &amp; RunKeeper</li>\n<li><a href=\"http://www.sonymobile.com/global-en/products/smartwear/smartwatch-3-swr50/\">Sony Smartwatch 3</a>: Runs on Android Wear and has built-in GPS, so you can use it as a stand-alone device.</li>\n</ul>\n<p>Not recommended:</p>\n<ul>\n<li>Polar: locked down to FlowSync</li>\n</ul>\n<h2>GPS</h2>\n<p>The basics of GPS:</p>\n<p>GPS is one system, but there are others, and some devices use more than one. For instance, a new iPhone\nconnects to GPS, GLONASS (Russia&apos;s system), as well as local wifi access points to derive an accurate location.</p>\n<p>GPS&apos;s accuracy has two user-facing problems</p>\n<ul>\n<li>Time to first lock</li>\n<li>Jitter</li>\n</ul>\n<p>The first problem is often ameliorated by &apos;quickfix&apos; tables - these store recent estimates of satellite\npositions so that your receiver can make better guesses initially for where exactly you are.</p>\n<p>The second is based on a few different problems - in cities, <a href=\"http://en.wikipedia.org/wiki/Multipath_propagation\">multipath propagation</a> will distort a signal that bounces off of a big\nbuilding, making the track end up offset from its original location.</p>\n<h2>Formats</h2>\n<p>Running data is fun because it&apos;s potentially 5-dimensional: within a single GPX or TCX file, you can have</p>\n<ul>\n<li>longitude &amp; latitude &amp; elevation <code>[x, y, z]</code></li>\n<li>heart rate</li>\n<li>time</li>\n</ul>\n<p>But traditional GIS formats like Shapefiles can&apos;t store all of this data in a non-hacky way,\nsince they only support attributes at the line level, not at the line-segment level.\n<a href=\"https://github.com/mapbox/togeojson\">toGeoJSON</a> converts GPX to GeoJSON with these properties\nput into arrays that work parallel to coordinates.</p>\n<ul>\n<li><a href=\"http://www.topografix.com/gpx.asp\">GPX</a><ul>\n<li><a href=\"http://www.gpsbabel.org/\">GPSBabel</a> is an essential swiss-army knife</li>\n</ul>\n</li>\n<li><a href=\"http://en.wikipedia.org/wiki/Training_Center_XML\">TCX</a></li>\n<li><a href=\"https://strava.github.io/api/v3/activities/\">Strava activity format</a></li>\n</ul>\n<h2>Sensors</h2>\n<p>A few basic sensor types:</p>\n<ul>\n<li>Heart rate</li>\n<li>Cadence (for cycling)</li>\n</ul>\n<p>Most heart rate sensors work via <a href=\"http://en.wikipedia.org/wiki/Electrocardiography\">EKG</a>, which means\nthat a big part of their effectiveness comes from skin contact and they often work better with sweat moisture.</p>\n<p>Not all do, however - for instance <a href=\"http://help.fitbit.com/articles/en_US/Help_article/Heart-rate-FAQs\">Fitbit PurePulse</a> uses an optical sensor to estimate blood flow and supposedly derives heart rate from this measurement. This system has <a href=\"http://recode.net/2015/02/02/three-new-fitbits-see-how-they-run/\">had mixed reviews based on its accuracy, which seems to be less than straps</a></p>\n<h3>Protocols</h3>\n<ul>\n<li><a href=\"http://en.wikipedia.org/wiki/Bluetooth_low_energy\">Bluetooth Low Energy</a></li>\n<li><a href=\"https://groups.google.com/forum/#!topic/btstack-dev/TusCxtbq7ug\">Polar Wearlink</a> - proprietary</li>\n</ul>\n<h4>ANT+</h4>\n<p><a href=\"http://en.wikipedia.org/wiki/ANT%2B\">ANT+</a> is a licensed protocol for accessories to communicate with other devices.</p>\n<ul>\n<li><a href=\"https://github.com/braiden/python-ant-downloader\">https://github.com/braiden/python-ant-downloader</a></li>\n<li><a href=\"https://github.com/Tigge/openant\">https://github.com/Tigge/openant</a></li>\n<li><a href=\"https://github.com/Tigge/antfs-cli\">https://github.com/Tigge/antfs-cli</a></li>\n<li><a href=\"https://github.com/mvillalba/python-ant\">https://github.com/mvillalba/python-ant</a></li>\n</ul>\n"
75 |     },
76 |     {
77 |       "component": "footer",
78 |       "links": [
79 |         {
80 |           "href": "https://github.com/tmcw/running-for-nerds",
81 |           "text": "GitHub"
82 |         },
83 |         {
84 |           "href": "https://github.com/tmcw",
85 |           "text": "tmcw"
86 |         }
87 |       ]
88 |     }
89 |   ]
90 | }


--------------------------------------------------------------------------------