Contiki-NG
tsch-adaptive-timesync.c
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015, SICS Swedish ICT.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  *
31  */
32 
33 /**
34  * \file
35  * TSCH adaptive time synchronization
36  * \author
37  * Atis Elsts <atis.elsts@sics.se>
38  *
39  */
40 
41 /**
42  * \addtogroup tsch
43  * @{
44 */
45 
46 #include "net/mac/tsch/tsch.h"
47 #include <stdio.h>
48 #include <inttypes.h>
49 
50 #if TSCH_ADAPTIVE_TIMESYNC
51 
52 /* Estimated drift of the time-source neighbor. Can be negative.
53  * Units used: ppm multiplied by 256. */
54 static int32_t drift_ppm;
55 /* Ticks compensated locally since the last timesync time */
56 static int32_t compensated_ticks;
57 /* Number of already recorded timesync history entries */
58 static uint8_t timesync_entry_count;
59 /* Since last learning of the drift; may be more than time since last timesync */
60 static uint32_t asn_since_last_learning;
61 /* The last neighbor used for timesync */
62 struct tsch_neighbor *last_timesource_neighbor;
63 
64 /* Units in which drift is stored: ppm * 256 */
65 #define TSCH_DRIFT_UNIT (1000L * 1000 * 256)
66 
67 /*---------------------------------------------------------------------------*/
68 long int
70 {
71  return (long int)drift_ppm / 256;
72 }
73 /*---------------------------------------------------------------------------*/
74 /* Add a value to a moving average estimator */
75 static int32_t
76 timesync_entry_add(int32_t val)
77 {
78 #define NUM_TIMESYNC_ENTRIES 8
79  static int32_t buffer[NUM_TIMESYNC_ENTRIES];
80  static uint8_t pos;
81  int i;
82  if(timesync_entry_count == 0) {
83  pos = 0;
84  }
85  buffer[pos] = val;
86  if(timesync_entry_count < NUM_TIMESYNC_ENTRIES) {
87  timesync_entry_count++;
88  } else {
89  /* We now have accurate drift compensation.
90  * Increase keep-alive timeout. */
91  tsch_set_ka_timeout(TSCH_MAX_KEEPALIVE_TIMEOUT);
92  }
93  pos = (pos + 1) % NUM_TIMESYNC_ENTRIES;
94 
95  val = 0;
96  for(i = 0; i < timesync_entry_count; ++i) {
97  val += buffer[i];
98  }
99  return val / timesync_entry_count;
100 }
101 /*---------------------------------------------------------------------------*/
102 /* Learn the neighbor drift rate at ppm */
103 static void
104 timesync_learn_drift_ticks(uint32_t time_delta_asn, int32_t drift_ticks)
105 {
106  /* should fit in a 32-bit integer */
107  int32_t time_delta_ticks = time_delta_asn * tsch_timing[tsch_ts_timeslot_length];
108  int32_t real_drift_ticks = drift_ticks + compensated_ticks;
109  int32_t last_drift_ppm = (int32_t)(((int64_t)real_drift_ticks * TSCH_DRIFT_UNIT) / time_delta_ticks);
110 
111  drift_ppm = timesync_entry_add(last_drift_ppm);
112 
113  TSCH_LOG_ADD(tsch_log_message,
114  snprintf(log->message, sizeof(log->message),
115  "drift %ld ppm (min/max delta seen: %"PRId32"/%"PRId32")",
117  min_drift_seen, max_drift_seen));
118 }
119 /*---------------------------------------------------------------------------*/
120 /* Either reset or update the neighbor's drift */
121 void
122 tsch_timesync_update(struct tsch_neighbor *n, uint16_t time_delta_asn, int32_t drift_correction)
123 {
124  /* Account the drift if either this is a new timesource,
125  * or the timedelta is not too small, as smaller timedelta
126  * means proportionally larger measurement error. */
127  if(last_timesource_neighbor != n) {
129  last_timesource_neighbor = n;
130  } else {
131  asn_since_last_learning += time_delta_asn;
132  if(asn_since_last_learning >= 4 * TSCH_SLOTS_PER_SECOND) {
133  timesync_learn_drift_ticks(asn_since_last_learning, drift_correction);
134  compensated_ticks = 0;
135  asn_since_last_learning = 0;
136  } else {
137  /* Too small timedelta, do not recalculate the drift to avoid introducing error. instead account for the corrected ticks */
138  compensated_ticks += drift_correction;
139  }
140  }
141  min_drift_seen = MIN(drift_correction, min_drift_seen);
142  max_drift_seen = MAX(drift_correction, max_drift_seen);
143 }
144 /*---------------------------------------------------------------------------*/
145 /* Error-accumulation free compensation algorithm */
146 static int32_t
147 compensate_internal(uint32_t time_delta_usec, int32_t drift_ppm, int32_t *remainder, int16_t *tick_conversion_error)
148 {
149  int64_t d = (int64_t)time_delta_usec * drift_ppm + *remainder;
150  int32_t amount = d / TSCH_DRIFT_UNIT;
151  int32_t amount_ticks;
152 
153  *remainder = (int32_t)(d - amount * TSCH_DRIFT_UNIT);
154 
155  amount += *tick_conversion_error;
156  amount_ticks = US_TO_RTIMERTICKS(amount);
157  *tick_conversion_error = amount - RTIMERTICKS_TO_US(amount_ticks);
158 
159  if(ABS(amount_ticks) > RTIMER_ARCH_SECOND / 128) {
160  TSCH_LOG_ADD(tsch_log_message,
161  snprintf(log->message, sizeof(log->message),
162  "!too big compensation %ld delta %ld", (long int)amount_ticks, (long int)time_delta_usec));
163  amount_ticks = (amount_ticks > 0 ? RTIMER_ARCH_SECOND : -RTIMER_ARCH_SECOND) / 128;
164  }
165 
166  return amount_ticks;
167 }
168 /*---------------------------------------------------------------------------*/
169 /* Do the compensation step before scheduling a new timeslot */
170 int32_t
171 tsch_timesync_adaptive_compensate(rtimer_clock_t time_delta_ticks)
172 {
173  int32_t result = 0;
174  uint32_t time_delta_usec = RTIMERTICKS_TO_US_64(time_delta_ticks);
175 
176  /* compensate, but not if the neighbor is not known */
177  if(drift_ppm && last_timesource_neighbor != NULL) {
178  static int32_t remainder;
179  static int16_t tick_conversion_error;
180  result = compensate_internal(time_delta_usec, drift_ppm,
181  &remainder, &tick_conversion_error);
182  compensated_ticks += result;
183  }
184 
185  if(TSCH_BASE_DRIFT_PPM) {
186  static int32_t base_drift_remainder;
187  static int16_t base_drift_tick_conversion_error;
188  result += compensate_internal(time_delta_usec, 256L * TSCH_BASE_DRIFT_PPM,
189  &base_drift_remainder, &base_drift_tick_conversion_error);
190  }
191 
192  return result;
193 }
194 /*---------------------------------------------------------------------------*/
195 void
197 {
198  last_timesource_neighbor = NULL;
199  drift_ppm = 0;
200  timesync_entry_count = 0;
201  compensated_ticks = 0;
202  asn_since_last_learning = 0;
203 }
204 /*---------------------------------------------------------------------------*/
205 #else /* TSCH_ADAPTIVE_TIMESYNC */
206 /*---------------------------------------------------------------------------*/
207 void
208 tsch_timesync_update(struct tsch_neighbor *n, uint16_t time_delta_asn, int32_t drift_correction)
209 {
210 }
211 /*---------------------------------------------------------------------------*/
212 int32_t
213 tsch_timesync_adaptive_compensate(rtimer_clock_t delta_ticks)
214 {
215  return 0;
216 }
217 void
219 {
220 }
221 /*---------------------------------------------------------------------------*/
222 long int
224 {
225  return 0;
226 }
227 /*---------------------------------------------------------------------------*/
228 #endif /* TSCH_ADAPTIVE_TIMESYNC */
229 /** @} */
#define TSCH_LOG_ADD(log_type, init_code)
Use this macro to add a log to the queue (will be printed out later, after leaving interrupt context)...
Definition: tsch-log.h:141
TSCH neighbor information.
Definition: tsch-types.h:109
void tsch_set_ka_timeout(uint32_t timeout)
Set the desynchronization timeout after which a node sends a unicasst keep-alive (KA) to its time sou...
Definition: tsch.c:190
void tsch_timesync_update(struct tsch_neighbor *n, uint16_t time_delta_asn, int32_t drift_correction)
Updates timesync information for a given neighbor.
int32_t tsch_timesync_adaptive_compensate(rtimer_clock_t delta_ticks)
Computes time compensation for a given point in the future.
Main API declarations for TSCH.
long int tsch_adaptive_timesync_get_drift_ppm(void)
Gives the estimated clock drift w.r.t.
void tsch_adaptive_timesync_reset(void)
Reset the status of the module.