From 8ed24fec63e59621c97bfe432eaed3d21f168a30 Mon Sep 17 00:00:00 2001
From: Sander Roosendaal <roosendaalsander@gmail.com>
Date: Thu, 22 Dec 2016 17:24:58 +0100
Subject: [PATCH]  Draft developers info

---
 rowers/templates/about_us.html   |   1 +
 rowers/templates/base.html       |  12 +-
 rowers/templates/developers.html | 198 +++++++++++++++++++++++++++++++
 rowers/urls.py                   |   1 +
 4 files changed, 208 insertions(+), 4 deletions(-)
 create mode 100644 rowers/templates/developers.html

diff --git a/rowers/templates/about_us.html b/rowers/templates/about_us.html
index 34c64464..e562c356 100644
--- a/rowers/templates/about_us.html
+++ b/rowers/templates/about_us.html
@@ -142,6 +142,7 @@ You will be taken to the secure PayPal payment site.
 
 <p>
   <ul>
+    <li>2016-12-19 Interactive stroke curve for NK Empower Oarlock</li>
     <li>2016-12-07 Favorite Flex Charts for Premium users</li>
     <li>2016-12-01 Support for NK Empower Oarlock parameters (catch and
     finish angles, slip and wash, and power as measured by the Oarlock</li>
diff --git a/rowers/templates/base.html b/rowers/templates/base.html
index 4c5678a4..2b209f35 100644
--- a/rowers/templates/base.html
+++ b/rowers/templates/base.html
@@ -155,18 +155,22 @@
     			{% block footer %}
     			<p id="footer"
 >{{ versionstring }}</p>
-			<div class="grid_3 alpha">
+			<div class="grid_2 alpha">
     			<p id="footer"><a href="/rowers/email/">&copy; Sander Roosendaal</a></p>
 			</div>
-			<div class="grid_1 suffix_1">
+			<div class="grid_1 prefix_1">
 			<p id="footer">
 		<a href="/rowers/about">About</a></p>
 			</div>
-			<div class="grid_1 suffix_1">
+                        <div class="grid_2">
+                          <p id="footer">
+                            <a href="/rowers/developers">Developers</a></p>
+                          </div>
+			<div class="grid_1">
 			<p id="footer">
 		<a href="/rowers/legal">Legal</a></p>
 			</div>
-			<div class="grid_1">
+			<div class="grid_1 prefix_1">
 			<p id="footer">
 		<a href="/rowers/physics">Physics</a></p>
 			</div>
diff --git a/rowers/templates/developers.html b/rowers/templates/developers.html
new file mode 100644
index 00000000..f383230a
--- /dev/null
+++ b/rowers/templates/developers.html
@@ -0,0 +1,198 @@
+
+{% extends "base.html" %}
+{% block title %}About us{% endblock title %}
+{% block content %}
+
+<div class="grid_6 alpha">
+  <h2>Resources for developers</h2>
+
+  <p>On this page, a work in progress, I will collect useful information
+    for developers of rowing data apps and hardware.</p>
+  
+  <p>I presume you have an app (smartphone app, dedicated hardware, web site)
+    where your users (customers) generate, collect or store their rowing
+    related workout data. You can now offer your users easy ways to get
+    their data on this site.</p>
+  
+  <p>There are three ways to allow your users to get data to Rowsandall.com.</p>
+
+  <h5>File based export from your app</h5>
+
+  <p>Enable export of TCX, FIT or CSV formatted files from your app.
+    The users
+    upload the file to Rowsandall.com.</p>
+
+  <ul>
+    <li>Advantages
+      <ul>
+        <li>User sees immediate results</li>
+      </ul>
+    </li>
+    <li>Disadvantages
+      <ul>
+        <li>It is a multi-step process: Download from your
+          app, store, upload.</li>
+      </ul>
+    </li>
+  </ul>
+    
+
+  <h5>Email from your app</h5>
+
+  <p>Similar as above, generate TCX, FIT or CSV formatted files and
+    email them
+    to <i>workouts@rowsandall.com</i> directly from your app. The From: field
+    should be the email address of the registered user.</p>
+
+  <ul>
+    <li>Advantages
+      <ul>
+        <li>It may take up to five minutes for the workout to show up
+          on the site.</li>
+      </ul>
+    </li>
+    <li>Disadvantages
+      <ul>
+        <li>It's a simple process, which can be automated.</li>
+      </ul>
+    </li>
+  </ul>
+    
+  <h5>Using the REST API</h5>
+
+  <p>We are building a REST API which will allow you to post and
+    receive stroke
+    data from the site directly.</p>
+
+  <p>The REST API is a work in progress. </p>
+
+  <ul>
+    <li>Advantages
+      <ul>
+        <li>Once it is set up, this is a one-click operation.</li>
+        <li>You can read a user's workout data from the site and use
+          them in your app.</li>
+        <li>This is not limited to workout data. You could make a full mobile
+          version of our site.</li>
+      </ul>
+    </li>
+  
+    <li>Disadvantages
+      <ul>
+        <li>The API is not stable and not fully tested yet.</li>
+        <li>You need to register your app with us. We can revoke your
+          permissions if you misuse them.</li>
+        <li>The first time user must grant permissions to your app.</li>
+        <li>You need to manage authorization tokens.</li>
+      </ul>
+    </li>
+  </ul>
+
+</div>
+
+
+
+<div class="grid_6 omega">
+  <div class="grid_6">
+    <h2>Quick Links</h2>
+
+    <h5>Accepted file formats</h5>
+
+    <p>All files adhering to the standards <a href="http://www8.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd">TCX</a> and <a href="https://www.thisisant.com/resources/fit/">FIT</a> formats will be parsed.</p>
+
+    <p>However, some rowing related parameters are not supported by TCX and FIT. Therefore, we are supporting the CSV format that is documented in the following link.</p>
+
+    <ul><li><a href="http://rowingdata.readthedocs.io/en/latest/#csv-file-standard">Our standard rowing CSV file</a></li></ul>
+
+    <p>Using this standard will guarantee that your user's data are accepted
+      without complaints.</p>
+
+    <h5>API related documentation</h5>
+    
+    <h6>Registering an app</h6>
+
+    <p>As a registered user, you can register an app.</p>
+    <ul><li><a href="/rowers/o/applications/">Self-service app link.</a></li></ul>
+    
+    <h6>Authentication</h6>
+
+    <p>Standard <a href="https://oauth.net/2/">Oauth2</a> authentication.
+      Get authorization code by pointing your user to the authorization URL.
+      Exchange authorization code for an access token. When access token expires,
+      use the refresh token to refresh it.</p>
+
+    <ul>
+      <li>Authorization URL: <b>https://rowsandall.com/rowers/o/authorize</b></li>
+      <li>Access Token request: <b>https://rowsandall.com/rowers/o/token/</b></li>
+      <li>Access Token refresh: <b>https://rowsandall.com/rowers/o/token/</b></li>
+    </ul>
+
+    <h6>API documentation</h6>
+
+    <p>Once you have a registered app, you have gone through the authorization
+      and have successfully obtained an access token, you can use it to place
+      POST, GET and PUT requests.</p>
+
+    <p>The workout summary data and the stroke data are obtained and sent
+      separately.</p>
+
+    <ul>
+      <li><a href="/rowers/api-docs">API documentation</a>
+        (But refer to the below for stroke data.)</li>
+      <li><a href="/rowers/api-docs#/workouts">Try out the workout summary API</a></li>
+      <li><a href="/rowers/api-docs#!/workouts/strokedata_list">GET stroke data</a></li>
+    </ul>
+
+    <p>You can only post stroke data to an existing workout with
+      workout number {id}. If the workout already has stroke data, you
+      will get a duplication error. This functionality will be expanded in the
+      future to enable updating stroke data. Stroke data for workout {id} are
+      posted to:</p>
+
+    <ul>
+      <li><b>https://rowsandall.com/rowers/api/workouts/{id}/strokedata</b></li>
+    </ul>
+
+    <p>The payload is application/json data and looks as follows:</p>
+
+    <p><pre>
+    {
+  "distance": [5,12,19,27,35,43,51,59,67,75,82,90,100],
+  "power": [112,221,511,673,744,754,754,749,729,729,726,709,707],
+  "hr": [132,131,131,132,133,136,139,142,145,147,150,152,153],
+  "pace": [145800,116400,88100,80400,77700,77400,77400,77600,78300,78300,78400,79000,79100],
+  "spm": [11,41,56,59,55,48,48,48,48,48,48,48,49],
+  "time": [0,2200,4599,7000,9599,12000,14400,16799,19400,21799,24200,26599,2900],
+}
+    </pre></p>
+
+    <p>Mandatory data fields are:</p>
+    <ul>
+      <li><b>time</b>: Time (milliseconds since workout start)</li>
+      <li><b>distance</b>: Distance (meters)</li>
+      <li><b>pace</b>: Pace (milliseconds per 500m)</li>
+      <li><b>spm</b> Stroke rate (strokes per minute)</li>
+    </ul>
+    <p>Optional data fiels are:</p>
+    <ul>
+      <li><b>power</b>: Power (Watt)</li>
+      <li><b>drivelength</b>: Drive length (meters)</li>
+      <li><b>dragfactor</b>: Drag factor</li>
+      <li><b>drivetime</b>: Drive time (ms)</li>
+      <li><b>strokerecoverytime</b>: Recovery time (ms)</li>
+      <li><b>averagedriveforce</b>: Average handle force (lbs)</li>
+      <li><b>peakdriveforce</b>: Peak handle force (lbs)</li>
+      <li><b>lapidx</b>: Lap identifier</li>
+      <li><b>hr</b>: Heart rate (beats per minute)</li>
+    </ul>
+
+    <p>Consistency checks will be done and the stroke data will be
+      refused if the mandatory data fields don't pass the checks.
+      All mandatory data fields
+      must have the same number of records. If an optional data field
+      fails a test, its values are silently replaced by zeros.</p>
+    
+  </div>
+</div>
+
+    {% endblock content %}
diff --git a/rowers/urls.py b/rowers/urls.py
index 10ca4c4a..8ca46c3e 100644
--- a/rowers/urls.py
+++ b/rowers/urls.py
@@ -168,6 +168,7 @@ urlpatterns = [
     url(r'^email/thankyou/$', TemplateView.as_view(template_name='thankyou.html'), name='thankyou'),
     url(r'^email/$', TemplateView.as_view(template_name='email.html'), name='email'),
     url(r'^about', TemplateView.as_view(template_name='about_us.html'),name='about'),
+    url(r'^developers', TemplateView.as_view(template_name='developers.html'),name='about'),
     url(r'^compatibility', TemplateView.as_view(template_name='compatibility.html'),name='about'),
     url(r'^videos', TemplateView.as_view(template_name='videos.html'),name='videos'),
     url(r'^analysis', TemplateView.as_view(template_name='analysis.html'),name='analysis'),