A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
lora-phy.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 */
8
9#ifndef LORA_PHY_H
10#define LORA_PHY_H
11
12#include "lora-channel.h"
14
15#include "ns3/callback.h"
16#include "ns3/mobility-model.h"
17#include "ns3/net-device.h"
18#include "ns3/node.h"
19#include "ns3/nstime.h"
20#include "ns3/object.h"
21
22#include <list>
23
24namespace ns3
25{
26namespace lorawan
27{
28
29class LoraChannel;
30
31/**
32 * \ingroup lorawan
33 *
34 * Structure to collect all parameters that are used to compute the duration of
35 * a packet (excluding payload length).
36 */
38{
39 uint8_t sf = 7; //!< Spreading Factor
40 bool headerDisabled = false; //!< Whether to use implicit header mode
41 uint8_t codingRate = 1; //!< Code rate (obtained as 4/(codingRate+4))
42 double bandwidthHz = 125000; //!< Bandwidth in Hz
43 uint32_t nPreamble = 8; //!< Number of preamble symbols
44 bool crcEnabled = true; //!< Whether Cyclic Redundancy Check (CRC) is enabled
45 bool lowDataRateOptimizationEnabled = false; //!< Whether low data rate optimization is enabled
46};
47
48/**
49 * Allow logging of LoraTxParameters like with any other data type.
50 */
51std::ostream& operator<<(std::ostream& os, const LoraTxParameters& params);
52
53/**
54 * \ingroup lorawan
55 *
56 * Base class for PHY layers implementing the LoRa modulation scheme.
57 *
58 * This class features common callbacks and defines the interfaces that are used
59 * to send and receive packets at the PHY layer. Furthermore, it features an
60 * implementation of the GetOnAirTime function, used to compute the actual
61 * duration of a packet based on a series of parameters that are collected in
62 * LoraTxParameters objects.
63 */
64class LoraPhy : public Object
65{
66 public:
67 /**
68 * Register this type.
69 * \return The object TypeId.
70 */
71 static TypeId GetTypeId();
72
73 LoraPhy(); //!< Default constructor
74 ~LoraPhy() override; //!< Destructor
75
76 /**
77 * Type definition for a callback for when a packet is correctly received.
78 *
79 * This callback can be set by an upper layer that wishes to be informed of
80 * correct reception events.
81 */
83
84 /**
85 * Type definition for a callback for when a packet reception fails.
86 *
87 * This callback can be set by an upper layer that wishes to be informed of
88 * failed reception events.
89 */
91
92 /**
93 * Type definition for a callback to call when a packet has finished sending.
94 *
95 * This callback is used by the MAC layer, to determine when to open a receive
96 * window.
97 */
99
100 /**
101 * Start receiving a packet.
102 *
103 * This method is typically called by LoraChannel.
104 *
105 * \param packet The packet that is arriving at this PHY layer.
106 * \param rxPowerDbm The power of the arriving packet (assumed to be constant for the whole
107 * reception).
108 * \param sf The Spreading Factor of the arriving packet.
109 * \param duration The on air time of this packet.
110 * \param frequencyMHz The frequency this packet is being transmitted on.
111 */
112 virtual void StartReceive(Ptr<Packet> packet,
113 double rxPowerDbm,
114 uint8_t sf,
115 Time duration,
116 double frequencyMHz) = 0;
117
118 /**
119 * Finish reception of a packet.
120 *
121 * This method is scheduled by StartReceive, based on the packet duration. By
122 * passing a LoraInterferenceHelper Event to this method, the class will be
123 * able to identify the packet that is being received among all those that
124 * were registered as interference by StartReceive.
125 *
126 * \param packet The received packet.
127 * \param event The event that is tied to this packet in the
128 * LoraInterferenceHelper.
129 */
131
132 /**
133 * Instruct the PHY to send a packet according to some parameters.
134 *
135 * \param packet The packet to send.
136 * \param txParams The desired transmission parameters.
137 * \param frequencyMHz The frequency on which to transmit.
138 * \param txPowerDbm The power in dBm with which to transmit the packet.
139 */
140 virtual void Send(Ptr<Packet> packet,
141 LoraTxParameters txParams,
142 double frequencyMHz,
143 double txPowerDbm) = 0;
144
145 /**
146 * Whether this device is transmitting or not.
147 *
148 * \return True if the device is currently transmitting a packet, false
149 * otherwise.
150 */
151 virtual bool IsTransmitting() = 0;
152
153 /**
154 * Whether this device is listening on the specified frequency or not.
155 *
156 * \param frequency The frequency to query.
157 * \return True if the device is listening on that frequency, false
158 * otherwise.
159 */
160 virtual bool IsOnFrequency(double frequency) = 0;
161
162 /**
163 * Set the callback to call upon successful reception of a packet.
164 *
165 * This method is typically called by an upper MAC layer that wants to be
166 * notified after the successful reception of a packet.
167 *
168 * \param callback The RxOkCallback instance.
169 */
170 void SetReceiveOkCallback(RxOkCallback callback);
171
172 /**
173 * Set the callback to call upon failed reception of a packet we were
174 * previously locked on.
175 *
176 * This method is typically called by an upper MAC layer that wants to be
177 * notified after the failed reception of a packet.
178 *
179 * \param callback The RxFailedCallback instance.
180 */
182
183 /**
184 * Set the callback to call after transmission of a packet.
185 *
186 * This method is typically called by an upper MAC layer that wants to be
187 * notified after the transmission of a packet.
188 *
189 * \param callback The TxFinishedCallback instance.
190 */
192
193 /**
194 * Get the mobility model associated to this PHY.
195 *
196 * \return The MobilityModel associated to this PHY.
197 */
199
200 /**
201 * Set the mobility model associated to this PHY.
202 *
203 * \param mobility The mobility model to associate to this PHY.
204 */
205 void SetMobility(Ptr<MobilityModel> mobility);
206
207 /**
208 * Set the LoraChannel instance PHY transmits on.
209 *
210 * Typically, there is only one instance per simulation.
211 *
212 * \param channel The LoraChannel instance this PHY will transmit on.
213 */
214 void SetChannel(Ptr<LoraChannel> channel);
215
216 /**
217 * Get the channel instance associated to this PHY.
218 *
219 * \return The LoraChannel instance this PHY transmits on.
220 */
222
223 /**
224 * Get the NetDevice associated to this PHY.
225 *
226 * \return The NetDevice associated to this PHY.
227 */
229
230 /**
231 * Set the NetDevice that owns this PHY.
232 *
233 * \param device The NetDevice this PHY will reference as its owner.
234 */
235 void SetDevice(Ptr<NetDevice> device);
236
237 /**
238 * Compute the symbol time from spreading factor and bandwidth.
239 *
240 * \param txParams The parameters for transmission.
241 * \return TSym, the time required to send a LoRa modulation symbol.
242 */
243 static Time GetTSym(LoraTxParameters txParams);
244
245 /**
246 * Compute the time that a packet with certain characteristics will take to be
247 * transmitted.
248 *
249 * Besides from the ones saved in LoraTxParameters, the packet's payload
250 * (obtained through a GetSize () call to account for the presence of Headers
251 * and Trailers, too) also influences the packet transmit time.
252 *
253 * \param packet The packet that needs to be transmitted.
254 * \param txParams The set of parameters that will be used for transmission.
255 * \return The time necessary to transmit the packet.
256 */
257 static Time GetOnAirTime(Ptr<Packet> packet, LoraTxParameters txParams);
258
259 private:
260 /**
261 * Internal call when transmission of a packet finishes.
262 *
263 * Calls to this function are typically scheduled by the Send function.
264 *
265 * \param packet A pointer to the packet that has been transmitted.
266 */
267 virtual void TxFinished(Ptr<const Packet> packet) = 0;
268
269 Ptr<MobilityModel> m_mobility; //!< The mobility model associated to this PHY.
270
271 protected:
272 // Member objects
273
274 Ptr<NetDevice> m_device; //!< The net device this PHY is attached to.
275
276 Ptr<LoraChannel> m_channel; //!< The channel this PHY transmits on.
277
278 LoraInterferenceHelper m_interference; //!< The LoraInterferenceHelper associated to this PHY.
279
280 // Trace sources
281
282 /**
283 * The trace source fired when a packet is sent.
284 */
286
287 /**
288 * The trace source fired when a packet begins the reception process from the
289 * medium.
290 */
292
293 /**
294 * The trace source fired when a packet reception ends.
295 */
297
298 /**
299 * The trace source fired when a packet was correctly received.
300 */
302
303 /**
304 * The trace source fired when a packet cannot be received because its power
305 * is below the sensitivity threshold.
306 */
308
309 /**
310 * The trace source fired when a packet cannot be correctly received because
311 * of interference.
312 */
314
315 // Callbacks
316
317 /**
318 * The callback to perform upon correct reception of a packet.
319 */
321
322 /**
323 * The callback to perform upon failed reception of a packet we were locked on.
324 */
326
327 /**
328 * The callback to perform upon the end of a transmission.
329 */
331};
332
333} // namespace lorawan
334
335} // namespace ns3
336#endif /* LORA_PHY_H */
Callback template class.
Definition callback.h:422
A base class which provides memory management and object aggregation.
Definition object.h:78
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.
a unique identifier for an interface.
Definition type-id.h:48
Helper for LoraPhy that manages interference calculations.
Base class for PHY layers implementing the LoRa modulation scheme.
Definition lora-phy.h:65
Ptr< LoraChannel > GetChannel() const
Get the channel instance associated to this PHY.
Definition lora-phy.cc:91
~LoraPhy() override
Destructor.
Definition lora-phy.cc:72
TracedCallback< Ptr< const Packet > > m_phyRxEndTrace
The trace source fired when a packet reception ends.
Definition lora-phy.h:296
LoraInterferenceHelper m_interference
The LoraInterferenceHelper associated to this PHY.
Definition lora-phy.h:278
Callback< void, Ptr< const Packet > > RxFailedCallback
Type definition for a callback for when a packet reception fails.
Definition lora-phy.h:90
void SetReceiveOkCallback(RxOkCallback callback)
Set the callback to call upon successful reception of a packet.
Definition lora-phy.cc:132
virtual void Send(Ptr< Packet > packet, LoraTxParameters txParams, double frequencyMHz, double txPowerDbm)=0
Instruct the PHY to send a packet according to some parameters.
static Time GetOnAirTime(Ptr< Packet > packet, LoraTxParameters txParams)
Compute the time that a packet with certain characteristics will take to be transmitted.
Definition lora-phy.cc:156
TracedCallback< Ptr< const Packet >, uint32_t > m_interferedPacket
The trace source fired when a packet cannot be correctly received because of interference.
Definition lora-phy.h:313
RxFailedCallback m_rxFailedCallback
The callback to perform upon failed reception of a packet we were locked on.
Definition lora-phy.h:325
Callback< void, Ptr< const Packet > > TxFinishedCallback
Type definition for a callback to call when a packet has finished sending.
Definition lora-phy.h:98
static Time GetTSym(LoraTxParameters txParams)
Compute the symbol time from spreading factor and bandwidth.
Definition lora-phy.cc:150
virtual void TxFinished(Ptr< const Packet > packet)=0
Internal call when transmission of a packet finishes.
virtual bool IsOnFrequency(double frequency)=0
Whether this device is listening on the specified frequency or not.
TxFinishedCallback m_txFinishedCallback
The callback to perform upon the end of a transmission.
Definition lora-phy.h:330
virtual void EndReceive(Ptr< Packet > packet, Ptr< LoraInterferenceHelper::Event > event)=0
Finish reception of a packet.
void SetMobility(Ptr< MobilityModel > mobility)
Set the mobility model associated to this PHY.
Definition lora-phy.cc:116
void SetReceiveFailedCallback(RxFailedCallback callback)
Set the callback to call upon failed reception of a packet we were previously locked on.
Definition lora-phy.cc:138
void SetDevice(Ptr< NetDevice > device)
Set the NetDevice that owns this PHY.
Definition lora-phy.cc:83
TracedCallback< Ptr< const Packet >, uint32_t > m_successfullyReceivedPacket
The trace source fired when a packet was correctly received.
Definition lora-phy.h:301
TracedCallback< Ptr< const Packet >, uint32_t > m_startSending
The trace source fired when a packet is sent.
Definition lora-phy.h:285
virtual bool IsTransmitting()=0
Whether this device is transmitting or not.
Ptr< NetDevice > GetDevice() const
Get the NetDevice associated to this PHY.
Definition lora-phy.cc:77
static TypeId GetTypeId()
Register this type.
Definition lora-phy.cc:26
TracedCallback< Ptr< const Packet >, uint32_t > m_underSensitivity
The trace source fired when a packet cannot be received because its power is below the sensitivity th...
Definition lora-phy.h:307
Ptr< MobilityModel > m_mobility
The mobility model associated to this PHY.
Definition lora-phy.h:269
void SetChannel(Ptr< LoraChannel > channel)
Set the LoraChannel instance PHY transmits on.
Definition lora-phy.cc:124
Ptr< NetDevice > m_device
The net device this PHY is attached to.
Definition lora-phy.h:274
TracedCallback< Ptr< const Packet > > m_phyRxBeginTrace
The trace source fired when a packet begins the reception process from the medium.
Definition lora-phy.h:291
Ptr< MobilityModel > GetMobility()
Get the mobility model associated to this PHY.
Definition lora-phy.cc:99
LoraPhy()
Default constructor.
Definition lora-phy.cc:68
Callback< void, Ptr< const Packet > > RxOkCallback
Type definition for a callback for when a packet is correctly received.
Definition lora-phy.h:82
void SetTxFinishedCallback(TxFinishedCallback callback)
Set the callback to call after transmission of a packet.
Definition lora-phy.cc:144
virtual void StartReceive(Ptr< Packet > packet, double rxPowerDbm, uint8_t sf, Time duration, double frequencyMHz)=0
Start receiving a packet.
Ptr< LoraChannel > m_channel
The channel this PHY transmits on.
Definition lora-phy.h:276
RxOkCallback m_rxOkCallback
The callback to perform upon correct reception of a packet.
Definition lora-phy.h:320
std::ostream & operator<<(std::ostream &os, const EndDeviceStatus &status)
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Structure to collect all parameters that are used to compute the duration of a packet (excluding payl...
Definition lora-phy.h:38
uint8_t codingRate
Code rate (obtained as 4/(codingRate+4))
Definition lora-phy.h:41
uint32_t nPreamble
Number of preamble symbols.
Definition lora-phy.h:43
bool headerDisabled
Whether to use implicit header mode.
Definition lora-phy.h:40
double bandwidthHz
Bandwidth in Hz.
Definition lora-phy.h:42
bool lowDataRateOptimizationEnabled
Whether low data rate optimization is enabled.
Definition lora-phy.h:45
bool crcEnabled
Whether Cyclic Redundancy Check (CRC) is enabled.
Definition lora-phy.h:44
uint8_t sf
Spreading Factor.
Definition lora-phy.h:39