Basic datalogging packet notes

1 files changed, 103 insertions, 0 deletions

diff --git a/notes/logging.mdwn b/notes/logging.mdwn
new file mode 100644
index 0000000..3265829
--- /dev/null
+++ b/notes/logging.mdwn
@@ -0,0 +1,103 @@
+Data Logging
+============
+
+Accelerometer Stream
+--------------------
+
+This stream is a sequence of packets consisting of millisecond deltas and
+smoothed accelerometer magnitudes.  Each packet is 200 bytes long and consists
+of 100 (delta,mag) pairs where each value is a uint8_t.
+
+Clearly this is a high bandwidth channel, logging ca. 20 bytes per second.
+This will consume a non-trivial amount of the watch's battery and should only
+be turned on if you intend to do debugging.  Also, since the stream is purely
+time delta based, if you do turn it on, you'll see an entry in the primary
+datalog stream telling you.
+
+Since each stream will end up catenated to the previous, the first entry in an
+accelerometer stream will be characterised by (a) having a time delta of zero
+(which isn't possible since no two readings happen at the same time) and (b)
+having a magnitude which matches the start stream packet in the datalog stream.
+
+Each stream will also end padded with zero-delta matching-magnitude values such
+that you can line it up with the datalog stream's end stream packet.  This
+means that in the worst case, there'll be 100 of the end markers.
+
+Datalog stream
+--------------
+
+This is the stream considered in the [reporting] document.  As stated, each
+packet in the stream is 12 bytes long, two 32 bit time_ts (I don't care about
+what will happen in 10 years from now, for now) and a 16 bit type and 16 bit
+value.
+
+The following types are defined:
+
+### Start Stream
+
+The _Start Stream_ packet has begin and end set to the same time_t and is an
+"event" packet.  it indicates that the accelerometer stream has started.  The
+value matches the magnitude recorded in the start stream marker in the
+accelerometer stream.
+
+### End Stream
+
+The _End Stream_ packet is the counterpart to the _Start Stream_ packet,
+is an event packet and indicates that the accelerometer stream has finished. The
+value matches the magnitude recorded in the end stream marker(s) in the accelerometer
+stream.
+
+### Step Record
+
+The _Step Record_ packet indicates a period of time and the number of steps
+taken during the period.  It is a time period packet and as such should not overlap
+with any other time period packets.
+
+Typically the time period will be approximately 1 minute, however it may be longer
+or shorter than this, depending on other events.
+
+### Begin Sleep
+
+The _Begin Sleep_ packet indicates that the user has set the watch into sleep mode.
+This packet will typically be preceeded by a step record packet detailing the
+step data up until the button press.  From this packet until an _End Sleep_ packet
+the stream of time period packets will be sleep characterisation packets.  There
+is no value in this event packet.
+
+### Alarm Went Off
+
+The _Alarm Went Off_ packet indicates that the watch alarm went off.  This can
+happen at any time of day as alarms are not limited to purely happening when the
+user is asleep.  This is an event packet and the begin time will be when the alarm
+went off.  The end time will be when the alarm was scheduled for and the value
+will be the number of seconds the alarm rang for before being silenced.
+
+### Alarm Went Off but was snoozed.
+
+All the same as the _Alarm Went Off_ packet, this packet indicates that instead of
+being disabled, the alarm was snoozed instead.
+
+### Alarm disarmed.
+
+The _Alarm disarmed_ packet indicates that a pending alarm was disarmed.  The
+begin time indicates when the event occurred and the end time indicates when the
+alarm was **originally** scheduled for.  The value indicates the number of seconds
+the alarm was ringing before being disabled.  If it is zero then the alarm was
+disarmed before it rang. (possible up to 30 minutes before the alarm time).
+
+### Sleep modality
+
+The _Sleep modality_ packet is a period packet whose value indicates the
+modality of the sleep epoch in question.  The length of the period will
+typically be measured in minutes since sleep is split into 60 second epochs.
+However the packets will typically only be transmitted when the sleep mode
+changes.
+
+### End of sleep mode
+
+The _End of sleep mode_ packet is an event packet which indicates a transition
+from sleep modality packets to step record packets.  When this packet is sent,
+it will be preceeded by a final sleep modality packet and from then on, step
+record packets will be received indicating detected movement.
+
+