Contiki 2.6

timesynch.h

Go to the documentation of this file.
00001 /**
00002  * \addtogroup sys
00003  * @{
00004  */
00005 
00006 /**
00007  * \defgroup timesynch Implicit network time synchronization
00008  * @{
00009  *
00010  * This crude and simple network time synchronization module
00011  * synchronizes clocks of all nodes in a network. The time
00012  * synchronization is implicit in that no explicit time
00013  * synchronization messages are sent: the module relies on the
00014  * underlying network device driver to timestamp all radio messages,
00015  * both outgoing and incoming. The code currently only works on the
00016  * Tmote Sky platform and the cc2420 driver.
00017  *
00018  * Every node has an authority level, which is included in every
00019  * outgoing packet. If a message is received from a node with higher
00020  * authority (lower authority number), the node adjusts its clock
00021  * towards the clock of the sending node.
00022  *
00023  * The timesynch module is implemented as a meta-MAC protocol, so that
00024  * the module is invoked for every incoming packet.
00025  *
00026  */
00027 
00028 /*
00029  * Copyright (c) 2007, Swedish Institute of Computer Science.
00030  * All rights reserved.
00031  *
00032  * Redistribution and use in source and binary forms, with or without
00033  * modification, are permitted provided that the following conditions
00034  * are met:
00035  * 1. Redistributions of source code must retain the above copyright
00036  *    notice, this list of conditions and the following disclaimer.
00037  * 2. Redistributions in binary form must reproduce the above copyright
00038  *    notice, this list of conditions and the following disclaimer in the
00039  *    documentation and/or other materials provided with the distribution.
00040  * 3. Neither the name of the Institute nor the names of its contributors
00041  *    may be used to endorse or promote products derived from this software
00042  *    without specific prior written permission.
00043  *
00044  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00045  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00046  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00047  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00048  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00049  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00050  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00051  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00052  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00053  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00054  * SUCH DAMAGE.
00055  *
00056  * This file is part of the Contiki operating system.
00057  *
00058  * $Id: timesynch.h,v 1.4 2008/07/01 21:02:51 adamdunkels Exp $
00059  */
00060 
00061 /**
00062  * \file
00063  *         Header file for a simple time synchronization mechanism
00064  * \author
00065  *         Adam Dunkels <adam@sics.se>
00066  */
00067 
00068 #ifndef __TIMESYNCH_H__
00069 #define __TIMESYNCH_H__
00070 
00071 #include "net/mac/mac.h"
00072 #include "sys/rtimer.h"
00073 
00074 /**
00075  * \brief      Initialize the timesynch module
00076  *
00077  *             This function initializes the timesynch module. This
00078  *             function must not be called before rime_init().
00079  *
00080  */
00081 void timesynch_init(void);
00082 
00083 /**
00084  * \brief      Get the current time-synchronized time
00085  * \return     The current time-synchronized time
00086  *
00087  *             This function returns the current time-synchronized
00088  *             time.
00089  *
00090  */
00091 rtimer_clock_t timesynch_time(void);
00092 
00093 /**
00094  * \brief      Get the current time-synchronized time, suitable for use with the rtimer module
00095  * \return     The current time-synchronized rtimer time
00096  *
00097  *             This function returns the (local) rtimer-equivalent
00098  *             time corresponding to the current time-synchronized
00099  *             (global) time. The rtimer-equivalent time is used for
00100  *             setting rtimer timers that are synchronized to other
00101  *             nodes in the network.
00102  *
00103  */
00104 rtimer_clock_t timesynch_time_to_rtimer(rtimer_clock_t synched_time);
00105 
00106 /**
00107  * \brief      Get the synchronized equivalent of an rtimer time
00108  * \return     The synchronized equivalent of an rtimer time
00109  *
00110  *             This function returns the time synchronized equivalent
00111  *             time corresponding to a (local) rtimer time.
00112  *
00113  */
00114 rtimer_clock_t timesynch_rtimer_to_time(rtimer_clock_t rtimer_time);
00115 
00116 /**
00117  * \brief      Get the current time-synchronized offset from the rtimer clock, which is used mainly for debugging
00118  * \return     The current time-synchronized offset from the rtimer clock
00119  *
00120  *             This function returns the current time-synchronized
00121  *             offset from the rtimer arch clock. This is mainly
00122  *             useful for debugging the timesynch module.
00123  *
00124  */
00125 rtimer_clock_t timesynch_offset(void);
00126 
00127 /**
00128  * \brief      Get the current authority level of the time-synchronized time
00129  * \return     The current authority level of the time-synchronized time
00130  *
00131  *             This function returns the current authority level of
00132  *             the time-synchronized time. A node with a lower
00133  *             authority level is defined to have a better notion of
00134  *             time than a node with a higher authority
00135  *             level. Authority level 0 is best and should be used by
00136  *             a sink node that has a connection to an outside,
00137  *             "true", clock source.
00138  *
00139  */
00140 int timesynch_authority_level(void);
00141 
00142 /**
00143  * \brief      Set the authority level of the current time
00144  * \param level The authority level
00145  */
00146 void timesynch_set_authority_level(int level);
00147 
00148 #endif /* __TIMESYNCH_H__ */
00149 
00150 /** @} */
00151 /** @} */