Contiki-NG
tsch-stats.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2017, University of Bristol - http://www.bristol.ac.uk
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  * notice, this list of conditions and the following disclaimer.
9  * 2. Redistributions in binary form must reproduce the above copyright
10  * notice, this list of conditions and the following disclaimer in the
11  * documentation and/or other materials provided with the distribution.
12  * 3. Neither the name of the copyright holder nor the names of its
13  * contributors may be used to endorse or promote products derived
14  * from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26  * SUCH DAMAGE.
27  *
28  */
29 
30 /**
31  * \file
32  * Header file for TSCH statistics
33  * \author
34  * Atis Elsts <atis.elsts@bristol.ac.uk>
35  */
36 
37 /**
38  * \addtogroup tsch
39  * @{
40 */
41 
42 #ifndef __TSCH_STATS_H__
43 #define __TSCH_STATS_H__
44 
45 /********** Includes **********/
46 
47 #include "contiki.h"
48 #include "net/linkaddr.h"
49 #include "net/mac/tsch/tsch-conf.h"
51 
52 /************ Constants ***********/
53 
54 /* Enable the collection of TSCH statistics? */
55 #ifdef TSCH_STATS_CONF_ON
56 #define TSCH_STATS_ON TSCH_STATS_CONF_ON
57 #else
58 #define TSCH_STATS_ON 0
59 #endif
60 
61 /* Enable the collection background noise RSSI? */
62 #ifdef TSCH_STATS_CONF_SAMPLE_NOISE_RSSI
63 #define TSCH_STATS_SAMPLE_NOISE_RSSI TSCH_STATS_CONF_SAMPLE_NOISE_RSSI
64 #else
65 #define TSCH_STATS_SAMPLE_NOISE_RSSI 0
66 #endif
67 
68 /*
69  * How to update a TSCH statistic.
70  * Uses a hardcoded EWMA alpha value equal to 0.125 by default.
71  */
72 #ifdef TSCH_STATS_CONF_EWMA_UPDATE
73 #define TSCH_STATS_EWMA_UPDATE TSCH_STATS_CONF_EWMA_UPDATE
74 #else
75 #define TSCH_STATS_EWMA_UPDATE(x, v) (x) = (((x) * 7 / 8) + (v) / 8)
76 #endif
77 
78 /*
79  * A channel is considered busy if at the sampling instant
80  * it has RSSI higher or equal to this limit.
81  */
82 #ifdef TSCH_STATS_CONF_BUSY_CHANNEL_RSSI
83 #define TSCH_STATS_BUSY_CHANNEL_RSSI TSCH_STATS_CONF_BUSY_CHANNEL_RSSI
84 #else
85 #define TSCH_STATS_BUSY_CHANNEL_RSSI -85
86 #endif
87 
88 /* The period after which stat values are decayed towards the default values */
89 #ifdef TSCH_STATS_CONF_DECAY_INTERVAL
90 #define TSCH_STATS_DECAY_INTERVAL TSCH_STATS_CONF_DECAY_INTERVAL
91 #else
92 #define TSCH_STATS_DECAY_INTERVAL (20ul * 60 * CLOCK_SECOND)
93 #endif
94 
95 /*
96  * The total number of MAC-layer channels.
97  * Sixteen for the IEEE802.15.4 2.4 GHz band.
98  */
99 #ifdef TSCH_STATS_CONF_NUM_CHANNELS
100 #define TSCH_STATS_NUM_CHANNELS TSCH_STATS_CONF_NUM_CHANNELS
101 #else
102 #define TSCH_STATS_NUM_CHANNELS 16
103 #endif
104 
105 /* The number of the first MAC-layer channel. */
106 #ifdef TSCH_STATS_CONF_FIRST_CHANNEL
107 #define TSCH_STATS_FIRST_CHANNEL TSCH_STATS_CONF_FIRST_CHANNEL
108 #else
109 #define TSCH_STATS_FIRST_CHANNEL 11
110 #endif
111 
112 /* Internal: the scaling of the various stats */
113 #define TSCH_STATS_RSSI_SCALING_FACTOR -16
114 #define TSCH_STATS_LQI_SCALING_FACTOR 16
115 #define TSCH_STATS_BINARY_SCALING_FACTOR 4096
116 
117 /*
118  * Transform a statistic from external form to the internal representation.
119  * To transform back, simply divide by the factor.
120  */
121 #define TSCH_STATS_TRANSFORM(x, factor) ((int16_t)(x) * factor)
122 
123 /* The default value for RSSI statistics: -90 dBm */
124 #define TSCH_STATS_DEFAULT_RSSI TSCH_STATS_TRANSFORM(-90, TSCH_STATS_RSSI_SCALING_FACTOR)
125 /* The default value for LQI statistics: 100 */
126 #define TSCH_STATS_DEFAULT_LQI TSCH_STATS_TRANSFORM(100, TSCH_STATS_LQI_SCALING_FACTOR)
127 /* The default value for P_tx (packet transmission probability) statistics: 50% */
128 #define TSCH_STATS_DEFAULT_P_TX (TSCH_STATS_BINARY_SCALING_FACTOR / 2)
129 /* The default value for channel free status: 100% */
130 #define TSCH_STATS_DEFAULT_CHANNEL_FREE TSCH_STATS_BINARY_SCALING_FACTOR
131 
132 /* #define these callbacks to do the adaptive channel selection based on RSSI */
133 /* TSCH_CALLBACK_CHANNEL_STATS_UPDATED(channel, previous_metric); */
134 /* TSCH_CALLBACK_SELECT_CHANNELS(); */
135 
136 
137 /************ Types ***********/
138 
139 typedef uint16_t tsch_stat_t;
140 
141 struct tsch_global_stats {
142  /* the maximum synchronization error */
143  uint32_t max_sync_error;
144  /* number of disassociations */
145  uint16_t num_disassociations;
146 #if TSCH_STATS_SAMPLE_NOISE_RSSI
147  /* per-channel noise estimates */
148  tsch_stat_t noise_rssi[TSCH_STATS_NUM_CHANNELS];
149  /* derived from `noise_rssi` and BUSY_CHANNEL_RSSI */
150  tsch_stat_t channel_free_ewma[TSCH_STATS_NUM_CHANNELS];
151 #endif /* TSCH_STATS_SAMPLE_NOISE_RSSI */
152 };
153 
154 struct tsch_channel_stats {
155  /* EWMA, from receptions */
156  tsch_stat_t rssi;
157  /* EWMA, from receptions */
158  tsch_stat_t lqi;
159  /* EWMA of probability, for unicast transmissions only */
160  tsch_stat_t p_tx_success;
161 };
162 
163 struct tsch_neighbor_stats {
164  struct tsch_channel_stats channel_stats[TSCH_STATS_NUM_CHANNELS];
165 };
166 
167 struct tsch_neighbor; /* Forward declaration */
168 
169 
170 /************ External variables ***********/
171 
172 #if TSCH_STATS_ON
173 
174 /* Statistics for the local node */
175 extern struct tsch_global_stats tsch_stats;
176 
177 /* For the timesource neighbor */
178 extern struct tsch_neighbor_stats tsch_neighbor_stats;
179 
180 
181 /************ Functions ***********/
182 
183 void tsch_stats_init(void);
184 
185 void tsch_stats_tx_packet(struct tsch_neighbor *, uint8_t mac_status, uint8_t channel);
186 
187 void tsch_stats_rx_packet(struct tsch_neighbor *, int8_t rssi, uint8_t lqi, uint8_t channel);
188 
189 void tsch_stats_on_time_synchronization(int32_t sync_error);
190 
191 void tsch_stats_sample_rssi(void);
192 
193 struct tsch_neighbor_stats *tsch_stats_get_from_neighbor(struct tsch_neighbor *);
194 
195 void tsch_stats_reset_neighbor_stats(void);
196 
197 #else /* TSCH_STATS_ON */
198 
199 #define tsch_stats_init()
200 #define tsch_stats_tx_packet(n, mac_status, channel)
201 #define tsch_stats_rx_packet(n, rssi, lqi, channel)
202 #define tsch_stats_on_time_synchronization(sync_error)
203 #define tsch_stats_sample_rssi()
204 #define tsch_stats_get_from_neighbor(neighbor) NULL
205 #define tsch_stats_reset_neighbor_stats()
206 
207 #endif /* TSCH_STATS_ON */
208 
209 static inline uint8_t
210 tsch_stats_channel_to_index(uint8_t channel)
211 {
212  return channel - TSCH_STATS_FIRST_CHANNEL;
213 }
214 
215 static inline uint8_t
216 tsch_stats_index_to_channel(uint8_t channel_index)
217 {
218  return channel_index + TSCH_STATS_FIRST_CHANNEL;
219 }
220 
221 
222 #endif /* __TSCH_STATS_H__ */
223 /** @} */
TSCH configuration.
TSCH queues.
Header file for the link-layer address representation
TSCH neighbor information.
Definition: tsch-types.h:109