OpenWSN Firmware
IEEE802154E.h
Go to the documentation of this file.
1 #ifndef __IEEE802154E_H
2 #define __IEEE802154E_H
3 
11 #include "openwsn.h"
12 #include "board.h"
13 #include "schedule.h"
14 #include "processIE.h"
15 
16 //=========================== debug define ====================================
17 
18 //=========================== define ==========================================
19 
20 #define SYNCHRONIZING_CHANNEL 20 // channel the mote listens on to synchronize
21 #define TXRETRIES 3 // number of MAC retries before declaring failed
22 #define TX_POWER 31 // 1=-25dBm, 31=0dBm (max value)
23 #define RESYNCHRONIZATIONGUARD 5 // in 32kHz ticks. min distance to the end of the slot to successfully synchronize
24 #define US_PER_TICK 30 // number of us per 32kHz clock tick
25 #define ADVTIMEOUT 30 // in seconds: sending ADV every 30 seconds
26 #define MAXKAPERIOD 2000 // in slots: @15ms per slot -> ~30 seconds. Max value used by adaptive synchronization.
27 #define DESYNCTIMEOUT 2333 // in slots: @15ms per slot -> ~35 seconds. A larger DESYNCTIMEOUT is needed if using a larger KATIMEOUT.
28 #define LIMITLARGETIMECORRECTION 5 // threshold number of ticks to declare a timeCorrection "large"
29 #define LENGTH_IEEE154_MAX 128 // max length of a valid radio packet
30 #define DUTY_CYCLE_WINDOW_LIMIT (0xFFFFFFFF>>1) // limit of the dutycycle window
31 
32 //15.4e information elements related
33 #define IEEE802154E_PAYLOAD_DESC_LEN_SHIFT 0x04
34 #define IEEE802154E_PAYLOAD_DESC_GROUP_ID_MLME (1<<1)
35 #define IEEE802154E_DESC_TYPE_LONG 0x01
36 #define IEEE802154E_DESC_TYPE_SHORT 0x00
37 
38 #define IEEE802154E_DESC_TYPE_HEADER_IE 0x00
39 #define IEEE802154E_DESC_TYPE_PAYLOAD_IE 0x01
40 //len field on PAYLOAD/HEADER DESC
41 #define IEEE802154E_DESC_LEN_HEADER_IE_MASK 0xFE00
42 #define IEEE802154E_DESC_LEN_PAYLOAD_IE_MASK 0xFFE0
43 
44 #define IEEE802154E_DESC_LEN_HEADER_IE_SHIFT 9
45 #define IEEE802154E_DESC_LEN_PAYLOAD_IE_SHIFT 5
46 
47 //groupID/elementID field on PAYLOAD/HEADER DESC
48 #define IEEE802154E_DESC_ELEMENTID_HEADER_IE_MASK 0x01FE
49 #define IEEE802154E_DESC_GROUPID_PAYLOAD_IE_MASK 0x001E
50 
51 #define IEEE802154E_DESC_ELEMENTID_HEADER_IE_SHIFT 1
52 #define IEEE802154E_DESC_GROUPID_PAYLOAD_IE_SHIFT 1
53 
54 //MLME Sub IE LONG page 83
55 #define IEEE802154E_DESC_LEN_LONG_MLME_IE_MASK 0xFFE0
56 #define IEEE802154E_DESC_SUBID_LONG_MLME_IE_MASK 0x001E
57 
58 #define IEEE802154E_DESC_LEN_LONG_MLME_IE_SHIFT 5
59 #define IEEE802154E_DESC_SUBID_LONG_MLME_IE_SHIFT 1
60 
61 //MLME Sub IE SHORT page 82
62 #define IEEE802154E_DESC_LEN_SHORT_MLME_IE_MASK 0xFF00
63 #define IEEE802154E_DESC_SUBID_SHORT_MLME_IE_MASK 0x00FE
64 
65 #define IEEE802154E_DESC_LEN_SHORT_MLME_IE_SHIFT 8
66 #define IEEE802154E_DESC_SUBID_SHORT_MLME_IE_SHIFT 1
67 
68 #define IEEE802154E_MLME_SYNC_IE_SUBID 0x1A
69 #define IEEE802154E_MLME_SYNC_IE_SUBID_SHIFT 1
70 #define IEEE802154E_MLME_SLOTFRAME_LINK_IE_SUBID 0x1B
71 #define IEEE802154E_MLME_SLOTFRAME_LINK_IE_SUBID_SHIFT 1
72 #define IEEE802154E_MLME_TIMESLOT_IE_SUBID 0x1c
73 #define IEEE802154E_MLME_TIMESLOT_IE_SUBID_SHIFT 1
74 
75 #define IEEE802154E_MLME_IE_GROUPID 0x01
76 #define IEEE802154E_ACK_NACK_TIMECORRECTION_ELEMENTID 0x1E
77 
89 #define FIRST_FRAME_BYTE 1
90 
91 // the different states of the IEEE802.15.4e state machine
92 typedef enum {
93  S_SLEEP = 0x00, // ready for next slot
94  // synchronizing
95  S_SYNCLISTEN = 0x01, // listened for packet to synchronize to network
96  S_SYNCRX = 0x02, // receiving packet to synchronize to network
97  S_SYNCPROC = 0x03, // processing packet just received
98  // TX
99  S_TXDATAOFFSET = 0x04, // waiting to prepare for Tx data
100  S_TXDATAPREPARE = 0x05, // preparing for Tx data
101  S_TXDATAREADY = 0x06, // ready to Tx data, waiting for 'go'
102  S_TXDATADELAY = 0x07, // 'go' signal given, waiting for SFD Tx data
103  S_TXDATA = 0x08, // Tx data SFD received, sending bytes
104  S_RXACKOFFSET = 0x09, // Tx data done, waiting to prepare for Rx ACK
105  S_RXACKPREPARE = 0x0a, // preparing for Rx ACK
106  S_RXACKREADY = 0x0b, // ready to Rx ACK, waiting for 'go'
107  S_RXACKLISTEN = 0x0c, // idle listening for ACK
108  S_RXACK = 0x0d, // Rx ACK SFD received, receiving bytes
109  S_TXPROC = 0x0e, // processing sent data
110  // RX
111  S_RXDATAOFFSET = 0x0f, // waiting to prepare for Rx data
112  S_RXDATAPREPARE = 0x10, // preparing for Rx data
113  S_RXDATAREADY = 0x11, // ready to Rx data, waiting for 'go'
114  S_RXDATALISTEN = 0x12, // idle listening for data
115  S_RXDATA = 0x13, // data SFD received, receiving more bytes
116  S_TXACKOFFSET = 0x14, // waiting to prepare for Tx ACK
117  S_TXACKPREPARE = 0x15, // preparing for Tx ACK
118  S_TXACKREADY = 0x16, // Tx ACK ready, waiting for 'go'
119  S_TXACKDELAY = 0x17, // 'go' signal given, waiting for SFD Tx ACK
120  S_TXACK = 0x18, // Tx ACK SFD received, sending bytes
121  S_RXPROC = 0x19, // processing received data
123 
124 // Atomic durations
125 // expressed in 32kHz ticks:
126 // - ticks = duration_in_seconds * 32768
127 // - duration_in_seconds = ticks / 32768
129  // time-slot related
130  TsTxOffset = 131, // 4000us
131  TsLongGT = 43, // 1300us
132  TsTxAckDelay = 151, // 4606us
133  TsShortGT = 16, // 500us
134  TsSlotDuration = PORT_TsSlotDuration, // 15000us
135  // execution speed related
136  maxTxDataPrepare = PORT_maxTxDataPrepare,
137  maxRxAckPrepare = PORT_maxRxAckPrepare,
138  maxRxDataPrepare = PORT_maxRxDataPrepare,
139  maxTxAckPrepare = PORT_maxTxAckPrepare,
140  // radio speed related
141  delayTx = PORT_delayTx, // between GO signal and SFD
142  delayRx = PORT_delayRx, // between GO signal and start listening
143  // radio watchdog
144  wdRadioTx = 33, // 1000us (needs to be >delayTx)
145  wdDataDuration = 164, // 5000us (measured 4280us with max payload)
146  wdAckDuration = 98, // 3000us (measured 1000us)
147 };
148 
149 //shift of bytes in the linkOption bitmap
155 };
156 
157 // FSM timer durations (combinations of atomic durations)
158 // TX
159 #define DURATION_tt1 ieee154e_vars.lastCapturedTime+TsTxOffset-delayTx-maxTxDataPrepare
160 #define DURATION_tt2 ieee154e_vars.lastCapturedTime+TsTxOffset-delayTx
161 #define DURATION_tt3 ieee154e_vars.lastCapturedTime+TsTxOffset-delayTx+wdRadioTx
162 #define DURATION_tt4 ieee154e_vars.lastCapturedTime+wdDataDuration
163 #define DURATION_tt5 ieee154e_vars.lastCapturedTime+TsTxAckDelay-TsShortGT-delayRx-maxRxAckPrepare
164 #define DURATION_tt6 ieee154e_vars.lastCapturedTime+TsTxAckDelay-TsShortGT-delayRx
165 #define DURATION_tt7 ieee154e_vars.lastCapturedTime+TsTxAckDelay+TsShortGT
166 #define DURATION_tt8 ieee154e_vars.lastCapturedTime+wdAckDuration
167 // RX
168 #define DURATION_rt1 ieee154e_vars.lastCapturedTime+TsTxOffset-TsLongGT-delayRx-maxRxDataPrepare
169 #define DURATION_rt2 ieee154e_vars.lastCapturedTime+TsTxOffset-TsLongGT-delayRx
170 #define DURATION_rt3 ieee154e_vars.lastCapturedTime+TsTxOffset+TsLongGT
171 #define DURATION_rt4 ieee154e_vars.lastCapturedTime+wdDataDuration
172 #define DURATION_rt5 ieee154e_vars.lastCapturedTime+TsTxAckDelay-delayTx-maxTxAckPrepare
173 #define DURATION_rt6 ieee154e_vars.lastCapturedTime+TsTxAckDelay-delayTx
174 #define DURATION_rt7 ieee154e_vars.lastCapturedTime+TsTxAckDelay-delayTx+wdRadioTx
175 #define DURATION_rt8 ieee154e_vars.lastCapturedTime+wdAckDuration
176 
177 //=========================== typedef =========================================
178 
179 // IEEE802.15.4E acknowledgement (ACK)
180 typedef struct {
181  PORT_SIGNED_INT_WIDTH timeCorrection;
183 
184 // includes payload header IE short + MLME short Header + Sync IE
185 #define ADV_PAYLOAD_LENGTH sizeof(payload_IE_ht) + \
186  sizeof(mlme_IE_ht) + \
187  sizeof(sync_IE_ht)
188 
189 //=========================== module variables ================================
190 
191 typedef struct {
192  // misc
193  asn_t asn; // current absolute slot number
194  slotOffset_t slotOffset; // current slot offset
195  slotOffset_t nextActiveSlotOffset; // next active slot offset
196  PORT_RADIOTIMER_WIDTH deSyncTimeout; // how many slots left before looses sync
197  bool isSync; // TRUE iff mote is synchronized to network
198  // as shown on the chronogram
199  ieee154e_state_t state; // state of the FSM
200  OpenQueueEntry_t* dataToSend; // pointer to the data to send
201  OpenQueueEntry_t* dataReceived; // pointer to the data received
202  OpenQueueEntry_t* ackToSend; // pointer to the ack to send
203  OpenQueueEntry_t* ackReceived; // pointer to the ack received
204  PORT_RADIOTIMER_WIDTH lastCapturedTime; // last captured time
205  PORT_RADIOTIMER_WIDTH syncCapturedTime; // captured time used to sync
206  // channel hopping
207  uint8_t freq; // frequency of the current slot
208  uint8_t asnOffset; // offset inside the frame
209 
210  PORT_RADIOTIMER_WIDTH radioOnInit; // when within the slot the radio turns on
211  PORT_RADIOTIMER_WIDTH radioOnTics; // how many tics within the slot the radio is on
212  bool radioOnThisSlot; // to control if the radio has been turned on in a slot.
214 
215 BEGIN_PACK
216 typedef struct {
217  uint8_t numSyncPkt; // how many times synchronized on a non-ACK packet
218  uint8_t numSyncAck; // how many times synchronized on an ACK
219  int16_t minCorrection; // minimum time correction
220  int16_t maxCorrection; // maximum time correction
221  uint8_t numDeSync; // number of times a desync happened
222  uint32_t numTicsOn; // mac dutyCycle
223  uint32_t numTicsTotal; // total tics for which the dutycycle is computed
225 END_PACK
226 
227 typedef struct {
228  PORT_RADIOTIMER_WIDTH num_newSlot;
229  PORT_RADIOTIMER_WIDTH num_timer;
230  PORT_RADIOTIMER_WIDTH num_startOfFrame;
231  PORT_RADIOTIMER_WIDTH num_endOfFrame;
233 
234 //=========================== prototypes ======================================
235 
236 // admin
237 void ieee154e_init(void);
238 // public
239 PORT_RADIOTIMER_WIDTH ieee154e_asnDiff(asn_t* someASN);
240 bool ieee154e_isSynch(void);
241 void ieee154e_getAsn(uint8_t* array);
242 // events
243 void ieee154e_startOfFrame(PORT_RADIOTIMER_WIDTH capturedTime);
244 void ieee154e_endOfFrame(PORT_RADIOTIMER_WIDTH capturedTime);
245 // misc
246 bool debugPrint_asn(void);
247 bool debugPrint_isSync(void);
248 bool debugPrint_macStats(void);
249 
255 #endif
Definition: IEEE802154E.h:144
port_INLINE void ieee154e_getAsn(uint8_t *array)
Definition: IEEE802154E.c:1710
Definition: IEEE802154E.h:130
PORT_RADIOTIMER_WIDTH num_newSlot
Definition: IEEE802154E.h:228
asn_t asn
Definition: IEEE802154E.h:193
Definition: IEEE802154E.h:102
Definition: IEEE802154E.h:133
ieee154e_state_t
Definition: IEEE802154E.h:92
PORT_RADIOTIMER_WIDTH radioOnInit
Definition: IEEE802154E.h:210
Definition: IEEE802154E.h:104
uint8_t numSyncPkt
Definition: IEEE802154E.h:217
PORT_RADIOTIMER_WIDTH deSyncTimeout
Definition: IEEE802154E.h:196
PORT_RADIOTIMER_WIDTH syncCapturedTime
Definition: IEEE802154E.h:205
Definition: IEEE802154E.h:96
Definition: IEEE802154E.h:100
OpenQueueEntry_t * ackToSend
Definition: IEEE802154E.h:202
Definition: IEEE802154E.h:138
ieee154e_linkOption_enum
Definition: IEEE802154E.h:150
Definition: IEEE802154E.h:153
Definition: IEEE802154E.h:142
Definition: IEEE802154E.h:121
ieee154e_atomicdurations_enum
Definition: IEEE802154E.h:128
Definition: IEEE802154E.h:118
Definition: IEEE802154E.h:145
slotOffset_t slotOffset
Definition: IEEE802154E.h:194
Definition: IEEE802154E.h:117
Definition: IEEE802154E.h:113
Definition: IEEE802154E.h:101
PORT_RADIOTIMER_WIDTH num_endOfFrame
Definition: IEEE802154E.h:231
Definition: IEEE802154E.h:93
OpenQueueEntry_t * dataReceived
Definition: IEEE802154E.h:201
Definition: IEEE802154E.h:137
void ieee154e_endOfFrame(PORT_RADIOTIMER_WIDTH capturedTime)
Indicates the radio just received the last byte of a packet.
Definition: IEEE802154E.c:314
ieee154e_state_t state
Definition: IEEE802154E.h:199
uint8_t numDeSync
Definition: IEEE802154E.h:221
Definition: openwsn.h:268
bool ieee154e_isSynch()
Definition: IEEE802154E.c:2076
PORT_RADIOTIMER_WIDTH radioOnTics
Definition: IEEE802154E.h:211
int16_t minCorrection
Definition: IEEE802154E.h:219
uint32_t numTicsTotal
Definition: IEEE802154E.h:223
Definition: IEEE802154E.h:132
Definition: IEEE802154E.h:131
bool debugPrint_isSync(void)
Trigger this module to print status information, over serial.
Definition: IEEE802154E.c:371
bool debugPrint_macStats()
Trigger this module to print status information, over serial.
Definition: IEEE802154E.c:386
Definition: IEEE802154E.h:191
Definition: IEEE802154E.h:180
Definition: IEEE802154E.h:154
uint8_t asnOffset
Definition: IEEE802154E.h:208
bool debugPrint_asn(void)
Trigger this module to print status information, over serial.
Definition: IEEE802154E.c:354
uint8_t numSyncAck
Definition: IEEE802154E.h:218
Definition: IEEE802154E.h:139
int16_t maxCorrection
Definition: IEEE802154E.h:220
Definition: IEEE802154E.h:136
Definition: IEEE802154E.h:115
PORT_RADIOTIMER_WIDTH num_timer
Definition: IEEE802154E.h:229
Definition: IEEE802154E.h:109
Definition: IEEE802154E.h:134
Definition: IEEE802154E.h:108
Definition: IEEE802154E.h:105
Definition: IEEE802154E.h:120
OpenQueueEntry_t * ackReceived
Definition: IEEE802154E.h:203
Definition: IEEE802154E.h:99
Definition: IEEE802154E.h:111
PORT_RADIOTIMER_WIDTH lastCapturedTime
Definition: IEEE802154E.h:204
Definition: IEEE802154E.h:216
PORT_RADIOTIMER_WIDTH num_startOfFrame
Definition: IEEE802154E.h:230
Definition: IEEE802154E.h:106
Definition: IEEE802154E.h:112
slotOffset_t nextActiveSlotOffset
Definition: IEEE802154E.h:195
Definition: IEEE802154E.h:114
Definition: IEEE802154E.h:107
Definition: IEEE802154E.h:146
Definition: IEEE802154E.h:95
void ieee154e_init()
This function initializes this module.
Definition: IEEE802154E.c:99
Definition: IEEE802154E.h:97
PORT_SIGNED_INT_WIDTH timeCorrection
Definition: IEEE802154E.h:181
uint8_t freq
Definition: IEEE802154E.h:207
bool radioOnThisSlot
Definition: IEEE802154E.h:212
Definition: openwsn.h:288
Definition: IEEE802154E.h:152
Definition: IEEE802154E.h:141
Definition: IEEE802154E.h:227
Definition: IEEE802154E.h:151
PORT_RADIOTIMER_WIDTH ieee154e_asnDiff(asn_t *someASN)
Definition: IEEE802154E.c:135
void ieee154e_startOfFrame(PORT_RADIOTIMER_WIDTH capturedTime)
Indicates the radio just received the first byte of a packet.
Definition: IEEE802154E.c:266
uint32_t numTicsOn
Definition: IEEE802154E.h:222
bool isSync
Definition: IEEE802154E.h:197
uint16_t slotOffset_t
Definition: schedule.h:63
Definition: IEEE802154E.h:119
OpenQueueEntry_t * dataToSend
Definition: IEEE802154E.h:200
Definition: IEEE802154E.h:116
Definition: IEEE802154E.h:103