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 class 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 */
133 // NOTE: When extending/updating, please update operator<< accordingly.
134 };
135
136 /**
137 * Register this type.
138 * @return The object TypeId.
139 */
140 static TypeId GetTypeId();
141
142 EndDeviceLoraPhy(); //!< Default constructor
143 ~EndDeviceLoraPhy() override; //!< Destructor
144
145 // Implementation of LoraPhy's pure virtual functions
147 double rxPowerDbm,
148 uint8_t sf,
149 Time duration,
150 uint32_t frequencyHz) override = 0;
151
152 // Implementation of LoraPhy's pure virtual functions
154
155 // Implementation of LoraPhy's pure virtual functions
156 void Send(Ptr<Packet> packet,
157 LoraTxParameters txParams,
158 uint32_t frequencyHz,
159 double txPowerDbm) override = 0;
160
161 // Implementation of LoraPhy's pure virtual functions
162 bool IsOnFrequency(uint32_t frequencyHz) override;
163
164 // Implementation of LoraPhy's pure virtual functions
165 bool IsTransmitting() override;
166
167 /**
168 * Set the frequency this end device will listen on.
169 *
170 * Should a packet be transmitted on a frequency different than that the
171 * EndDeviceLoraPhy is listening on, the packet will be discarded.
172 *
173 * @param frequencyHz The frequency [Hz] to listen to.
174 */
175 void SetFrequency(uint32_t frequencyHz);
176
177 /**
178 * Set the Spreading Factor this end device will listen for.
179 *
180 * The EndDeviceLoraPhy object will not be able to lock on transmissions that
181 * use a different spreading factor than the one it's listening for.
182 *
183 * @param sf The spreading factor to listen for.
184 */
185 void SetSpreadingFactor(uint8_t sf);
186
187 /**
188 * Get the Spreading Factor this end device is listening for.
189 *
190 * @return The Spreading Factor we are listening for.
191 */
192 uint8_t GetSpreadingFactor() const;
193
194 /**
195 * Return the state this end device is currently in.
196 *
197 * @return The state this EndDeviceLoraPhy is currently in.
198 */
200
201 /**
202 * Switch to the STANDBY state.
203 */
204 void SwitchToStandby();
205
206 /**
207 * Switch to the SLEEP state.
208 */
209 void SwitchToSleep();
210
211 /**
212 * Add the input listener to the list of objects to be notified of PHY-level
213 * events.
214 *
215 * @param listener The new listener.
216 */
218
219 /**
220 * Remove the input listener from the list of objects to be notified of
221 * PHY-level events.
222 *
223 * @param listener The listener to be unregistered.
224 */
226
227 static const double sensitivity[6]; //!< The sensitivity vector of this device to different SFs
228
229 protected:
230 /**
231 * Signals the end of a transmission by the EndDeviceLoraPhy.
232 *
233 * @param packet A pointer to the Packet transmitted.
234 */
235 void TxFinished(Ptr<const Packet> packet) override;
236
237 /**
238 * Switch to the RX state.
239 */
240 void SwitchToRx();
241
242 /**
243 * Switch to the TX state.
244 *
245 * @param txPowerDbm The transmission power [dBm].
246 */
247 void SwitchToTx(double txPowerDbm);
248
249 /**
250 * Trace source for when a packet is lost because it was using a spreading factor different from
251 * the one this EndDeviceLoraPhy was configured to listen for.
252 */
254
255 /**
256 * Trace source for when a packet is lost because it was transmitted on a
257 * frequency different from the one this EndDeviceLoraPhy was configured to
258 * listen on.
259 */
261
262 TracedValue<State> m_state; //!< The state this PHY is currently in.
263
264 // static const double sensitivity[6]; //!< The sensitivity vector of this device to different
265 // SFs
266
267 uint32_t m_frequencyHz; //!< The frequency [Hz] this device is listening on
268
269 uint8_t m_sf; //!< The Spreading Factor this device is listening for
270
271 /**
272 * typedef for a list of EndDeviceLoraPhyListener.
273 */
274 typedef std::vector<EndDeviceLoraPhyListener*> Listeners;
275 /**
276 * typedef for a list of EndDeviceLoraPhyListener iterator.
277 */
278 typedef std::vector<EndDeviceLoraPhyListener*>::iterator ListenersI;
279
280 Listeners m_listeners; //!< PHY listeners
281};
282
283/**
284 * Overloaded operator to print the value of a EndDeviceLoraPhy::State.
285 *
286 * @param os The output stream
287 * @param state The enum value of the PHY state
288 * @return The output stream with text value of the PHY state
289 */
290std::ostream& operator<<(std::ostream& os, const EndDeviceLoraPhy::State& state);
291
292} // namespace lorawan
293} // namespace ns3
294
295#endif /* END_DEVICE_LORA_PHY_H */
Smart pointer class similar to boost::intrusive_ptr.
Definition ptr.h:66
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:49
void SwitchToSleep()
Switch to the SLEEP state.
EndDeviceLoraPhy::State GetState()
Return the state this end device is currently in.
void StartReceive(Ptr< Packet > packet, double rxPowerDbm, uint8_t sf, Time duration, uint32_t frequencyHz) override=0
Start receiving a packet.
void Send(Ptr< Packet > packet, LoraTxParameters txParams, uint32_t frequencyHz, double txPowerDbm) override=0
Instruct the PHY to send a packet according to some parameters.
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.
bool IsOnFrequency(uint32_t frequencyHz) override
Whether this device is listening on the specified frequency or not.
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 SetFrequency(uint32_t frequencyHz)
Set the frequency this end device will listen on.
uint32_t m_frequencyHz
The frequency [Hz] this device is listening on.
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.
@ TX
The PHY layer is sending a packet.
@ STANDBY
The PHY layer is in STANDBY.
@ RX
The PHY layer is receiving a packet.
void TxFinished(Ptr< const Packet > packet) override
Signals the end of a transmission by the EndDeviceLoraPhy.
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.
The class that delivers packets among PHY layers.
LoraPhy()
Default constructor.
Definition lora-phy.cc:68
std::ostream & operator<<(std::ostream &os, const EndDeviceLoraPhy::State &state)
Overloaded operator to print the value of a EndDeviceLoraPhy::State.
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