Contiki-NG
tsch.h
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 * \ingroup link-layer
35 * \defgroup tsch 802.15.4 TSCH
36 The IEEE 802.15.4-2015 TimeSlotted Channel Hopping (TSCH) protocol. Provides
37 scheduled communication on top of a globally-synchronized network. Performs
38 frequency hopping for enhanced reliability.
39 * @{
40 * \file
41 * Main API declarations for TSCH.
42 */
43 
44 #ifndef __TSCH_H__
45 #define __TSCH_H__
46 
47 /********** Includes **********/
48 
49 #include "contiki.h"
50 #include "net/mac/mac.h"
51 #include "net/linkaddr.h"
52 
53 #include "net/mac/tsch/tsch-conf.h"
59 #include "net/mac/tsch/tsch-log.h"
64 #if UIP_CONF_IPV6_RPL
65 #include "net/mac/tsch/tsch-rpl.h"
66 #endif /* UIP_CONF_IPV6_RPL */
67 
68 
69 /* Include Arch-Specific conf */
70 #ifdef TSCH_CONF_ARCH_HDR_PATH
71 #include TSCH_CONF_ARCH_HDR_PATH
72 #endif /* TSCH_CONF_ARCH_HDR_PATH */
73 
74 /*********** Callbacks *********/
75 
76 /* Link callbacks to RPL in case RPL is enabled */
77 #if UIP_CONF_IPV6_RPL
78 
79 #ifndef TSCH_CALLBACK_JOINING_NETWORK
80 #define TSCH_CALLBACK_JOINING_NETWORK tsch_rpl_callback_joining_network
81 #endif /* TSCH_CALLBACK_JOINING_NETWORK */
82 
83 #ifndef TSCH_CALLBACK_LEAVING_NETWORK
84 #define TSCH_CALLBACK_LEAVING_NETWORK tsch_rpl_callback_leaving_network
85 #endif /* TSCH_CALLBACK_LEAVING_NETWORK */
86 
87 #ifndef TSCH_CALLBACK_KA_SENT
88 #define TSCH_CALLBACK_KA_SENT tsch_rpl_callback_ka_sent
89 #endif /* TSCH_CALLBACK_KA_SENT */
90 
91 #ifndef TSCH_RPL_CHECK_DODAG_JOINED
92 #define TSCH_RPL_CHECK_DODAG_JOINED tsch_rpl_check_dodag_joined
93 #endif /* TSCH_RPL_CHECK_DODAG_JOINED */
94 
95 #endif /* UIP_CONF_IPV6_RPL */
96 
97 #if BUILD_WITH_ORCHESTRA
98 
99 #ifndef TSCH_CALLBACK_NEW_TIME_SOURCE
100 #define TSCH_CALLBACK_NEW_TIME_SOURCE orchestra_callback_new_time_source
101 #endif /* TSCH_CALLBACK_NEW_TIME_SOURCE */
102 
103 #ifndef TSCH_CALLBACK_PACKET_READY
104 #define TSCH_CALLBACK_PACKET_READY orchestra_callback_packet_ready
105 #endif /* TSCH_CALLBACK_PACKET_READY */
106 
107 #endif /* BUILD_WITH_ORCHESTRA */
108 
109 /* Called by TSCH when joining a network */
110 #ifdef TSCH_CALLBACK_JOINING_NETWORK
111 void TSCH_CALLBACK_JOINING_NETWORK();
112 #endif
113 
114 /* Called by TSCH when leaving a network */
115 #ifdef TSCH_CALLBACK_LEAVING_NETWORK
116 void TSCH_CALLBACK_LEAVING_NETWORK();
117 #endif
118 
119 /* Called by TSCH after sending a keep-alive */
120 #ifdef TSCH_CALLBACK_KA_SENT
121 void TSCH_CALLBACK_KA_SENT();
122 #endif
123 
124 /* Called by TSCH before sending a EB */
125 #ifdef TSCH_RPL_CHECK_DODAG_JOINED
126 int TSCH_RPL_CHECK_DODAG_JOINED();
127 #endif
128 
129 /* Called by TSCH form interrupt after receiving a frame, enabled upper-layer to decide
130  * whether to ACK or NACK */
131 #ifdef TSCH_CALLBACK_DO_NACK
132 int TSCH_CALLBACK_DO_NACK(struct tsch_link *link, linkaddr_t *src, linkaddr_t *dst);
133 #endif
134 
135 /* Called by TSCH when switching time source */
136 #ifdef TSCH_CALLBACK_NEW_TIME_SOURCE
137 struct tsch_neighbor;
138 void TSCH_CALLBACK_NEW_TIME_SOURCE(const struct tsch_neighbor *old, const struct tsch_neighbor *new);
139 #endif
140 
141 /* Called by TSCH every time a packet is ready to be added to the send queue */
142 #ifdef TSCH_CALLBACK_PACKET_READY
143 int TSCH_CALLBACK_PACKET_READY(void);
144 #endif
145 
146 /***** External Variables *****/
147 
148 /* Are we coordinator of the TSCH network? */
149 extern int tsch_is_coordinator;
150 /* Are we associated to a TSCH network? */
151 extern int tsch_is_associated;
152 /* Is the PAN running link-layer security? */
153 extern int tsch_is_pan_secured;
154 /* The TSCH MAC driver */
155 extern const struct mac_driver tschmac_driver;
156 /* 802.15.4 broadcast MAC address */
157 extern const linkaddr_t tsch_broadcast_address;
158 /* The address we use to identify EB queue */
159 extern const linkaddr_t tsch_eb_address;
160 /* The current Absolute Slot Number (ASN) */
161 extern struct tsch_asn_t tsch_current_asn;
162 extern uint8_t tsch_join_priority;
163 extern struct tsch_link *current_link;
164 /* If we are inside a slot, these tell the current channel and channel offset */
165 extern uint8_t tsch_current_channel;
166 extern uint8_t tsch_current_channel_offset;
167 /* TSCH channel hopping sequence */
168 extern uint8_t tsch_hopping_sequence[TSCH_HOPPING_SEQUENCE_MAX_LEN];
169 extern struct tsch_asn_divisor_t tsch_hopping_sequence_length;
170 /* TSCH timeslot timing (in micro-second) */
171 extern tsch_timeslot_timing_usec tsch_timing_us;
172 /* TSCH timeslot timing (in rtimer ticks) */
173 extern tsch_timeslot_timing_ticks tsch_timing;
174 /* Statistics on the current session */
175 extern unsigned long tx_count;
176 extern unsigned long rx_count;
177 extern unsigned long sync_count;
178 extern int32_t min_drift_seen;
179 extern int32_t max_drift_seen;
180 /* The TSCH standard 10ms timeslot timing */
182 
183 /* TSCH processes */
184 PROCESS_NAME(tsch_process);
185 PROCESS_NAME(tsch_send_eb_process);
186 PROCESS_NAME(tsch_pending_events_process);
187 
188 
189 /********** Functions *********/
190 
191 /**
192  * Set the TSCH join priority (JP)
193  *
194  * \param jp the new join priority
195  */
196 void tsch_set_join_priority(uint8_t jp);
197 /**
198  * Set the period at wich TSCH enhanced beacons (EBs) are sent. The period can
199  * not be set to exceed TSCH_MAX_EB_PERIOD. Set to 0 to stop sending EBs.
200  * Actual transmissions are jittered, spaced by a random number within
201  * [period*0.75, period[
202  * If RPL is used, the period will be automatically reset by RPL
203  * equal to the DIO period whenever the DIO period changes.
204  * Hence, calling `tsch_set_eb_period(0)` is NOT sufficient to disable sending EB!
205  * To do that, either configure the node in RPL leaf mode, or
206  * use static config for TSCH (`define TSCH_CONF_EB_PERIOD 0`).
207  *
208  * \param period The period in Clock ticks.
209  */
210 void tsch_set_eb_period(uint32_t period);
211 /**
212  * Set the desynchronization timeout after which a node sends a unicasst
213  * keep-alive (KA) to its time source. Set to 0 to stop sending KAs. The
214  * actual timeout is a random number within [timeout*0.9, timeout[
215  * Can be called from an interrupt.
216  *
217  * \param timeout The timeout in Clock ticks.
218  */
219 void tsch_set_ka_timeout(uint32_t timeout);
220 /**
221  * Set the node as PAN coordinator
222  *
223  * \param enable 1 to be coordinator, 0 to be a node
224  */
225 void tsch_set_coordinator(int enable);
226 /**
227  * Enable/disable security. If done at the coordinator, the Information
228  * will be included in EBs, and all nodes will adopt the same security level.
229  * Enabling requires compilation with LLSEC802154_ENABLED set.
230  * Note: when LLSEC802154_ENABLED is set, nodes boot with security enabled.
231  *
232  * \param enable 1 to enable security, 0 to disable it
233  */
234 void tsch_set_pan_secured(int enable);
235 /**
236  * Schedule a keep-alive transmission within [timeout*0.9, timeout[
237  * Can be called from an interrupt.
238  * @see tsch_set_ka_timeout
239  *
240  * \param immediate send immediately when 1, schedule using current timeout when 0
241  */
242 void tsch_schedule_keepalive(int immediate);
243 /**
244  * Get the time, in clock ticks, since the TSCH network was started.
245  *
246  * \return The network uptime, or -1 if the node is not part of a TSCH network.
247  */
248 uint64_t tsch_get_network_uptime_ticks(void);
249 /**
250  * Leave the TSCH network we are currently in
251  */
252 void tsch_disassociate(void);
253 
254 #endif /* __TSCH_H__ */
255 /** @} */
TSCH constants.
TSCH configuration.
TSCH queues.
TSCH types.
TSCH-RPL interaction.
The structure of a MAC protocol driver in Contiki.
Definition: mac.h:62
void tsch_set_join_priority(uint8_t jp)
Set the TSCH join priority (JP)
Definition: tsch.c:184
Header file for the link-layer address representation
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
TSCH runtime operation within timeslots.
rtimer_clock_t tsch_timeslot_timing_ticks[tsch_ts_elements_count]
TSCH timeslot timing elements in rtimer ticks.
Definition: tsch-types.h:146
For quick modulo operation on ASN.
Definition: tsch-asn.h:54
void tsch_set_eb_period(uint32_t period)
Set the period at wich TSCH enhanced beacons (EBs) are sent.
Definition: tsch.c:197
void tsch_schedule_keepalive(int immediate)
Schedule a keep-alive transmission within [timeout*0.9, timeout[ Can be called from an interrupt...
Definition: tsch.c:330
#define PROCESS_NAME(name)
Declare the name of a process.
Definition: process.h:286
TSCH adaptive time synchronization.
TSCH security.
uint64_t tsch_get_network_uptime_ticks(void)
Get the time, in clock ticks, since the TSCH network was started.
Header file for TSCH statistics
uint16_t tsch_timeslot_timing_usec[tsch_ts_elements_count]
TSCH timeslot timing elements in micro-seconds.
Definition: tsch-types.h:149
void tsch_disassociate(void)
Leave the TSCH network we are currently in.
Definition: tsch.c:567
void tsch_set_pan_secured(int enable)
Enable/disable security.
Definition: tsch.c:178
TSCH packet parsing and creation.
TSCH scheduling engine.
The ASN is an absolute slot number over 5 bytes.
Definition: tsch-asn.h:48
const tsch_timeslot_timing_usec tsch_timeslot_timing_us_10000
TSCH timing attributes and description.
MAC driver header file
void tsch_set_coordinator(int enable)
Set the node as PAN coordinator.
Definition: tsch.c:168
TSCH per-slot logging.