A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
end-device-lorawan-mac.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2017 University of Padova
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Davide Magrin <magrinda@dei.unipd.it>
7 * Martina Capuzzo <capuzzom@dei.unipd.it>
8 *
9 * Modified by: Peggy Anderson <peggy.anderson@usask.ca>
10 */
11
12#ifndef END_DEVICE_LORAWAN_MAC_H
13#define END_DEVICE_LORAWAN_MAC_H
14
15#include "lora-device-address.h"
16#include "lora-frame-header.h"
17#include "lorawan-mac-header.h"
18#include "lorawan-mac.h"
19
20#include "ns3/random-variable-stream.h"
21#include "ns3/traced-value.h"
22
23namespace ns3
24{
25namespace lorawan
26{
27
28/**
29 * \ingroup lorawan
30 *
31 * Class representing the MAC layer of a LoRaWAN device.
32 */
34{
35 public:
36 /**
37 * Register this type.
38 * \return The object TypeId.
39 */
40 static TypeId GetTypeId();
41
42 EndDeviceLorawanMac(); //!< Default constructor
43 ~EndDeviceLorawanMac() override; //!< Destructor
44
45 /////////////////////
46 // Sending methods //
47 /////////////////////
48
49 /**
50 * Send a packet.
51 *
52 * The MAC layer of the end device will take care of using the right parameters.
53 *
54 * \param packet The packet to send.
55 */
56 void Send(Ptr<Packet> packet) override;
57
58 /**
59 * Checking if we are performing the transmission of a new packet or a retransmission, and call
60 * SendToPhy function.
61 *
62 * \param packet The packet to send.
63 */
64 virtual void DoSend(Ptr<Packet> packet);
65
66 /**
67 * Add headers and send a packet with the sending function of the physical layer.
68 *
69 * \param packet The packet to send.
70 */
71 virtual void SendToPhy(Ptr<Packet> packet);
72
73 /**
74 * Postpone transmission to the specified time and delete previously scheduled transmissions if
75 * present.
76 *
77 * \param nextTxDelay Delay at which the transmission will be performed.
78 * \param packet The packet to delay the transmission of.
79 */
80 virtual void postponeTransmission(Time nextTxDelay, Ptr<Packet> packet);
81
82 ///////////////////////
83 // Receiving methods //
84 ///////////////////////
85
86 /**
87 * Receive a packet.
88 *
89 * This method is typically registered as a callback in the underlying PHY
90 * layer so that it's called when a packet is going up the stack.
91 *
92 * \param packet The received packet.
93 */
94 void Receive(Ptr<const Packet> packet) override;
95
96 void FailedReception(Ptr<const Packet> packet) override;
97
98 /**
99 * Perform the actions that are required after a packet send.
100 *
101 * This function handles opening of the first receive window.
102 *
103 * \param packet The packet that has just been transmitted.
104 */
105 void TxFinished(Ptr<const Packet> packet) override;
106
107 /////////////////////////
108 // Getters and Setters //
109 /////////////////////////
110
111 /**
112 * Reset retransmission parameters contained in the structure LoraRetxParams.
113 */
114 virtual void resetRetransmissionParameters();
115
116 /**
117 * Enable data rate adaptation in the retransmitting procedure.
118 *
119 * \param adapt If the data rate adaptation is enabled or not.
120 */
121 void SetDataRateAdaptation(bool adapt);
122
123 /**
124 * Get if data rate adaptation is enabled or not.
125 *
126 * \return True if the data rate adaptation is enabled, false if disabled.
127 */
128 bool GetDataRateAdaptation() const;
129
130 /**
131 * Set the max number of unacknowledged redundant transmissions of each packet. If,
132 * after a transmission, any acknowledgement is received, no more are sent for that packet.
133 *
134 * \param maxNumbTx The number of transmissions.
135 */
136 void SetMaxNumberOfTransmissions(uint8_t maxNumbTx);
137
138 /**
139 * Get the max number of unacknowledged redundant transmissions of each packet. If,
140 * after a transmission, any acknowledgement is received, no more are sent for that packet.
141 *
142 * \return The number of transmissions as uint8_t.
143 */
145
146 /**
147 * Set the data rate this end device will use when transmitting. For End
148 * Devices, this value is assumed to be fixed, and can be modified via MAC
149 * commands issued by the gateway.
150 *
151 * \param dataRate The dataRate to use when transmitting.
152 */
153 void SetDataRate(uint8_t dataRate);
154
155 /**
156 * Get the data rate this end device is set to use.
157 *
158 * \return The data rate this device uses when transmitting.
159 */
160 uint8_t GetDataRate();
161
162 /**
163 * Get the transmission power this end device is set to use.
164 *
165 * \return The transmission power this device uses when transmitting.
166 */
167 virtual uint8_t GetTransmissionPower();
168
169 /**
170 * Set the network address of this device.
171 *
172 * \param address The address to set.
173 */
175
176 /**
177 * Get the network address of this device.
178 *
179 * \return This device's address.
180 */
182
183 // void SetRx1DrOffset (uint8_t rx1DrOffset);
184
185 // uint8_t GetRx1DrOffset ();
186
187 /**
188 * Get the aggregated duty cycle.
189 *
190 * \return A time instance containing the aggregated duty cycle in fractional form.
191 */
192 double GetAggregatedDutyCycle();
193
194 /////////////////////////
195 // MAC command methods //
196 /////////////////////////
197
198 /**
199 * Add the necessary options and MAC commands to the LoraFrameHeader.
200 *
201 * \param frameHeader The frame header on which to apply the options.
202 */
203 void ApplyNecessaryOptions(LoraFrameHeader& frameHeader);
204
205 /**
206 * Add the necessary options and MAC commands to the LorawanMacHeader.
207 *
208 * \param macHeader The mac header on which to apply the options.
209 */
211
212 /**
213 * Set the message type to send when the Send method is called.
214 *
215 * \param mType The message type.
216 */
218
219 /**
220 * Get the message type to send when the Send method is called.
221 *
222 * \return The message type.
223 */
225
226 /**
227 * Parse and take action on the commands contained on this FrameHeader.
228 *
229 * \param frameHeader The frame header.
230 */
231 void ParseCommands(LoraFrameHeader frameHeader);
232
233 /**
234 * Perform the actions that need to be taken when receiving a LinkCheckAns command.
235 *
236 * \param margin The margin value of the command.
237 * \param gwCnt The gateway count value of the command.
238 */
239 void OnLinkCheckAns(uint8_t margin, uint8_t gwCnt);
240
241 /**
242 * Perform the actions that need to be taken when receiving a LinkAdrReq command.
243 *
244 * \param dataRate The data rate value of the command.
245 * \param txPower The transmission power value of the command.
246 * \param enabledChannels A list of the enabled channels.
247 * \param repetitions The number of repetitions prescribed by the command.
248 */
249 void OnLinkAdrReq(uint8_t dataRate,
250 uint8_t txPower,
251 std::list<int> enabledChannels,
252 int repetitions);
253
254 /**
255 * Perform the actions that need to be taken when receiving a DutyCycleReq command.
256 *
257 * \param dutyCycle The aggregate duty cycle prescribed by the command, in
258 * fraction form.
259 */
260 void OnDutyCycleReq(double dutyCycle);
261
262 /**
263 * Perform the actions that need to be taken when receiving a RxParamSetupReq command.
264 *
265 * \param rxParamSetupReq The Parameter Setup Request.
266 */
267 void OnRxParamSetupReq(Ptr<RxParamSetupReq> rxParamSetupReq);
268
269 /**
270 * Perform the actions that need to be taken when receiving a RxParamSetupReq
271 * command based on the Device's Class Type.
272 *
273 * \param rxParamSetupReq The Parameter Setup Request.
274 */
275 virtual void OnRxClassParamSetupReq(Ptr<RxParamSetupReq> rxParamSetupReq);
276
277 /**
278 * Perform the actions that need to be taken when receiving a DevStatusReq command.
279 */
280 void OnDevStatusReq();
281
282 /**
283 * Perform the actions that need to be taken when receiving a NewChannelReq command.
284 *
285 * \param chIndex The ChIndex field of the received NewChannelReq command.
286 * \param frequency The Frequency field of the received NewChannelReq command.
287 * \param minDataRate The MinDR field of the received NewChannelReq command.
288 * \param maxDataRate The MaxDR field of the received NewChannelReq command.
289 */
290 void OnNewChannelReq(uint8_t chIndex,
291 double frequency,
292 uint8_t minDataRate,
293 uint8_t maxDataRate);
294
295 ////////////////////////////////////
296 // Logical channel administration //
297 ////////////////////////////////////
298
299 /**
300 * Add a logical channel to the helper.
301 *
302 * \param frequency The channel's center frequency.
303 */
304 void AddLogicalChannel(double frequency);
305
306 /**
307 * Set a new logical channel in the helper.
308 *
309 * \param chIndex The channel's new index.
310 * \param frequency The channel's center frequency.
311 * \param minDataRate The minimum data rate allowed on the channel.
312 * \param maxDataRate The maximum data rate allowed on the channel.
313 */
314 void SetLogicalChannel(uint8_t chIndex,
315 double frequency,
316 uint8_t minDataRate,
317 uint8_t maxDataRate);
318
319 /**
320 * Add a logical channel to the helper.
321 *
322 * \param logicalChannel The logical channel to add.
323 */
324 void AddLogicalChannel(Ptr<LogicalLoraChannel> logicalChannel);
325
326 /**
327 * Add a subband to the logical channel helper.
328 *
329 * \param startFrequency The SubBand's lowest frequency.
330 * \param endFrequency The SubBand's highest frequency.
331 * \param dutyCycle The SubBand's duty cycle, in fraction form.
332 * \param maxTxPowerDbm The maximum transmission power allowed on the SubBand.
333 */
334 void AddSubBand(double startFrequency,
335 double endFrequency,
336 double dutyCycle,
337 double maxTxPowerDbm);
338
339 /**
340 * Add a MAC command to the list of those that will be sent out in the next
341 * packet.
342 *
343 * \param macCommand A pointer to the MAC command.
344 */
345 void AddMacCommand(Ptr<MacCommand> macCommand);
346
347 protected:
348 /**
349 * Structure representing the parameters that will be used in the
350 * retransmission procedure.
351 */
353 {
354 Time firstAttempt; //!< Timestamp of the first transmission of the packet
355 Ptr<Packet> packet = nullptr; //!< A pointer to the packet being retransmitted
356 bool waitingAck = false; //!< Whether the packet requires explicit acknowledgment
357 uint8_t retxLeft; //!< Number of retransmission attempts left
358 };
359
360 bool
361 m_enableDRAdapt; //!< Enable data rate adaptation (ADR) during the retransmission procedure.
362 uint8_t
363 m_maxNumbTx; //!< Default number of unacknowledged redundant transmissions of each packet.
364 TracedValue<uint8_t> m_dataRate; //!< The data rate this device is using to transmit.
365 TracedValue<double> m_txPower; //!< The transmission power this device is using to transmit.
366 uint8_t m_codingRate; //!< The coding rate used by this device.
367 bool m_headerDisabled; //!< Whether or not the LoRa PHY header is disabled for communications by
368 //!< this device.
369 LoraDeviceAddress m_address; //!< The address of this device.
370
371 /**
372 * Find the minimum waiting time before the next possible transmission based
373 * on end device's Class Type.
374 *
375 * \param waitingTime Currently known minimum waiting time, possibly raised by this function.
376 * \return The updated minimum waiting time in Time format.
377 */
378 virtual Time GetNextClassTransmissionDelay(Time waitingTime);
379
380 /**
381 * Find a suitable channel for transmission. The channel is chosen among the
382 * ones that are available in the end device, based on their duty
383 * cycle limitations.
384 *
385 * \return A pointer to the channel.
386 */
388
389 /**
390 * The duration of a receive window in number of symbols. This should be
391 * converted to time based or the reception parameter used.
392 *
393 * The downlink preamble transmitted by the gateways contains 8 symbols.
394 * The receiver requires 5 symbols to detect the preamble and synchronize.
395 * Therefore there must be a 5 symbols overlap between the receive window
396 * and the transmitted preamble.
397 * (Ref: Recommended SX1272/76 Settings for EU868 LoRaWAN Network Operation )
398 */
400
401 /**
402 * List of the MAC commands that need to be applied to the next UL packet.
403 */
404 std::list<Ptr<MacCommand>> m_macCommandList;
405
406 /**
407 * Structure containing the retransmission parameters for this device.
408 */
410
411 /**
412 * An uniform random variable, used by the Shuffle method to randomly reorder
413 * the channel list.
414 */
416
417 /////////////////
418 // Callbacks //
419 /////////////////
420
421 /**
422 * The trace source fired when the transmission procedure is finished.
423 */
425
426 private:
427 /**
428 * Randomly shuffle a Ptr<LogicalLoraChannel> vector.
429 *
430 * Used to pick a random channel on which to send the packet.
431 *
432 * \param vector The vector of pointers to logical LoRa channels.
433 * \return The shuffled vector.
434 */
435 std::vector<Ptr<LogicalLoraChannel>> Shuffle(std::vector<Ptr<LogicalLoraChannel>> vector);
436
437 /**
438 * Find the base minimum waiting time before the next possible transmission.
439 *
440 * \return The base minimum waiting time.
441 */
443
444 /**
445 * Whether this device's data rate should be controlled by the network server.
446 */
448
449 /**
450 * The event of retransmitting a packet in a consecutive moment if an ACK is not received.
451 *
452 * This Event is used to cancel the retransmission if the ACK is found in ParseCommand function
453 * and if a newer packet is delivered from the application to be sent.
454 */
456
457 /**
458 * The event of transmitting a packet in a consecutive moment, when the duty cycle let us
459 * transmit.
460 *
461 * This Event is used to cancel the transmission of this packet if a newer packet is delivered
462 * from the application to be sent.
463 */
465
466 /**
467 * The last known link margin.
468 *
469 * This value is obtained (and updated) when a LinkCheckAns Mac command is
470 * received.
471 */
473
474 /**
475 * The last known gateway count (i.e., gateways that are in communication
476 * range with this end device).
477 *
478 * This value is obtained (and updated) when a LinkCheckAns Mac command is
479 * received.
480 */
482
483 /**
484 * The aggregated duty cycle this device needs to respect across all sub-bands.
485 */
487
488 /**
489 * The message type to apply to packets sent with the Send method.
490 */
492
493 /**
494 * current value of the device frame counter.
495 */
497};
498
499} // namespace lorawan
500
501} // namespace ns3
502#endif /* END_DEVICE_LORAWAN_MAC_H */
An identifier for simulation events.
Definition event-id.h:45
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Forward calls to a chain of Callback.
Trace classes with value semantics.
a unique identifier for an interface.
Definition type-id.h:48
Class representing the MAC layer of a LoRaWAN device.
LorawanMacHeader::MType m_mType
The message type to apply to packets sent with the Send method.
uint8_t m_maxNumbTx
Default number of unacknowledged redundant transmissions of each packet.
TracedValue< int > m_lastKnownGatewayCount
The last known gateway count (i.e., gateways that are in communication range with this end device).
bool GetDataRateAdaptation() const
Get if data rate adaptation is enabled or not.
void SetLogicalChannel(uint8_t chIndex, double frequency, uint8_t minDataRate, uint8_t maxDataRate)
Set a new logical channel in the helper.
void FailedReception(Ptr< const Packet > packet) override
Function called by lower layers to inform this layer that reception of a packet we were locked on fai...
virtual void OnRxClassParamSetupReq(Ptr< RxParamSetupReq > rxParamSetupReq)
Perform the actions that need to be taken when receiving a RxParamSetupReq command based on the Devic...
void AddSubBand(double startFrequency, double endFrequency, double dutyCycle, double maxTxPowerDbm)
Add a subband to the logical channel helper.
bool m_headerDisabled
Whether or not the LoRa PHY header is disabled for communications by this device.
bool m_controlDataRate
Whether this device's data rate should be controlled by the network server.
virtual void postponeTransmission(Time nextTxDelay, Ptr< Packet > packet)
Postpone transmission to the specified time and delete previously scheduled transmissions if present.
virtual void SendToPhy(Ptr< Packet > packet)
Add headers and send a packet with the sending function of the physical layer.
Ptr< LogicalLoraChannel > GetChannelForTx()
Find a suitable channel for transmission.
void OnDutyCycleReq(double dutyCycle)
Perform the actions that need to be taken when receiving a DutyCycleReq command.
TracedValue< double > m_txPower
The transmission power this device is using to transmit.
uint8_t m_codingRate
The coding rate used by this device.
bool m_enableDRAdapt
Enable data rate adaptation (ADR) during the retransmission procedure.
void TxFinished(Ptr< const Packet > packet) override
Perform the actions that are required after a packet send.
Ptr< UniformRandomVariable > m_uniformRV
An uniform random variable, used by the Shuffle method to randomly reorder the channel list.
void OnRxParamSetupReq(Ptr< RxParamSetupReq > rxParamSetupReq)
Perform the actions that need to be taken when receiving a RxParamSetupReq command.
static TypeId GetTypeId()
Register this type.
TracedValue< double > m_aggregatedDutyCycle
The aggregated duty cycle this device needs to respect across all sub-bands.
EventId m_nextRetx
The event of transmitting a packet in a consecutive moment, when the duty cycle let us transmit.
double GetAggregatedDutyCycle()
Get the aggregated duty cycle.
void Receive(Ptr< const Packet > packet) override
Receive a packet.
void SetMType(LorawanMacHeader::MType mType)
Set the message type to send when the Send method is called.
virtual void resetRetransmissionParameters()
Reset retransmission parameters contained in the structure LoraRetxParams.
virtual Time GetNextClassTransmissionDelay(Time waitingTime)
Find the minimum waiting time before the next possible transmission based on end device's Class Type.
void ParseCommands(LoraFrameHeader frameHeader)
Parse and take action on the commands contained on this FrameHeader.
void ApplyNecessaryOptions(LoraFrameHeader &frameHeader)
Add the necessary options and MAC commands to the LoraFrameHeader.
TracedCallback< uint8_t, bool, Time, Ptr< Packet > > m_requiredTxCallback
The trace source fired when the transmission procedure is finished.
virtual uint8_t GetTransmissionPower()
Get the transmission power this end device is set to use.
uint8_t GetMaxNumberOfTransmissions()
Get the max number of unacknowledged redundant transmissions of each packet.
void SetDataRateAdaptation(bool adapt)
Enable data rate adaptation in the retransmitting procedure.
void OnLinkCheckAns(uint8_t margin, uint8_t gwCnt)
Perform the actions that need to be taken when receiving a LinkCheckAns command.
EventId m_nextTx
The event of retransmitting a packet in a consecutive moment if an ACK is not received.
void OnLinkAdrReq(uint8_t dataRate, uint8_t txPower, std::list< int > enabledChannels, int repetitions)
Perform the actions that need to be taken when receiving a LinkAdrReq command.
std::list< Ptr< MacCommand > > m_macCommandList
List of the MAC commands that need to be applied to the next UL packet.
TracedValue< uint8_t > m_dataRate
The data rate this device is using to transmit.
LoraDeviceAddress m_address
The address of this device.
void Send(Ptr< Packet > packet) override
Send a packet.
uint16_t m_currentFCnt
current value of the device frame counter.
void AddMacCommand(Ptr< MacCommand > macCommand)
Add a MAC command to the list of those that will be sent out in the next packet.
void SetMaxNumberOfTransmissions(uint8_t maxNumbTx)
Set the max number of unacknowledged redundant transmissions of each packet.
TracedValue< double > m_lastKnownLinkMargin
The last known link margin.
void AddLogicalChannel(double frequency)
Add a logical channel to the helper.
Time GetNextTransmissionDelay()
Find the base minimum waiting time before the next possible transmission.
std::vector< Ptr< LogicalLoraChannel > > Shuffle(std::vector< Ptr< LogicalLoraChannel > > vector)
Randomly shuffle a Ptr<LogicalLoraChannel> vector.
LorawanMacHeader::MType GetMType()
Get the message type to send when the Send method is called.
virtual void DoSend(Ptr< Packet > packet)
Checking if we are performing the transmission of a new packet or a retransmission,...
void OnDevStatusReq()
Perform the actions that need to be taken when receiving a DevStatusReq command.
LoraDeviceAddress GetDeviceAddress()
Get the network address of this device.
void OnNewChannelReq(uint8_t chIndex, double frequency, uint8_t minDataRate, uint8_t maxDataRate)
Perform the actions that need to be taken when receiving a NewChannelReq command.
void SetDataRate(uint8_t dataRate)
Set the data rate this end device will use when transmitting.
uint8_t m_receiveWindowDurationInSymbols
The duration of a receive window in number of symbols.
uint8_t GetDataRate()
Get the data rate this end device is set to use.
void SetDeviceAddress(LoraDeviceAddress address)
Set the network address of this device.
struct LoraRetxParameters m_retxParams
Structure containing the retransmission parameters for this device.
This class represents the device address of a LoraWAN end device.
This class represents the Frame header (FHDR) used in a LoraWAN network.
This class represents the Mac header of a LoRaWAN packet.
Class representing the LoRaWAN MAC layer.
Definition lorawan-mac.h:37
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Structure representing the parameters that will be used in the retransmission procedure.
bool waitingAck
Whether the packet requires explicit acknowledgment.
uint8_t retxLeft
Number of retransmission attempts left.
Time firstAttempt
Timestamp of the first transmission of the packet.
Ptr< Packet > packet
A pointer to the packet being retransmitted.