=================== 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 .. 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 { 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; 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