A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
end-device-status.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018 University of Padova
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Martina Capuzzo <capuzzom@dei.unipd.it>
7 * Davide Magrin <magrinda@dei.unipd.it>
8 */
9
10#ifndef END_DEVICE_STATUS_H
11#define END_DEVICE_STATUS_H
12
14#include "lora-device-address.h"
15#include "lora-frame-header.h"
16#include "lora-net-device.h"
17#include "lorawan-mac-header.h"
18
19#include "ns3/object.h"
20#include "ns3/pointer.h"
21
22#include <iostream>
23
24namespace ns3
25{
26namespace lorawan
27{
28
29/**
30 * \ingroup lorawan
31 *
32 * This class represents the network server's knowledge about an end device in
33 * the LoRaWAN network it is administering.
34 *
35 * The network server's NetworkStatus component contains a list of instances of
36 * this class, one for each device in the network. Each instance contains all
37 * the parameters and information of the end device and the packets received
38 * from it. Furthermore, this class holds the reply packet that the network
39 * server will send to this device at the first available receive window. Upon
40 * new packet arrivals at the network server, the OnReceivedPacket method is
41 * called to update the information regarding the last received packet and its
42 * parameters.
43 *
44 * Diagram of the end-device-status data structure. One instance of this class
45 * for each end device, that will be identified by its address.
46 *
47 * Public Access:
48 *
49 * (End device address) --- Current device parameters:
50 * - First Receive Window Spreading Factor (SF) and Data Rate (DR)
51 * - First Receive Window frequency
52 * - Second Window Spreading Factor (SF) and Data Rate (DR)
53 * - Second Receive Window frequency
54 * --- Reply
55 * - Need for reply (true/false)
56 * - Updated reply
57 * --- Received Packets
58 * - Received packets list (see below).
59 *
60 *
61 * Private Access:
62 *
63 * (Received packets list) - List of gateways that received the packet (see below)
64 * - Spreading Factor (SF) of the received packet
65 * - Frequency of the received packet
66 * - Bandwidth of the received packet
67 *
68 * (Gateway list) - Time at which the packet was received
69 * - Reception power
70 */
71class EndDeviceStatus : public Object
72{
73 public:
74 /********************/
75 /* Reply management */
76 /********************/
77
78 /**
79 * Structure representing the reply that the network server will send this
80 * device at the first opportunity.
81 */
82 struct Reply
83 {
84 LorawanMacHeader macHeader; //!< The MAC Header to attach to the reply packet.
85 LoraFrameHeader frameHeader; //!< The Frame Header to attach to the reply packet.
86 Ptr<Packet> payload; //!< The data packet that will be sent as a reply.
87 bool needsReply = false; //!< Whether or not this device needs a reply
88 };
89
90 /**
91 * Whether the end device needs a reply.
92 *
93 * This is determined by looking at headers and payload of the Reply
94 * structure: if they are empty, no reply should be needed.
95 *
96 * \return A boolean value signaling if the end device needs a reply.
97 */
98 bool NeedsReply() const;
99
100 /**
101 * Get the reply packet.
102 *
103 * \return A pointer to the packet reply (data + headers).
104 */
106
107 /**
108 * Get the reply packet mac header.
109 *
110 * \return The packet reply mac header.
111 */
113
114 /**
115 * Get the reply packet frame header.
116 *
117 * \return The packet reply frame header.
118 */
120
121 /**
122 * Get the data of the reply packet.
123 *
124 * \return A pointer to the packet reply.
125 */
127
128 /***********************************/
129 /* Received packet list management */
130 /***********************************/
131
132 /**
133 * Structure saving information regarding the packet reception in
134 * each gateway.
135 */
137 {
138 Address gwAddress; //!< Address of the gateway that received the packet.
139 Time receivedTime; //!< Time at which the packet was received by this gateway.
140 double rxPower; //!< Reception power of the packet at this gateway.
141 };
142
143 /**
144 * typedef of a list of gateways with relative reception information.
145 */
146 typedef std::map<Address, PacketInfoPerGw> GatewayList;
147
148 /**
149 * Structure saving information regarding all packet receptions.
150 */
152 {
153 // Members
154 Ptr<const Packet> packet = nullptr; //!< The received packet
155 GatewayList gwList; //!< List of gateways that received this packet
156 uint8_t sf; //!< Spreading factor used to send this packet
157 double frequency; //!< Carrier frequency [MHz] used to send this packet
158 };
159
160 /**
161 * typedef of a list of packets paired to their reception info.
162 */
163 typedef std::list<std::pair<Ptr<const Packet>, ReceivedPacketInfo>> ReceivedPacketList;
164
165 /*******************************************/
166 /* Proper EndDeviceStatus class definition */
167 /*******************************************/
168
169 /**
170 * Register this type.
171 * \return The object TypeId.
172 */
173 static TypeId GetTypeId();
174
175 EndDeviceStatus(); //!< Default constructor
176 ~EndDeviceStatus() override; //!< Destructor
177
178 /**
179 * Constructor with initialization parameters.
180 *
181 * \param endDeviceAddress Address of the end device.
182 * \param endDeviceMac Pointer to the MAC layer of the end device.
183 */
184 EndDeviceStatus(LoraDeviceAddress endDeviceAddress,
185 Ptr<ClassAEndDeviceLorawanMac> endDeviceMac);
186
187 /**
188 * Get the spreading factor this device is using in the first receive window.
189 *
190 * \return An unsigned 8-bit integer containing the spreading factor.
191 */
193
194 /**
195 * Get the first window frequency of this device.
196 *
197 * \return The frequency [MHz].
198 */
199 double GetFirstReceiveWindowFrequency() const;
200
201 /**
202 * Get the spreading factor this device is using in the second
203 * receive window.
204 *
205 * \return An unsigned 8-bit integer containing the spreading factor.
206 */
208
209 /**
210 * Return the second window frequency of this device.
211 *
212 * \return The frequency [MHz].
213 */
214 double GetSecondReceiveWindowFrequency() const;
215
216 /**
217 * Get the received packet list.
218 *
219 * \return The received packet list.
220 */
222
223 /**
224 * Set the spreading factor this device is using in the first receive window.
225 *
226 * \param sf The spreading factor.
227 */
229
230 /**
231 * Set the first window frequency of this device.
232 *
233 * \param frequency The frequency [MHz].
234 */
235 void SetFirstReceiveWindowFrequency(double frequency);
236
237 /**
238 * Set the spreading factor this device is using in the second receive window.
239 *
240 * \param sf The spreading factor.
241 */
243
244 /**
245 * Set the second window frequency of this device.
246 *
247 * \param frequency The frequency [MHz].
248 */
249 void SetSecondReceiveWindowFrequency(double frequency);
250
251 /**
252 * Set the reply packet mac header.
253 *
254 * \param macHeader The mac header (MHDR).
255 */
256 void SetReplyMacHeader(LorawanMacHeader macHeader);
257
258 /**
259 * Set the reply packet frame header.
260 *
261 * \param frameHeader The frame header (FHDR + FPort).
262 */
263 void SetReplyFrameHeader(LoraFrameHeader frameHeader);
264
265 /**
266 * Set the packet reply payload.
267 *
268 * \param replyPayload Packet containing the FRMPayload.
269 */
270 void SetReplyPayload(Ptr<Packet> replyPayload);
271
272 /**
273 * Get the MAC layer of the end device.
274 *
275 * \return A pointer to the MAC layer.
276 */
278
279 //////////////////////
280 // Other methods //
281 //////////////////////
282
283 /**
284 * Insert a received packet in the packet list.
285 *
286 * \param receivedPacket The packet received.
287 * \param gwAddress The address of the receiver gateway.
288 */
289 void InsertReceivedPacket(Ptr<const Packet> receivedPacket, const Address& gwAddress);
290
291 /**
292 * Return the last packet that was received from this device.
293 *
294 * \return The last received packet.
295 */
297
298 /**
299 * Return the information about the last packet that was received from the
300 * device.
301 *
302 * \return The information about the last received packet.
303 */
305
306 /**
307 * Reset the next reply state.
308 */
309 void InitializeReply();
310
311 /**
312 * Add MAC command to the frame header of next reply.
313 *
314 * \param macCommand The MAC command.
315 */
316 void AddMACCommand(Ptr<MacCommand> macCommand);
317
318 /**
319 * Check if there is already a running reception window event scheduled for this end device.
320 *
321 * \return True if a reception window event is already scheduled, false otherwise.
322 */
324
325 /**
326 * Store next scheduled reception window event.
327 *
328 * \param event The event.
329 */
331
332 /**
333 * Cancel next scheduled reception window event.
334 */
336
337 /**
338 * Get the gateways which received the last packet from the end device. Gateways are mapped
339 * to their measured reception power of the last packet, in ascending order.
340 *
341 * \return The ordered map of reception power values and gateways.
342 */
343 std::map<double, Address> GetPowerGatewayMap();
344
345 struct Reply m_reply; //!< Next reply intended for this device
346 LoraDeviceAddress m_endDeviceAddress; //!< The address of this device
347
348 /**
349 * Stream insertion operator.
350 *
351 * \param os The stream.
352 * \param status The status.
353 * \return A reference to the stream.
354 */
355 friend std::ostream& operator<<(std::ostream& os, const EndDeviceStatus& status);
356
357 private:
358 // Receive window data
359 uint8_t m_firstReceiveWindowSpreadingFactor = 0; //!< Spreading Factor (SF) for RX1 window
360 double m_firstReceiveWindowFrequency = 0; //!< Frequency [MHz] for RX1 window
361 uint8_t m_secondReceiveWindowSpreadingFactor = 0; //!< Spreading Factor (SF) for RX2 window.
362 double m_secondReceiveWindowFrequency = 869.525; //!< Frequency [MHz] for RX2 window
363 EventId m_receiveWindowEvent; //!< Event storing the next scheduled downlink transmission
364
365 ReceivedPacketList m_receivedPacketList; //!< List of received packets
366
367 /// \note Using this attribute is 'cheating', since we are assuming perfect
368 /// synchronization between the info at the device and at the network server
369 Ptr<ClassAEndDeviceLorawanMac> m_mac; //!< Pointer to the MAC layer of this device
370};
371} // namespace lorawan
372
373} // namespace ns3
374#endif /* DEVICE_STATUS_H */
a polymophic address class
Definition address.h:90
An identifier for simulation events.
Definition event-id.h:45
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
a unique identifier for an interface.
Definition type-id.h:48
This class represents the network server's knowledge about an end device in the LoRaWAN network it is...
EndDeviceStatus::ReceivedPacketInfo GetLastReceivedPacketInfo()
Return the information about the last packet that was received from the device.
void SetFirstReceiveWindowFrequency(double frequency)
Set the first window frequency of this device.
void SetSecondReceiveWindowFrequency(double frequency)
Set the second window frequency of this device.
uint8_t m_secondReceiveWindowSpreadingFactor
Spreading Factor (SF) for RX2 window.
bool HasReceiveWindowOpportunityScheduled()
Check if there is already a running reception window event scheduled for this end device.
void SetReplyMacHeader(LorawanMacHeader macHeader)
Set the reply packet mac header.
void SetReplyFrameHeader(LoraFrameHeader frameHeader)
Set the reply packet frame header.
double m_firstReceiveWindowFrequency
Frequency [MHz] for RX1 window.
static TypeId GetTypeId()
Register this type.
Ptr< Packet > GetReplyPayload()
Get the data of the reply packet.
std::list< std::pair< Ptr< const Packet >, ReceivedPacketInfo > > ReceivedPacketList
typedef of a list of packets paired to their reception info.
void SetSecondReceiveWindowSpreadingFactor(uint8_t sf)
Set the spreading factor this device is using in the second receive window.
LorawanMacHeader GetReplyMacHeader() const
Get the reply packet mac header.
uint8_t m_firstReceiveWindowSpreadingFactor
Spreading Factor (SF) for RX1 window.
void InsertReceivedPacket(Ptr< const Packet > receivedPacket, const Address &gwAddress)
Insert a received packet in the packet list.
EventId m_receiveWindowEvent
Event storing the next scheduled downlink transmission.
struct Reply m_reply
Next reply intended for this device.
LoraDeviceAddress m_endDeviceAddress
The address of this device.
bool NeedsReply() const
Whether the end device needs a reply.
LoraFrameHeader GetReplyFrameHeader() const
Get the reply packet frame header.
double m_secondReceiveWindowFrequency
Frequency [MHz] for RX2 window.
double GetSecondReceiveWindowFrequency() const
Return the second window frequency of this device.
std::map< Address, PacketInfoPerGw > GatewayList
typedef of a list of gateways with relative reception information.
ReceivedPacketList m_receivedPacketList
List of received packets.
void RemoveReceiveWindowOpportunity()
Cancel next scheduled reception window event.
void SetReceiveWindowOpportunity(EventId event)
Store next scheduled reception window event.
ReceivedPacketList GetReceivedPacketList() const
Get the received packet list.
double GetFirstReceiveWindowFrequency() const
Get the first window frequency of this device.
Ptr< const Packet > GetLastPacketReceivedFromDevice()
Return the last packet that was received from this device.
void SetReplyPayload(Ptr< Packet > replyPayload)
Set the packet reply payload.
friend std::ostream & operator<<(std::ostream &os, const EndDeviceStatus &status)
Stream insertion operator.
void AddMACCommand(Ptr< MacCommand > macCommand)
Add MAC command to the frame header of next reply.
uint8_t GetFirstReceiveWindowSpreadingFactor() const
Get the spreading factor this device is using in the first receive window.
void SetFirstReceiveWindowSpreadingFactor(uint8_t sf)
Set the spreading factor this device is using in the first receive window.
Ptr< ClassAEndDeviceLorawanMac > m_mac
Pointer to the MAC layer of this device.
void InitializeReply()
Reset the next reply state.
std::map< double, Address > GetPowerGatewayMap()
Get the gateways which received the last packet from the end device.
uint8_t GetSecondReceiveWindowSpreadingFactor() const
Get the spreading factor this device is using in the second receive window.
Ptr< Packet > GetCompleteReplyPacket()
Get the reply packet.
~EndDeviceStatus() override
Destructor.
EndDeviceStatus()
Default constructor.
Ptr< ClassAEndDeviceLorawanMac > GetMac()
Get the MAC layer of the end 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.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Structure saving information regarding the packet reception in each gateway.
Time receivedTime
Time at which the packet was received by this gateway.
Address gwAddress
Address of the gateway that received the packet.
double rxPower
Reception power of the packet at this gateway.
Structure saving information regarding all packet receptions.
GatewayList gwList
List of gateways that received this packet.
double frequency
Carrier frequency [MHz] used to send this packet.
Ptr< const Packet > packet
The received packet.
uint8_t sf
Spreading factor used to send this packet.
Structure representing the reply that the network server will send this device at the first opportuni...
LorawanMacHeader macHeader
The MAC Header to attach to the reply packet.
bool needsReply
Whether or not this device needs a reply.
Ptr< Packet > payload
The data packet that will be sent as a reply.
LoraFrameHeader frameHeader
The Frame Header to attach to the reply packet.