1 files changed, 103 insertions, 0 deletions
diff --git a/notes/logging.mdwn b/notes/logging.mdwn
new file mode 100644
@@ -0,0 +1,103 @@
+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.
+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
+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
+### 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
+### 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
+### 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.