GitList
Browse code

Add a kind of user manual in the README

Natasha Kerensikova authored on03/06/2016 19:39:27
Showing1 changed files
README.md
History View file @23e641c
... ... 
@@ -14,3 +14,106 @@ drain empty a fully-charged Pebble Time Round battery in about 2h30, but
14 14 
 transferring a full day worth of Pebble Health data would only take about
15 15 
 3 minutes. That means roughly 2% of battery per day, for the Pebble model
16 16 
 with the smallest battery.
17 
+
18 
+## Basic Operation
19 
+
20 
+To use this watchapp, you need a webserver to receive the POST request
21 
+sent the watchapp. The append server in my
22 
+[Simple Web Applicaitons (in Ada)][webapps] was the reference used when
23 
+developing this watchapp, but any webapp that can work with a POSTed HTML
24 
+form should work, and the actual HTML from doesn't even need to exist.
25 
+
26 
+[webapps]: https://github.com/faelys/simple-webapps
27 
+
28 
+The watchapp needs to be configured to do anything. The required
29 
+configuration fields are the URL endpoint to which the form is POSTed, and
30 
+the name of the data field.
31 
+
32 
+When configured, the watchapp makes one POST request for each recorded
33 
+Pebble Health entry, filling the data field with string like:
34 
+
35 
+	2016-05-25T21:22:00Z,120,0,4,9915,1,0
36 
+
37 
+That is a typical CSV line, with the fields interpreted as follow:
38 
+
39 
+- **absolute time** of the line, in UTC time zone and in RFC-3339
40 
+format,
41 
+- **number of steps** taken in the given minute (120 in this example),
42 
+- **yaw** (angle of the watch in the x-y plane) in 1/16th of turn
43 
+- **pitch** (angle of the watchface to the z axis) in 1/16th of turn
44 
+- **VMC** which is a measure of how much movement happened during the
45 
+  minute (9915 here is a lot, my desk activity is a few thousands,
46 
+  light sleep or watching TV is a few hundreds, and it goes down to
47 
+  zero during deep sleep)
48 
+- **ambieent light level**, from 1 (darkest) to 4 (brightest) with 0
49 
+  meaning unknown
50 
+- **activity mask**, currently 3 for deep sleep, 1 for non-deep sleep or 0
51 
+  for not sleeping.
52 
+
53 
+Sometimes Pebble Health has no available data for a given minute, then all
54 
+fields except time are empty, so it looks like this:
55 
+
56 
+	2016-05-25T05:14:00Z,,,,,,
57 
+
58 
+## Optional Feature
59 
+
60 
+### Auto Wakeup
61 
+
62 
+I found that the activity mask is reset much more frequently than the rest
63 
+of Pebble Health data, and it seems it happens on a daily basis. To prevent
64 
+forgetting to export the data, it can be automated by configuring an
65 
+automatic wakeup time. The data will then be exported every day at that
66 
+time.
67 
+
68 
+Note that this watchapp has currently a bad management for Wakeup errors.
69 
+So for example if you set a time when some other watchapps has already
70 
+taken, it will fail silently.
71 
+
72 
+### Data Bundling
73 
+
74 
+The HTTP overhead of a POST request is quite larger than the data line
75 
+itself, so it can improve throughput to bundle several line in a single
76 
+POST request.
77 
+
78 
+If your receiving webapp supports this, you can configure bundling lines,
79 
+with a percent-encoded separator of your choice. For example, %0d%0a might
80 
+be good for a webapp like my Append Server that appends the POSTed field
81 
+directly to a text file.
82 
+
83 
+### Extra Form Fields
84 
+
85 
+The webapp might need some other fields than the health data, for example a
86 
+Submit button, or a field to select which file to affect, or a password to
87 
+prevent unauthorized access to the webapp.
88 
+
89 
+Any number of fields can be added to each POST request made by the
90 
+watchapp, with the configured static value.
91 
+
92 
+### Data Signature
93 
+
94 
+Authentication to the webapp might need something stronger than a password,
95 
+and the watchapp javascript engine doesn't do well with cookies. In order
96 
+to strengthen the authentication, my Append Server uses HMAC authentication
97 
+of data lines.
98 
+
99 
+The watchapps can be configured to provide a signature on a the given form
100 
+field, with the usual HMAC-SHA\* algorthm, and can encode the signature in
101 
+hexadecimal or base-64 or send it unencoded.
102 
+
103 
+### Auto Close
104 
+
105 
+With this option the watchapp can automatically close when the data export
106 
+is complete. It can be useful for example to assign to a shortcut button,
107 
+or even just start the watchapp and forget about it.
108 
+
109 
+Note that even when this option is disabled, the watchapp will still
110 
+auto-close when it is started through auto-wakeup, in order to be as
111 
+unobtrusive as possible.
112 
+
113 
+Be warned that the auto-close is faster than the loading of the
114 
+configuration page, so if you have auto-close enabled and have synced
115 
+recently, when trying to load the configuration screen the watchapp might
116 
+close before you have a chance to configure anything. The only solution
117 
+then is to wait for more health data to be generated, so that while it
118 
+upload the configuration page has enough time to load and suspend
119 
+auto-close.