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"
63 #if UIP_CONF_IPV6_RPL
64 #include "net/mac/tsch/tsch-rpl.h"
65 #endif /* UIP_CONF_IPV6_RPL */
66 
67 #if CONTIKI_TARGET_COOJA
68 #include "lib/simEnvChange.h"
69 #include "sys/cooja_mt.h"
70 #endif /* CONTIKI_TARGET_COOJA */
71 
72 /*********** Macros *********/
73 
74 /* Wait for a condition with timeout t0+offset. */
75 #if CONTIKI_TARGET_COOJA
76 #define BUSYWAIT_UNTIL_ABS(cond, t0, offset) \
77  while(!(cond) && RTIMER_CLOCK_LT(RTIMER_NOW(), (t0) + (offset))) { \
78  simProcessRunValue = 1; \
79  cooja_mt_yield(); \
80  };
81 #else
82 #define BUSYWAIT_UNTIL_ABS(cond, t0, offset) \
83  while(!(cond) && RTIMER_CLOCK_LT(RTIMER_NOW(), (t0) + (offset))) ;
84 #endif /* CONTIKI_TARGET_COOJA */
85 
86 /*********** Callbacks *********/
87 
88 /* Link callbacks to RPL in case RPL is enabled */
89 #if UIP_CONF_IPV6_RPL
90 
91 #ifndef TSCH_CALLBACK_JOINING_NETWORK
92 #define TSCH_CALLBACK_JOINING_NETWORK tsch_rpl_callback_joining_network
93 #endif /* TSCH_CALLBACK_JOINING_NETWORK */
94 
95 #ifndef TSCH_CALLBACK_LEAVING_NETWORK
96 #define TSCH_CALLBACK_LEAVING_NETWORK tsch_rpl_callback_leaving_network
97 #endif /* TSCH_CALLBACK_LEAVING_NETWORK */
98 
99 #ifndef TSCH_CALLBACK_KA_SENT
100 #define TSCH_CALLBACK_KA_SENT tsch_rpl_callback_ka_sent
101 #endif /* TSCH_CALLBACK_KA_SENT */
102 
103 #endif /* UIP_CONF_IPV6_RPL */
104 
105 #if BUILD_WITH_ORCHESTRA
106 
107 #ifndef TSCH_CALLBACK_NEW_TIME_SOURCE
108 #define TSCH_CALLBACK_NEW_TIME_SOURCE orchestra_callback_new_time_source
109 #endif /* TSCH_CALLBACK_NEW_TIME_SOURCE */
110 
111 #ifndef TSCH_CALLBACK_PACKET_READY
112 #define TSCH_CALLBACK_PACKET_READY orchestra_callback_packet_ready
113 #endif /* TSCH_CALLBACK_PACKET_READY */
114 
115 #endif /* BUILD_WITH_ORCHESTRA */
116 
117 /* Called by TSCH when joining a network */
118 #ifdef TSCH_CALLBACK_JOINING_NETWORK
119 void TSCH_CALLBACK_JOINING_NETWORK();
120 #endif
121 
122 /* Called by TSCH when leaving a network */
123 #ifdef TSCH_CALLBACK_LEAVING_NETWORK
124 void TSCH_CALLBACK_LEAVING_NETWORK();
125 #endif
126 
127 /* Called by TSCH after sending a keep-alive */
128 #ifdef TSCH_CALLBACK_KA_SENT
129 void TSCH_CALLBACK_KA_SENT();
130 #endif
131 
132 /* Called by TSCH form interrupt after receiving a frame, enabled upper-layer to decide
133  * whether to ACK or NACK */
134 #ifdef TSCH_CALLBACK_DO_NACK
135 int TSCH_CALLBACK_DO_NACK(struct tsch_link *link, linkaddr_t *src, linkaddr_t *dst);
136 #endif
137 
138 /* Called by TSCH when switching time source */
139 #ifdef TSCH_CALLBACK_NEW_TIME_SOURCE
140 struct tsch_neighbor;
141 void TSCH_CALLBACK_NEW_TIME_SOURCE(const struct tsch_neighbor *old, const struct tsch_neighbor *new);
142 #endif
143 
144 /* Called by TSCH every time a packet is ready to be added to the send queue */
145 #ifdef TSCH_CALLBACK_PACKET_READY
146 void TSCH_CALLBACK_PACKET_READY(void);
147 #endif
148 
149 /***** External Variables *****/
150 
151 /* Are we coordinator of the TSCH network? */
152 extern int tsch_is_coordinator;
153 /* Are we associated to a TSCH network? */
154 extern int tsch_is_associated;
155 /* Is the PAN running link-layer security? */
156 extern int tsch_is_pan_secured;
157 /* The TSCH MAC driver */
158 extern const struct mac_driver tschmac_driver;
159 /* 802.15.4 broadcast MAC address */
160 extern const linkaddr_t tsch_broadcast_address;
161 /* The address we use to identify EB queue */
162 extern const linkaddr_t tsch_eb_address;
163 /* The current Absolute Slot Number (ASN) */
164 extern struct tsch_asn_t tsch_current_asn;
165 extern uint8_t tsch_join_priority;
166 extern struct tsch_link *current_link;
167 /* If we are inside a slot, this tells the current channel */
168 extern uint8_t tsch_current_channel;
169 /* TSCH channel hopping sequence */
170 extern uint8_t tsch_hopping_sequence[TSCH_HOPPING_SEQUENCE_MAX_LEN];
171 extern struct tsch_asn_divisor_t tsch_hopping_sequence_length;
172 /* TSCH timeslot timing (in rtimer ticks) */
173 extern rtimer_clock_t tsch_timing[tsch_ts_elements_count];
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 
179 /* TSCH processes */
180 PROCESS_NAME(tsch_process);
181 PROCESS_NAME(tsch_send_eb_process);
182 PROCESS_NAME(tsch_pending_events_process);
183 
184 
185 /********** Functions *********/
186 
187 /**
188  * Set the TSCH join priority (JP)
189  *
190  * \param jp the new join priority
191  */
192 void tsch_set_join_priority(uint8_t jp);
193 /**
194  * Set the period at wich TSCH enhanced beacons (EBs) are sent. The period can
195  * not be set to exceed TSCH_MAX_EB_PERIOD. Set to 0 to stop sending EBs.
196  * Actual transmissions are jittered, spaced by a random number within
197  * [period*0.75, period[
198  *
199  * \param period The period in Clock ticks.
200  */
201 void tsch_set_eb_period(uint32_t period);
202 /**
203  * Set the desynchronization timeout after which a node sends a unicasst
204  * keep-alive (KA) to its time source. Set to 0 to stop sending KAs. The
205  * actual timeout is a random number within
206  * [timeout*0.9, timeout[
207  *
208  * \param timeout The timeout in Clock ticks.
209  */
210 void tsch_set_ka_timeout(uint32_t timeout);
211 /**
212  * Set the node as PAN coordinator
213  *
214  * \param enable 1 to be coordinator, 0 to be a node
215  */
216 void tsch_set_coordinator(int enable);
217 /**
218  * Enable/disable security. If done at the coordinator, the Information
219  * will be included in EBs, and all nodes will adopt the same security level.
220  * Enabling requires compilation with LLSEC802154_ENABLED set.
221  * Note: when LLSEC802154_ENABLED is set, nodes boot with security enabled.
222  *
223  * \param enable 1 to enable security, 0 to disable it
224  */
225 void tsch_set_pan_secured(int enable);
226 /**
227  * Schedule a keep-alive transmission within [timeout*0.9, timeout[
228  * @see tsch_set_ka_timeout
229  */
230 void tsch_schedule_keepalive(void);
231 /**
232  * Schedule a keep-alive immediately
233  */
235 /**
236  * Leave the TSCH network we are currently in
237  */
238 void tsch_disassociate(void);
239 
240 #endif /* __TSCH_H__ */
241 /** @} */
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:193
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:199
void tsch_schedule_keepalive_immediately(void)
Schedule a keep-alive immediately.
Definition: tsch.c:326
TSCH runtime operation within timeslots.
void tsch_schedule_keepalive(void)
Schedule a keep-alive transmission within [timeout*0.9, timeout[.
Definition: tsch.c:314
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:210
#define PROCESS_NAME(name)
Declare the name of a process.
Definition: process.h:286
TSCH adaptive time synchronization.
TSCH security.
void tsch_disassociate(void)
Leave the TSCH network we are currently in.
Definition: tsch.c:501
void tsch_set_pan_secured(int enable)
Enable/disable security.
Definition: tsch.c:187
TSCH packet parsing and creation.
TSCH scheduling engine.
The ASN is an absolute slot number over 5 bytes.
Definition: tsch-asn.h:48
MAC driver header file
void tsch_set_coordinator(int enable)
Set the node as PAN coordinator.
Definition: tsch.c:177
TSCH per-slot logging.