--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>Packet timestamping</title>
+<meta name="author" content="Miklos Maroti, Janos Sallai" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="packet-timestamping">
+<h1 class="title">Packet timestamping</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">TBA</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
+</tr>
+<tr><th class="docinfo-name">Status:</th>
+<td>Draft</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">> 2.1</td>
+</tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Miklos Maroti, Janos Sallai</td></tr>
+<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">15-May-2008</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.0</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2008-05-15</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
+</tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and requests
+discussion and suggestions for improvements. Distribution of this memo is
+unlimited. This memo is in full compliance with TEP 1.</p>
+</div>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>This TEP describes a mechanism that provides access to the time of transmission
+and time of reception of a packet. The local clocks of the sender and recipient
+are used to timestamp the transmission and reception of the packet,
+respectively.</p>
+</div>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<p>Time of packet sending and reception is often of interest in sensor network
+applications. Typically, neither the time of invocation of the send command, nor
+the time of signaling of the sendDone event can be used to estimate, without
+significant jitter, the time when the packet was transmitted. Similarly, the
+time of occurrence of the receive event cannot be used to reliably estimate the
+time of reception.</p>
+<p>A straightforward way of message timestamping is to use the start-of-frame
+delimiter interrupt, commonly exposed by packet-oriented radio transceivers.
+This approach was taken by the CC2420 radio stack in TinyOS 1.x: the SFD
+interrupt handler was exposed by the radio stack as an asynchronous event. This
+solution was problematic, because higher- level application components that
+wired the interface containing this event could break the timing of radio stack
+due to excessive computation in interrupt context.</p>
+<p>This TEP overcomes this issue by providing a standardized, platform- independent
+interface to access packet timestamps without exposing timing critical and/or
+hardware-specific events. Also, this TEP does not prescribe how packet
+timestamping should be implemented: it only describes the interfaces and the
+required functionality (semantics).</p>
+</div>
+<div class="section">
+<h1><a id="the-packettimestamp-interface" name="the-packettimestamp-interface">2. The <tt class="docutils literal"><span class="pre">PacketTimeStamp</span></tt> interface</a></h1>
+<p>This TEP specifies a standard interface (<tt class="docutils literal"><span class="pre">PacketTimeStamp</span></tt>) to access the
+packet transmission and packet reception times. The sender and the receiver use
+unsynchronized clocks to timestamp packets. The precision and width of
+timestamps is specified as interface parameters <tt class="docutils literal"><span class="pre">precision_tag</span></tt> and
+<tt class="docutils literal"><span class="pre">size_type</span></tt>:</p>
+<pre class="literal-block">
+interface PacketTimeStamp<precision_tag, size_type>
+{
+ async command bool isValid(message_t* msg);
+ async command size_type timestamp(message_t* msg);
+ async command void clear(message_t* msg);
+ async command void set(message_t* msg, size_type value);
+}
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">timestamp</span></tt> command of the <tt class="docutils literal"><span class="pre">PacketTimeStamp</span></tt> interface is an accessor to the
+the timestamp. The <tt class="docutils literal"><span class="pre">timestamp</span></tt> command returns the time
+of transmission after a sendDone event, and the time of reception after a
+receive event.</p>
+<p>In some cases, it is not possible to timestamp certain packets (e.g. under very
+heavy traffic multiple interrupts can occur before they could be serviced, and
+even if capture registers are used, it is not possible to get the time stamp for
+the first or last unserviced event). The <tt class="docutils literal"><span class="pre">PacketTimeStamp</span></tt> interface contains
+the <tt class="docutils literal"><span class="pre">isValid</span></tt> command to query if the packet timestamp is valid.</p>
+<p>The communications stack MUST guarantee that if the <tt class="docutils literal"><span class="pre">isValid</span></tt> command called
+from within the <tt class="docutils literal"><span class="pre">sendDone</span></tt> or <tt class="docutils literal"><span class="pre">receive</span></tt> event handler returns <tt class="docutils literal"><span class="pre">TRUE</span></tt>, then
+the value returned by the <tt class="docutils literal"><span class="pre">timestamp</span></tt> command can be trusted. However, it
+might be possible that the local clock overflowed more than once or that is was
+stopped or reset since the packet was timestamped, which causes the value
+returned by the <tt class="docutils literal"><span class="pre">timestamp</span></tt> command invalid. The <tt class="docutils literal"><span class="pre">isValid</span></tt> command MAY
+return TRUE in such situations, and it is the responsibility of the user of the
+interface to ensure that the clock runs freely from the time of message
+reception to the time when <tt class="docutils literal"><span class="pre">timestamp</span></tt> is called. To avoid this issue, it is
+recommended that <tt class="docutils literal"><span class="pre">isValid</span></tt> and <tt class="docutils literal"><span class="pre">timestamp</span></tt> are called from the <tt class="docutils literal"><span class="pre">receive</span></tt>
+or <tt class="docutils literal"><span class="pre">sendDone</span></tt> event handler.</p>
+<p>The clear command invalidates the timestamp: after clear is called, <tt class="docutils literal"><span class="pre">isValid</span></tt>
+will return <tt class="docutils literal"><span class="pre">FALSE</span></tt>. A <tt class="docutils literal"><span class="pre">set</span></tt> command is also included to allow for changing
+the timestamp associated with the message. After the <tt class="docutils literal"><span class="pre">set</span></tt> command is called,
+<tt class="docutils literal"><span class="pre">isValid</span></tt> will return TRUE.</p>
+<p>The communications stack guarantees that the transmission timestamp and the
+reception timestamp that belong to the same packet transmission always
+correspond to the same physical phenomenon, i.e. to the same instance of
+physical time. This TEP does not prescribe what synchronization event the
+communications stack should use. For example, the communications stack may chose
+to timestamps hardware events that correspond to the start of
+transmission/reception of the packet, signaled a start-of-frame delimiter (SFD)
+interrupt. The SFD interrupt occurs at the same time on the transmitter and the
+receiver (assuming that the signal propagation delay is negligible).
+Alternatively, on a byte oriented radio, the timestamp may correspond to the
+average of the transmission times of bytes, as described in <a class="footnote-reference" href="#id5" id="id1" name="id1">[2]</a>.</p>
+</div>
+<div class="section">
+<h1><a id="hil-requirements" name="hil-requirements">3. HIL requirements</a></h1>
+<p>The signature of the platform's ActiveMessageC <a class="footnote-reference" href="#id6" id="id2" name="id2">[3]</a> MUST include:</p>
+<pre class="literal-block">
+provides interface PacketTimeStamp<TMilli,uint32_t>;
+</pre>
+<p>where timestamps are given in the node's local time, which is available through
+<tt class="docutils literal"><span class="pre">HILTimerMilliC.LocalTime</span></tt> <a class="footnote-reference" href="#id7" id="id3" name="id3">[4]</a>.</p>
+<p>The communications stack MAY support timestamp precisions and widths other than
+<tt class="docutils literal"><span class="pre">TMilli</span></tt> and <tt class="docutils literal"><span class="pre">uint32_t</span></tt>, respectively. Also, alternative
+<tt class="docutils literal"><span class="pre">TimesyncedPacket</span></tt> implementations MAY use clock sources other than
+<tt class="docutils literal"><span class="pre">HILTimerMilliC.LocalTime</span></tt>.</p>
+</div>
+<div class="section">
+<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
+<p>A reference implementation of the packet timestamping mechanism described in
+this TEP can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/rf230</span></tt>.</p>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">Miklos Maroti</div>
+<div class="line">Janos Sallai</div>
+<div class="line">Institute for Software Integrated Systems</div>
+<div class="line">Vanderbilt University</div>
+<div class="line">2015 Terrace Place</div>
+<div class="line">Nashville, TN 37203</div>
+<div class="line">phone: +1 (615) 343-7555</div>
+</div>
+</div>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id4" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id4">[1]</a></td><td>TEP 111: message_t</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id5" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[2]</a></td><td>Maroti, M., Kusy, B., Simon, G., and Ledeczi, A. 2004. The flooding time synchronization protocol. In Proceedings of the 2nd international Conference on Embedded Networked Sensor Systems (Baltimore, MD, USA, November 03 - 05, 2004). ACM SenSys '04.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id6" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2" name="id6">[3]</a></td><td>TEP 116: Packet protocols</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id7" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id3" name="id7">[4]</a></td><td>TEP 102: Timers</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>Packet-level time synchronization</title>
+<meta name="author" content="Miklos Maroti, Janos Sallai" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="packet-level-time-synchronization">
+<h1 class="title">Packet-level time synchronization</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">TBA</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
+</tr>
+<tr><th class="docinfo-name">Status:</th>
+<td>Draft</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">> 2.1</td>
+</tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Miklos Maroti, Janos Sallai</td></tr>
+<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">15-May-2008</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.0</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2008-05-15</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
+</tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and requests
+discussion and suggestions for improvements. Distribution of this memo is
+unlimited. This memo is in full compliance with TEP 1.</p>
+</div>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>This TEP describes a packet-level time synchronization mechanism that allows for
+sending a time value along with the packet which is automatically converted from
+the sender's local time to the receiver's local time by the communications
+stack.</p>
+</div>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<p>Time of occurrence of events is often of interest in a sensor network.
+Maintaining a synchronized UTC or a virtual global time in a sensor network may,
+however, lead to significant communication overhead and may not always be
+required by the application.</p>
+<p>This TEP describes a packet-level time synchronization mechanism that allows for
+sending a time value along with the packet which is automatically converted from
+the sender's local time to the receiver's local time by the communications
+stack. Packet-level time synchronization is limited to single-hop communication
+and does not provide synchronized network time. It provides a simple yet
+powerful abstraction, on top of which it is possible to implement higher-level
+time synchronization services (e.g. FTSP <a class="footnote-reference" href="#id17" id="id1" name="id1">[6]</a>)in a platform-independent way.
+Packet-level time synchronization is semantically equivalent to the ETA
+primitives <a class="footnote-reference" href="#id12" id="id2" name="id2">[1]</a>.</p>
+<p>The rest of this TEP specifies:</p>
+<ul class="simple">
+<li>Platform-independent packet-level time synchronization interfaces</li>
+<li>How these interfaces are provided in the HIL</li>
+<li>A guideline how each transceiver's HAL may implement the above interfaces</li>
+</ul>
+</div>
+<div class="section">
+<h1><a id="interface" name="interface">2. Interface</a></h1>
+<p>Packet-level time synchronization is implemented by the communication stack and
+is exposed through two interfaces, <tt class="docutils literal"><span class="pre">TimeSyncAMSend</span></tt> and <tt class="docutils literal"><span class="pre">TimeSyncPacket</span></tt>.</p>
+<p>The <tt class="docutils literal"><span class="pre">TimeSyncAMSend</span></tt> interface allows for sending a time value (e.g. an event
+timestamp) along with a message. It is parameterized by the precision and width
+of the time value:</p>
+<pre class="literal-block">
+interface TimeSyncAMSend<precision_tag, size_type>
+{
+ command error_t send(am_addr_t addr, message_t* msg, uint8_t len, size_type event_time);
+ command error_t cancel(message_t* msg);
+ event void sendDone(message_t* msg, error_t error);
+ command uint8_t maxPayloadLength();
+ command void* getPayload(message_t* msg, uint8_t len);
+}
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">send</span></tt> command sends a regular message just like <tt class="docutils literal"><span class="pre">AMSend.send</span></tt> <a class="footnote-reference" href="#id13" id="id3" name="id3">[2]</a>, but
+it also performs sender-receiver time synchronization. The <tt class="docutils literal"><span class="pre">event_time</span></tt>
+parameter holds the time of some event as expressed in the local clock of the
+sender. The receiver can obtain the time of this event (expressed in its own
+local time) via the <tt class="docutils literal"><span class="pre">TimeSyncPacket</span></tt> interface.</p>
+<p>The rest of the functionality is identical to that of the <tt class="docutils literal"><span class="pre">AMSend</span></tt> interface,
+therefore its description is omitted here. Please refer to <a class="footnote-reference" href="#id13" id="id4" name="id4">[2]</a> for details.</p>
+<p>The <tt class="docutils literal"><span class="pre">TimeSyncPacket</span></tt> interface, parameterized by a precision tag and width,
+allows for retrieving a time value that was sent along the received packet:</p>
+<pre class="literal-block">
+interface TimeSyncPacket<precision_tag, size_type>
+{
+ command bool isValid(message_t* msg);
+ command size_type eventTime(message_t* msg);
+}
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">isValid</span></tt> command returns <tt class="docutils literal"><span class="pre">TRUE</span></tt> if the value returned by
+<tt class="docutils literal"><span class="pre">eventTime</span></tt> can be trusted. Under certain circumstances the received packet
+cannot be properly time stamped, so the sender-receiver synchronization cannot
+be finished on the receiver side. In such case, this command returns <tt class="docutils literal"><span class="pre">FALSE</span></tt>.
+This command MUST be called only on the receiver side and only for messages
+transmitted via the TimeSyncAMSend interface.</p>
+<p>The communications stack MUST guarantee that if the <tt class="docutils literal"><span class="pre">isValid</span></tt> command called
+from within the <tt class="docutils literal"><span class="pre">receive</span></tt> event handler returns <tt class="docutils literal"><span class="pre">TRUE</span></tt>, then the value
+returned by the <tt class="docutils literal"><span class="pre">eventTime</span></tt> command can be trusted. However, it might be
+possible that the local clock overflowed more than once or that is was stopped
+or reset since the packet was received, which causes the <tt class="docutils literal"><span class="pre">event_time</span></tt> to be
+invalid. The <tt class="docutils literal"><span class="pre">isValid</span></tt> command MAY return <tt class="docutils literal"><span class="pre">TRUE</span></tt> in such situations, and it
+is the responsibility of the user of the interface to ensure that the clock runs
+freely from the time of message reception to the time when <tt class="docutils literal"><span class="pre">eventTime</span></tt> is
+called. To avoid this issue, it is recommended that <tt class="docutils literal"><span class="pre">isValid</span></tt> and
+<tt class="docutils literal"><span class="pre">eventTime</span></tt> are called from the <tt class="docutils literal"><span class="pre">receive</span></tt> event handler.</p>
+<p>The <tt class="docutils literal"><span class="pre">eventTime</span></tt> command should be called by the receiver of a packet. The
+time of the synchronization event is returned as expressed in the local clock of
+the caller. This command MUST BE called only on the receiver side and only for
+messages transmitted via the <tt class="docutils literal"><span class="pre">TimeSyncAMSend</span></tt> interface.</p>
+</div>
+<div class="section">
+<h1><a id="hil-requirements" name="hil-requirements">3. HIL requirements</a></h1>
+<p>The signature of the platform's ActiveMessageC <a class="footnote-reference" href="#id16" id="id5" name="id5">[5]</a> MUST include:</p>
+<pre class="literal-block">
+provides interface TimeSyncAMSend<TMilli, uint32_t>;
+provides interface TimeSyncPacket<TMilli, uint32_t>;
+</pre>
+<p>where event times are given in the node's local time, which is available through
+<tt class="docutils literal"><span class="pre">HILTimerMilliC.LocalTime</span></tt>.</p>
+<p>The communications stack MAY support timestamp precisions and widths other than
+<tt class="docutils literal"><span class="pre">TMilli</span></tt> and uint32_t, respectively. Also, alternative <tt class="docutils literal"><span class="pre">TimeSyncAMSend</span></tt> and
+<tt class="docutils literal"><span class="pre">TimeSyncPacket</span></tt> implementations MAY use clock sources other than
+<tt class="docutils literal"><span class="pre">HILTimerMilliC.LocalTime</span></tt>.</p>
+</div>
+<div class="section">
+<h1><a id="implementation-guidelines" name="implementation-guidelines">4. Implementation guidelines</a></h1>
+<p>Packet-level time synchronization employs the ETA primitives. In this TEP, only
+the basics of the time synchronization mechanism are described, for details
+please see <a class="footnote-reference" href="#id12" id="id6" name="id6">[1]</a>. This section presents two possible implementation approaches.
+The first approach assumes that the payload of the packet is still mutable when
+the transmission time of the packet (e.g. the timestamp of the SFD interrupt)
+becomes available. The second approach avoids this assumption and uses the
+packet timestamping functionality described in TEP <a class="footnote-reference" href="#id15" id="id7" name="id7">[4]</a> to implement packet-
+level time synchronization.</p>
+<div class="section">
+<h2><a id="approach-1" name="approach-1">4.1 Approach #1</a></h2>
+<p>Several transceivers allow for modifying the contents of a packet after packet
+transmission is started. Packet-level time synchronization can be implemented
+very efficiently on such platforms.</p>
+<p>Transmitter's story</p>
+<blockquote>
+<ul class="simple">
+<li>When the communications stack services a <tt class="docutils literal"><span class="pre">TimeSyncAMSend.send</span></tt> command called
+with event timestamp <tt class="docutils literal"><span class="pre">t_e</span></tt>, it stores <tt class="docutils literal"><span class="pre">t_e</span></tt> (e.g. in a map with the pointer
+of the message_t as key) and sets the designated timestamp field in the packet
+payload to <tt class="docutils literal"><span class="pre">0x80000000</span></tt>.</li>
+<li>When the packet starts being transmitted over the communication medium, a
+corresponding hardware event is timestamped (e.g. an SFD interrupt). Let us
+denote this transmission timestamp with <tt class="docutils literal"><span class="pre">t_tx</span></tt>. The difference of event
+timestamp <tt class="docutils literal"><span class="pre">t_e</span></tt> and transmit timestamp <tt class="docutils literal"><span class="pre">t_tx</span></tt> is written into the
+designated timestamp field in the payload of the packet (typically into the
+footer, since the first few bytes might have been transmitted by this time).
+That is, the information the packet contains at the instance when being sent
+over the communications medium is the age of the event (i.e. how much time ago
+the event had occurred).</li>
+<li>If an error occurs with timestamping the transmission or with writing the
+package payload after transmission has started, then the designated timestamp
+field in the packet payload will contain <tt class="docutils literal"><span class="pre">0x80000000</span></tt>, indicating the error
+to the receiver.</li>
+</ul>
+</blockquote>
+<p>Receiver's story</p>
+<blockquote>
+<ul class="simple">
+<li>The packet is timestamped with the receiver node's local clock at reception
+(e.g. with the timestamp of the SFD interrupt). Let us denote the time of
+reception with <tt class="docutils literal"><span class="pre">t_rx</span></tt>. The reception timestamp is stored in the metadata
+structure of the <tt class="docutils literal"><span class="pre">message_t</span></tt> <a class="footnote-reference" href="#id16" id="id8" name="id8">[5]</a>.</li>
+<li>When the event time is queried via the <tt class="docutils literal"><span class="pre">TimeSyncPacket</span></tt> interface, the
+<tt class="docutils literal"><span class="pre">eventTime</span></tt> command returns the sum of the value stored in the designated
+timestamp field in packet payload and the reception timestamp, i.e. <tt class="docutils literal"><span class="pre">e_t-</span>
+<span class="pre">e_tx+e_rx</span></tt>. This value corresponds to the time of the event in the receiver's
+local clock.</li>
+<li>The <tt class="docutils literal"><span class="pre">TimeSyncPacket.isValid</span></tt> command returns <tt class="docutils literal"><span class="pre">FALSE</span></tt> if the time
+value stored in the payload equals <tt class="docutils literal"><span class="pre">0x80000000</span></tt> or if the communications
+stack failed to timestamp the reception of the packet. Otherwise <tt class="docutils literal"><span class="pre">TRUE</span></tt> is
+returned, which indicates that the value returned by
+<tt class="docutils literal"><span class="pre">TimeSyncPacket.eventTime</span></tt> can be trusted.</li>
+</ul>
+</blockquote>
+</div>
+<div class="section">
+<h2><a id="approach-2" name="approach-2">4.1 Approach #2</a></h2>
+<p>If a particular platform does not support changing the packet contents after the
+synchronization event (start of transmission, SFD interrupt, etc.) had occured,
+it is still possible to provide packet-level time synchronization functionality
+at the cost of some communication overhead. Such an approach can rely on packet
+timestamping TEP <a class="footnote-reference" href="#id15" id="id9" name="id9">[4]</a> to implement packet-level time synchronization.</p>
+<p>Transmitter's story</p>
+<blockquote>
+<ul class="simple">
+<li>When the communications stack services a <tt class="docutils literal"><span class="pre">TimeSyncAMSend.send</span></tt> command
+called with event timestamp <tt class="docutils literal"><span class="pre">t_e</span></tt>, it stores <tt class="docutils literal"><span class="pre">t_e</span></tt> (e.g. in a map with the
+pointer of the message_t as key) and sends the packet.</li>
+<li>Transmission of the packet is timestamped using the packet timestamping TEP
+<a class="footnote-reference" href="#id15" id="id10" name="id10">[4]</a> mechanism. Let us denote this transmission timestamp with <tt class="docutils literal"><span class="pre">t_tx</span></tt>. The
+difference of event timestamp <tt class="docutils literal"><span class="pre">t_e</span></tt> and transmit timestamp <tt class="docutils literal"><span class="pre">t_tx</span></tt> is sent
+in an auxilliary packet. That is, the information the auxulary packet contains
+is the age of the event at the time when the initial packet was transmitted.</li>
+</ul>
+</blockquote>
+<p>Receiver's story</p>
+<blockquote>
+<ul class="simple">
+<li>The packet is timestamped with the receiver node's local clock at reception
+(e.g. with the timestamp of the SFD interrupt). Let us denote the time of
+reception with <tt class="docutils literal"><span class="pre">t_rx</span></tt>. The reception timestamp is stored in the metadata
+structure of the <tt class="docutils literal"><span class="pre">message_t</span></tt> <a class="footnote-reference" href="#id16" id="id11" name="id11">[5]</a>.</li>
+<li>When the auxilliary packet arrives, the time value it carries (<tt class="docutils literal"><span class="pre">t_e-t_tx</span></tt>,
+the age of the event) is stored in a metadata field of the main packet. The
+auxilliary packet is discarded, and the receive event is signalled with the
+pointer to the main packet.</li>
+<li>When the event time is queried via the <tt class="docutils literal"><span class="pre">TimeSyncPacket</span></tt> interface, the
+<tt class="docutils literal"><span class="pre">eventTime</span></tt> command returns the sum of the value stored in the metadata (age
+of the event) and the reception timestamp, i.e. <tt class="docutils literal"><span class="pre">e_t-</span> <span class="pre">e_tx+e_rx</span></tt>. This value
+corresponds to the time of the event in the receiver's local clock.</li>
+<li>The <tt class="docutils literal"><span class="pre">TimeSyncPacket.isValid</span></tt> command returns <tt class="docutils literal"><span class="pre">FALSE</span></tt> if the communications
+stack failed to timestamp the reception of the packet. Otherwise <tt class="docutils literal"><span class="pre">TRUE</span></tt> is
+returned, which indicates that the value returned by
+<tt class="docutils literal"><span class="pre">TimeSyncPacket.eventTime</span></tt> can be trusted.</li>
+</ul>
+</blockquote>
+</div>
+<div class="section">
+<h2><a id="reference-implementation" name="reference-implementation">5. Reference implementation</a></h2>
+<p>A reference implementation of the packet-level time synchronization mechanism
+described in this TEP can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/rf230</span></tt>.</p>
+</div>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">Miklos Maroti</div>
+<div class="line">Janos Sallai</div>
+<div class="line">Institute for Software Integrated Systems</div>
+<div class="line">Vanderbilt University</div>
+<div class="line">2015 Terrace Place</div>
+<div class="line">Nashville, TN 37203</div>
+<div class="line">phone: +1 (615) 343-7555</div>
+</div>
+</div>
+<div class="section">
+<h1><a id="citations" name="citations">7. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id12" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id12">[1]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id6">2</a>)</em> Kusy, B., Dutta, P., Levis, P., Maroti, M., Ledeczi, A., Culler, D., Elapsed Time on Arrival: A simple and versatile primitive for canonical time synchronization services. International Journal of Ad hoc and Ubiquitous Computing, Vol, 2, No. 1, 2006.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id13" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id13">[2]</a></td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id4">2</a>)</em> TEP 116: Packet protocols</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id14" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id14">[3]</a></td><td>TEP 102: Timers</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id15" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id15">[4]</a></td><td><em>(<a class="fn-backref" href="#id7">1</a>, <a class="fn-backref" href="#id9">2</a>, <a class="fn-backref" href="#id10">3</a>)</em> TEP TBA: Packet timestamping</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id16" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id16">[5]</a></td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id8">2</a>, <a class="fn-backref" href="#id11">3</a>)</em> TEP 111: message_t</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id17" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id17">[6]</a></td><td>Maroti, M., Kusy, B., Simon, G., and Ledeczi, A. 2004. The flooding time synchronization protocol. In Proceedings of the 2nd international Conference on Embedded Networked Sensor Systems (Baltimore, MD, USA, November 03 - 05, 2004). ACM SenSys '04.</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
--- /dev/null
+===================
+Packet timestamping
+===================
+
+:TEP: TBA
+:Group: Core Working Group
+:Type: Documentary
+:Status: Draft
+:TinyOS-Version: > 2.1
+:Author: Miklos Maroti, Janos Sallai
+
+:Draft-Created: 15-May-2008
+:Draft-Version: $Revision$
+:Draft-Modified: $Date$
+:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
+
+.. Note::
+
+ This memo documents a part of TinyOS for the TinyOS Community, and requests
+ discussion and suggestions for improvements. Distribution of this memo is
+ unlimited. This memo is in full compliance with TEP 1.
+
+Abstract
+============================================================================
+
+This TEP describes a mechanism that provides access to the time of transmission
+and time of reception of a packet. The local clocks of the sender and recipient
+are used to timestamp the transmission and reception of the packet,
+respectively.
+
+1. Introduction
+============================================================================
+
+Time of packet sending and reception is often of interest in sensor network
+applications. Typically, neither the time of invocation of the send command, nor
+the time of signaling of the sendDone event can be used to estimate, without
+significant jitter, the time when the packet was transmitted. Similarly, the
+time of occurrence of the receive event cannot be used to reliably estimate the
+time of reception.
+
+A straightforward way of message timestamping is to use the start-of-frame
+delimiter interrupt, commonly exposed by packet-oriented radio transceivers.
+This approach was taken by the CC2420 radio stack in TinyOS 1.x: the SFD
+interrupt handler was exposed by the radio stack as an asynchronous event. This
+solution was problematic, because higher- level application components that
+wired the interface containing this event could break the timing of radio stack
+due to excessive computation in interrupt context.
+
+This TEP overcomes this issue by providing a standardized, platform- independent
+interface to access packet timestamps without exposing timing critical and/or
+hardware-specific events. Also, this TEP does not prescribe how packet
+timestamping should be implemented: it only describes the interfaces and the
+required functionality (semantics).
+
+2. The ``PacketTimeStamp`` interface
+============================================================================
+
+This TEP specifies a standard interface (``PacketTimeStamp``) to access the
+packet transmission and packet reception times. The sender and the receiver use
+unsynchronized clocks to timestamp packets. The precision and width of
+timestamps is specified as interface parameters ``precision_tag`` and
+``size_type``::
+
+ interface PacketTimeStamp<precision_tag, size_type>
+ {
+ async command bool isValid(message_t* msg);
+ async command size_type timestamp(message_t* msg);
+ async command void clear(message_t* msg);
+ async command void set(message_t* msg, size_type value);
+ }
+
+The ``timestamp`` command of the ``PacketTimeStamp`` interface is an accessor to the
+the timestamp. The ``timestamp`` command returns the time
+of transmission after a sendDone event, and the time of reception after a
+receive event.
+
+In some cases, it is not possible to timestamp certain packets (e.g. under very
+heavy traffic multiple interrupts can occur before they could be serviced, and
+even if capture registers are used, it is not possible to get the time stamp for
+the first or last unserviced event). The ``PacketTimeStamp`` interface contains
+the ``isValid`` command to query if the packet timestamp is valid.
+
+The communications stack MUST guarantee that if the ``isValid`` command called
+from within the ``sendDone`` or ``receive`` event handler returns ``TRUE``, then
+the value returned by the ``timestamp`` command can be trusted. However, it
+might be possible that the local clock overflowed more than once or that is was
+stopped or reset since the packet was timestamped, which causes the value
+returned by the ``timestamp`` command invalid. The ``isValid`` command MAY
+return TRUE in such situations, and it is the responsibility of the user of the
+interface to ensure that the clock runs freely from the time of message
+reception to the time when ``timestamp`` is called. To avoid this issue, it is
+recommended that ``isValid`` and ``timestamp`` are called from the ``receive``
+or ``sendDone`` event handler.
+
+The clear command invalidates the timestamp: after clear is called, ``isValid``
+will return ``FALSE``. A ``set`` command is also included to allow for changing
+the timestamp associated with the message. After the ``set`` command is called,
+``isValid`` will return TRUE.
+
+The communications stack guarantees that the transmission timestamp and the
+reception timestamp that belong to the same packet transmission always
+correspond to the same physical phenomenon, i.e. to the same instance of
+physical time. This TEP does not prescribe what synchronization event the
+communications stack should use. For example, the communications stack may chose
+to timestamps hardware events that correspond to the start of
+transmission/reception of the packet, signaled a start-of-frame delimiter (SFD)
+interrupt. The SFD interrupt occurs at the same time on the transmitter and the
+receiver (assuming that the signal propagation delay is negligible).
+Alternatively, on a byte oriented radio, the timestamp may correspond to the
+average of the transmission times of bytes, as described in [2]_.
+
+3. HIL requirements
+============================================================================
+
+The signature of the platform's ActiveMessageC [3]_ MUST include::
+
+ provides interface PacketTimeStamp<TMilli,uint32_t>;
+
+where timestamps are given in the node's local time, which is available through
+``HILTimerMilliC.LocalTime`` [4]_.
+
+The communications stack MAY support timestamp precisions and widths other than
+``TMilli`` and ``uint32_t``, respectively. Also, alternative
+``TimesyncedPacket`` implementations MAY use clock sources other than
+``HILTimerMilliC.LocalTime``.
+
+4. Implementation
+============================================================================
+
+A reference implementation of the packet timestamping mechanism described in
+this TEP can be found in ``tinyos-2.x/tos/chips/rf230``.
+
+5. Author's Address
+============================================================================
+
+| Miklos Maroti
+| Janos Sallai
+| Institute for Software Integrated Systems
+| Vanderbilt University
+| 2015 Terrace Place
+| Nashville, TN 37203
+| phone: +1 (615) 343-7555
+
+6. Citations
+============================================================================
+
+.. [1] TEP 111: message_t
+
+.. [2] Maroti, M., Kusy, B., Simon, G., and Ledeczi, A. 2004. The flooding time synchronization protocol. In Proceedings of the 2nd international Conference on Embedded Networked Sensor Systems (Baltimore, MD, USA, November 03 - 05, 2004). ACM SenSys '04.
+
+.. [3] TEP 116: Packet protocols
+
+.. [4] TEP 102: Timers
--- /dev/null
+=================================
+Packet-level time synchronization
+=================================
+
+:TEP: TBA
+:Group: Core Working Group
+:Type: Documentary
+:Status: Draft
+:TinyOS-Version: > 2.1
+:Author: Miklos Maroti, Janos Sallai
+
+:Draft-Created: 15-May-2008
+:Draft-Version: $Revision$
+:Draft-Modified: $Date$
+:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
+
+.. Note::
+
+ This memo documents a part of TinyOS for the TinyOS Community, and requests
+ discussion and suggestions for improvements. Distribution of this memo is
+ unlimited. This memo is in full compliance with TEP 1.
+
+Abstract
+============================================================================
+
+This TEP describes a packet-level time synchronization mechanism that allows for
+sending a time value along with the packet which is automatically converted from
+the sender's local time to the receiver's local time by the communications
+stack.
+
+1. Introduction
+============================================================================
+
+Time of occurrence of events is often of interest in a sensor network.
+Maintaining a synchronized UTC or a virtual global time in a sensor network may,
+however, lead to significant communication overhead and may not always be
+required by the application.
+
+This TEP describes a packet-level time synchronization mechanism that allows for
+sending a time value along with the packet which is automatically converted from
+the sender's local time to the receiver's local time by the communications
+stack. Packet-level time synchronization is limited to single-hop communication
+and does not provide synchronized network time. It provides a simple yet
+powerful abstraction, on top of which it is possible to implement higher-level
+time synchronization services (e.g. FTSP [6]_)in a platform-independent way.
+Packet-level time synchronization is semantically equivalent to the ETA
+primitives [1]_.
+
+The rest of this TEP specifies:
+
+- Platform-independent packet-level time synchronization interfaces
+- How these interfaces are provided in the HIL
+- A guideline how each transceiver's HAL may implement the above interfaces
+
+2. Interface
+============================================================================
+
+Packet-level time synchronization is implemented by the communication stack and
+is exposed through two interfaces, ``TimeSyncAMSend`` and ``TimeSyncPacket``.
+
+The ``TimeSyncAMSend`` interface allows for sending a time value (e.g. an event
+timestamp) along with a message. It is parameterized by the precision and width
+of the time value::
+
+ interface TimeSyncAMSend<precision_tag, size_type>
+ {
+ command error_t send(am_addr_t addr, message_t* msg, uint8_t len, size_type event_time);
+ command error_t cancel(message_t* msg);
+ event void sendDone(message_t* msg, error_t error);
+ command uint8_t maxPayloadLength();
+ command void* getPayload(message_t* msg, uint8_t len);
+ }
+
+The ``send`` command sends a regular message just like ``AMSend.send`` [2]_, but
+it also performs sender-receiver time synchronization. The ``event_time``
+parameter holds the time of some event as expressed in the local clock of the
+sender. The receiver can obtain the time of this event (expressed in its own
+local time) via the ``TimeSyncPacket`` interface.
+
+The rest of the functionality is identical to that of the ``AMSend`` interface,
+therefore its description is omitted here. Please refer to [2]_ for details.
+
+The ``TimeSyncPacket`` interface, parameterized by a precision tag and width,
+allows for retrieving a time value that was sent along the received packet::
+
+ interface TimeSyncPacket<precision_tag, size_type>
+ {
+ command bool isValid(message_t* msg);
+ command size_type eventTime(message_t* msg);
+ }
+
+The ``isValid`` command returns ``TRUE`` if the value returned by
+``eventTime`` can be trusted. Under certain circumstances the received packet
+cannot be properly time stamped, so the sender-receiver synchronization cannot
+be finished on the receiver side. In such case, this command returns ``FALSE``.
+This command MUST be called only on the receiver side and only for messages
+transmitted via the TimeSyncAMSend interface.
+
+The communications stack MUST guarantee that if the ``isValid`` command called
+from within the ``receive`` event handler returns ``TRUE``, then the value
+returned by the ``eventTime`` command can be trusted. However, it might be
+possible that the local clock overflowed more than once or that is was stopped
+or reset since the packet was received, which causes the ``event_time`` to be
+invalid. The ``isValid`` command MAY return ``TRUE`` in such situations, and it
+is the responsibility of the user of the interface to ensure that the clock runs
+freely from the time of message reception to the time when ``eventTime`` is
+called. To avoid this issue, it is recommended that ``isValid`` and
+``eventTime`` are called from the ``receive`` event handler.
+
+The ``eventTime`` command should be called by the receiver of a packet. The
+time of the synchronization event is returned as expressed in the local clock of
+the caller. This command MUST BE called only on the receiver side and only for
+messages transmitted via the ``TimeSyncAMSend`` interface.
+
+3. HIL requirements
+============================================================================
+
+The signature of the platform's ActiveMessageC [5]_ MUST include::
+
+ provides interface TimeSyncAMSend<TMilli, uint32_t>;
+ provides interface TimeSyncPacket<TMilli, uint32_t>;
+
+where event times are given in the node's local time, which is available through
+``HILTimerMilliC.LocalTime``.
+
+The communications stack MAY support timestamp precisions and widths other than
+``TMilli`` and uint32_t, respectively. Also, alternative ``TimeSyncAMSend`` and
+``TimeSyncPacket`` implementations MAY use clock sources other than
+``HILTimerMilliC.LocalTime``.
+
+4. Implementation guidelines
+============================================================================
+
+Packet-level time synchronization employs the ETA primitives. In this TEP, only
+the basics of the time synchronization mechanism are described, for details
+please see [1]_. This section presents two possible implementation approaches.
+The first approach assumes that the payload of the packet is still mutable when
+the transmission time of the packet (e.g. the timestamp of the SFD interrupt)
+becomes available. The second approach avoids this assumption and uses the
+packet timestamping functionality described in TEP [4]_ to implement packet-
+level time synchronization.
+
+4.1 Approach #1
+----------------------------------------------------------------------------
+
+Several transceivers allow for modifying the contents of a packet after packet
+transmission is started. Packet-level time synchronization can be implemented
+very efficiently on such platforms.
+
+Transmitter's story
+
+ - When the communications stack services a ``TimeSyncAMSend.send`` command called
+ with event timestamp ``t_e``, it stores ``t_e`` (e.g. in a map with the pointer
+ of the message_t as key) and sets the designated timestamp field in the packet
+ payload to ``0x80000000``.
+
+ - When the packet starts being transmitted over the communication medium, a
+ corresponding hardware event is timestamped (e.g. an SFD interrupt). Let us
+ denote this transmission timestamp with ``t_tx``. The difference of event
+ timestamp ``t_e`` and transmit timestamp ``t_tx`` is written into the
+ designated timestamp field in the payload of the packet (typically into the
+ footer, since the first few bytes might have been transmitted by this time).
+ That is, the information the packet contains at the instance when being sent
+ over the communications medium is the age of the event (i.e. how much time ago
+ the event had occurred).
+
+ - If an error occurs with timestamping the transmission or with writing the
+ package payload after transmission has started, then the designated timestamp
+ field in the packet payload will contain ``0x80000000``, indicating the error
+ to the receiver.
+
+Receiver's story
+
+ - The packet is timestamped with the receiver node's local clock at reception
+ (e.g. with the timestamp of the SFD interrupt). Let us denote the time of
+ reception with ``t_rx``. The reception timestamp is stored in the metadata
+ structure of the ``message_t`` [5]_.
+
+ - When the event time is queried via the ``TimeSyncPacket`` interface, the
+ ``eventTime`` command returns the sum of the value stored in the designated
+ timestamp field in packet payload and the reception timestamp, i.e. ``e_t-
+ e_tx+e_rx``. This value corresponds to the time of the event in the receiver's
+ local clock.
+
+ - The ``TimeSyncPacket.isValid`` command returns ``FALSE`` if the time
+ value stored in the payload equals ``0x80000000`` or if the communications
+ stack failed to timestamp the reception of the packet. Otherwise ``TRUE`` is
+ returned, which indicates that the value returned by
+ ``TimeSyncPacket.eventTime`` can be trusted.
+
+
+4.1 Approach #2
+----------------------------------------------------------------------------
+
+If a particular platform does not support changing the packet contents after the
+synchronization event (start of transmission, SFD interrupt, etc.) had occured,
+it is still possible to provide packet-level time synchronization functionality
+at the cost of some communication overhead. Such an approach can rely on packet
+timestamping TEP [4]_ to implement packet-level time synchronization.
+
+Transmitter's story
+
+ - When the communications stack services a ``TimeSyncAMSend.send`` command
+ called with event timestamp ``t_e``, it stores ``t_e`` (e.g. in a map with the
+ pointer of the message_t as key) and sends the packet.
+
+ - Transmission of the packet is timestamped using the packet timestamping TEP
+ [4]_ mechanism. Let us denote this transmission timestamp with ``t_tx``. The
+ difference of event timestamp ``t_e`` and transmit timestamp ``t_tx`` is sent
+ in an auxilliary packet. That is, the information the auxulary packet contains
+ is the age of the event at the time when the initial packet was transmitted.
+
+Receiver's story
+
+ - The packet is timestamped with the receiver node's local clock at reception
+ (e.g. with the timestamp of the SFD interrupt). Let us denote the time of
+ reception with ``t_rx``. The reception timestamp is stored in the metadata
+ structure of the ``message_t`` [5]_.
+
+ - When the auxilliary packet arrives, the time value it carries (``t_e-t_tx``,
+ the age of the event) is stored in a metadata field of the main packet. The
+ auxilliary packet is discarded, and the receive event is signalled with the
+ pointer to the main packet.
+
+ - When the event time is queried via the ``TimeSyncPacket`` interface, the
+ ``eventTime`` command returns the sum of the value stored in the metadata (age
+ of the event) and the reception timestamp, i.e. ``e_t- e_tx+e_rx``. This value
+ corresponds to the time of the event in the receiver's local clock.
+
+ - The ``TimeSyncPacket.isValid`` command returns ``FALSE`` if the communications
+ stack failed to timestamp the reception of the packet. Otherwise ``TRUE`` is
+ returned, which indicates that the value returned by
+ ``TimeSyncPacket.eventTime`` can be trusted.
+
+5. Reference implementation
+----------------------------------------------------------------------------
+
+A reference implementation of the packet-level time synchronization mechanism
+described in this TEP can be found in ``tinyos-2.x/tos/chips/rf230``.
+
+
+6. Author's Address
+============================================================================
+
+| Miklos Maroti
+| Janos Sallai
+| Institute for Software Integrated Systems
+| Vanderbilt University
+| 2015 Terrace Place
+| Nashville, TN 37203
+| phone: +1 (615) 343-7555
+
+7. Citations
+============================================================================
+
+.. [1] Kusy, B., Dutta, P., Levis, P., Maroti, M., Ledeczi, A., Culler, D., Elapsed Time on Arrival: A simple and versatile primitive for canonical time synchronization services. International Journal of Ad hoc and Ubiquitous Computing, Vol, 2, No. 1, 2006.
+
+.. [2] TEP 116: Packet protocols
+
+.. [3] TEP 102: Timers
+
+.. [4] TEP TBA: Packet timestamping
+
+.. [5] TEP 111: message_t
+
+.. [6] Maroti, M., Kusy, B., Simon, G., and Ledeczi, A. 2004. The flooding time synchronization protocol. In Proceedings of the 2nd international Conference on Embedded Networked Sensor Systems (Baltimore, MD, USA, November 03 - 05, 2004). ACM SenSys '04.
+
+
projects / tinyos-2.x.git / commitdiff