Contiki 2.6
|
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 /** @} */