A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
end-device-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 * Authors: Davide Magrin <magrinda@dei.unipd.it>,
7 * Michele Luvisotto <michele.luvisotto@dei.unipd.it>
8 * Stefano Romagnolo <romagnolostefano93@gmail.com>
9 */
10
11#ifndef END_DEVICE_LORA_PHY_H
12#define END_DEVICE_LORA_PHY_H
13
14#include "lora-phy.h"
15
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#include "ns3/traced-value.h"
22
23namespace ns3
24{
25namespace lorawan
26{
27
28class LoraChannel;
29
30/**
31 * \ingroup lorawan
32 *
33 * Receive notifications about PHY events.
34 */
36{
37 public:
38 virtual ~EndDeviceLoraPhyListener(); //!< Destructor
39
40 /**
41 * We have received the first bit of a packet. We decided
42 * that we could synchronize on this packet. It does not mean
43 * we will be able to successfully receive completely the
44 * whole packet. It means that we will report a BUSY status until
45 * one of the following happens:
46 * - NotifyRxEndOk
47 * - NotifyRxEndError
48 * - NotifyTxStart
49 */
50 virtual void NotifyRxStart() = 0;
51
52 /**
53 * We are about to send the first bit of the packet.
54 * We do not send any event to notify the end of
55 * transmission. Listeners should assume that the
56 * channel implicitly reverts to the idle state
57 * unless they have received a cca busy report.
58 *
59 * \param txPowerDbm The nominal tx power in dBm.
60 */
61 virtual void NotifyTxStart(double txPowerDbm) = 0;
62
63 /**
64 * Notify listeners that we went to sleep.
65 */
66 virtual void NotifySleep() = 0;
67
68 /**
69 * Notify listeners that we woke up.
70 */
71 virtual void NotifyStandby() = 0;
72};
73
74/**
75 * \ingroup lorawan
76 *
77 * Class representing a LoRa transceiver.
78 *
79 * This class inherits some functionality by LoraPhy, like the GetOnAirTime
80 * function, and extends it to represent the behavior of a LoRa chip, like the
81 * SX1272.
82 *
83 * Additional behaviors featured in this class include a State member variable
84 * that expresses the current state of the device (SLEEP, TX, RX or STANDBY),
85 * and a frequency and Spreading Factor this device is listening to when in
86 * STANDBY mode. After transmission and reception, the device returns
87 * automatically to STANDBY mode. The decision of when to go into SLEEP mode
88 * is delegateed to an upper layer, which can modify the state of the device
89 * through the public SwitchToSleep and SwitchToStandby methods. In SLEEP
90 * mode, the device cannot lock on a packet and start reception.
91 *
92 * Peculiarities about the error model and about how errors are handled are
93 * supposed to be handled by classes extending this one, like
94 * SimpleEndDeviceLoraPhy or SpectrumEndDeviceLoraPhy. These classes need to
95 */
97{
98 public:
99 /**
100 * An enumeration of the possible states of an EndDeviceLoraPhy.
101 * It makes sense to define a state for End Devices since there's only one
102 * demodulator which can either send, receive, stay idle or go in a deep
103 * sleep state.
104 */
105 enum State
106 {
107 /**
108 * The PHY layer is sleeping.
109 * During sleep, the device is not listening for incoming messages.
110 */
112
113 /**
114 * The PHY layer is in STANDBY.
115 * When the PHY is in this state, it's listening to the channel, and
116 * it's also ready to transmit data passed to it by the MAC layer.
117 */
119
120 /**
121 * The PHY layer is sending a packet.
122 * During transmission, the device cannot receive any packet or send
123 * any additional packet.
124 */
126
127 /**
128 * The PHY layer is receiving a packet.
129 * While the device is locked on an incoming packet, transmission is
130 * not possible.
131 */
132 RX
133 };
134
135 /**
136 * Register this type.
137 * \return The object TypeId.
138 */
139 static TypeId GetTypeId();
140
141 EndDeviceLoraPhy(); //!< Default constructor
142 ~EndDeviceLoraPhy() override; //!< Destructor
143
144 // Implementation of LoraPhy's pure virtual functions
146 double rxPowerDbm,
147 uint8_t sf,
148 Time duration,
149 double frequencyMHz) override = 0;
150
151 // Implementation of LoraPhy's pure virtual functions
153
154 // Implementation of LoraPhy's pure virtual functions
155 void Send(Ptr<Packet> packet,
156 LoraTxParameters txParams,
157 double frequencyMHz,
158 double txPowerDbm) override = 0;
159
160 // Implementation of LoraPhy's pure virtual functions
161 bool IsOnFrequency(double frequencyMHz) override;
162
163 // Implementation of LoraPhy's pure virtual functions
164 bool IsTransmitting() override;
165
166 /**
167 * Set the frequency this end device will listen on.
168 *
169 * Should a packet be transmitted on a frequency different than that the
170 * EndDeviceLoraPhy is listening on, the packet will be discarded.
171 *
172 * \param frequencyMHz The frequency [MHz] to listen to.
173 */
174 void SetFrequency(double frequencyMHz);
175
176 /**
177 * Set the Spreading Factor this end device will listen for.
178 *
179 * The EndDeviceLoraPhy object will not be able to lock on transmissions that
180 * use a different spreading factor than the one it's listening for.
181 *
182 * \param sf The spreading factor to listen for.
183 */
184 void SetSpreadingFactor(uint8_t sf);
185
186 /**
187 * Get the Spreading Factor this end device is listening for.
188 *
189 * \return The Spreading Factor we are listening for.
190 */
191 uint8_t GetSpreadingFactor() const;
192
193 /**
194 * Return the state this end device is currently in.
195 *
196 * \return The state this EndDeviceLoraPhy is currently in.
197 */
199
200 /**
201 * Switch to the STANDBY state.
202 */
203 void SwitchToStandby();
204
205 /**
206 * Switch to the SLEEP state.
207 */
208 void SwitchToSleep();
209
210 /**
211 * Add the input listener to the list of objects to be notified of PHY-level
212 * events.
213 *
214 * \param listener The new listener.
215 */
217
218 /**
219 * Remove the input listener from the list of objects to be notified of
220 * PHY-level events.
221 *
222 * \param listener The listener to be unregistered.
223 */
225
226 static const double sensitivity[6]; //!< The sensitivity vector of this device to different SFs
227
228 protected:
229 /**
230 * Signals the end of a transmission by the EndDeviceLoraPhy.
231 *
232 * \param packet A pointer to the Packet transmitted.
233 */
234 void TxFinished(Ptr<const Packet> packet) override;
235
236 /**
237 * Switch to the RX state.
238 */
239 void SwitchToRx();
240
241 /**
242 * Switch to the TX state.
243 *
244 * \param txPowerDbm The transmission power [dBm].
245 */
246 void SwitchToTx(double txPowerDbm);
247
248 /**
249 * Trace source for when a packet is lost because it was using a spreading factor different from
250 * the one this EndDeviceLoraPhy was configured to listen for.
251 */
253
254 /**
255 * Trace source for when a packet is lost because it was transmitted on a
256 * frequency different from the one this EndDeviceLoraPhy was configured to
257 * listen on.
258 */
260
261 TracedValue<State> m_state; //!< The state this PHY is currently in.
262
263 // static const double sensitivity[6]; //!< The sensitivity vector of this device to different
264 // SFs
265
266 double m_frequency; //!< The frequency this device is listening on
267
268 uint8_t m_sf; //!< The Spreading Factor this device is listening for
269
270 /**
271 * typedef for a list of EndDeviceLoraPhyListener.
272 */
273 typedef std::vector<EndDeviceLoraPhyListener*> Listeners;
274 /**
275 * typedef for a list of EndDeviceLoraPhyListener iterator.
276 */
277 typedef std::vector<EndDeviceLoraPhyListener*>::iterator ListenersI;
278
279 Listeners m_listeners; //!< PHY listeners
280};
281
282} // namespace lorawan
283
284} // namespace ns3
285#endif /* END_DEVICE_LORA_PHY_H */
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 a LoRa transceiver.
bool IsOnFrequency(double frequencyMHz) override
Whether this device is listening on the specified frequency or not.
void SwitchToSleep()
Switch to the SLEEP state.
EndDeviceLoraPhy::State GetState()
Return the state this end device is currently in.
void Send(Ptr< Packet > packet, LoraTxParameters txParams, double frequencyMHz, double txPowerDbm) override=0
Instruct the PHY to send a packet according to some parameters.
void SetFrequency(double frequencyMHz)
Set the frequency this end device will listen on.
uint8_t GetSpreadingFactor() const
Get the Spreading Factor this end device is listening for.
static const double sensitivity[6]
The sensitivity vector of this device to different SFs.
std::vector< EndDeviceLoraPhyListener * >::iterator ListenersI
typedef for a list of EndDeviceLoraPhyListener iterator.
Listeners m_listeners
PHY listeners.
void RegisterListener(EndDeviceLoraPhyListener *listener)
Add the input listener to the list of objects to be notified of PHY-level events.
bool IsTransmitting() override
Whether this device is transmitting or not.
uint8_t m_sf
The Spreading Factor this device is listening for.
static TypeId GetTypeId()
Register this type.
void SwitchToRx()
Switch to the RX state.
void EndReceive(Ptr< Packet > packet, Ptr< LoraInterferenceHelper::Event > event) override=0
Finish reception of a packet.
std::vector< EndDeviceLoraPhyListener * > Listeners
typedef for a list of EndDeviceLoraPhyListener.
void SwitchToStandby()
Switch to the STANDBY state.
EndDeviceLoraPhy()
Default constructor.
~EndDeviceLoraPhy() override
Destructor.
void SetSpreadingFactor(uint8_t sf)
Set the Spreading Factor this end device will listen for.
TracedValue< State > m_state
The state this PHY is currently in.
TracedCallback< Ptr< const Packet >, uint32_t > m_wrongSf
Trace source for when a packet is lost because it was using a spreading factor different from the one...
void SwitchToTx(double txPowerDbm)
Switch to the TX state.
void UnregisterListener(EndDeviceLoraPhyListener *listener)
Remove the input listener from the list of objects to be notified of PHY-level events.
State
An enumeration of the possible states of an EndDeviceLoraPhy.
@ RX
The PHY layer is receiving a packet.
@ TX
The PHY layer is sending a packet.
@ SLEEP
The PHY layer is sleeping.
@ STANDBY
The PHY layer is in STANDBY.
void TxFinished(Ptr< const Packet > packet) override
Signals the end of a transmission by the EndDeviceLoraPhy.
double m_frequency
The frequency this device is listening on.
void StartReceive(Ptr< Packet > packet, double rxPowerDbm, uint8_t sf, Time duration, double frequencyMHz) override=0
Start receiving a packet.
TracedCallback< Ptr< const Packet >, uint32_t > m_wrongFrequency
Trace source for when a packet is lost because it was transmitted on a frequency different from the o...
Receive notifications about PHY events.
virtual void NotifyStandby()=0
Notify listeners that we woke up.
virtual void NotifyTxStart(double txPowerDbm)=0
We are about to send the first bit of the packet.
virtual void NotifyRxStart()=0
We have received the first bit of a packet.
virtual void NotifySleep()=0
Notify listeners that we went to sleep.
Base class for PHY layers implementing the LoRa modulation scheme.
Definition lora-phy.h:65
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