A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
lora-packet-tracker.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 * Author: Davide Magrin <magrinda@dei.unipd.it>
7 */
8
9#ifndef LORA_PACKET_TRACKER_H
10#define LORA_PACKET_TRACKER_H
11
12#include "ns3/nstime.h"
13#include "ns3/packet.h"
14
15#include <map>
16#include <string>
17
18namespace ns3
19{
20namespace lorawan
21{
22
32
33/**
34 * \ingroup lorawan
35 *
36 * Stores PHY-layer uplink packet metrics of sender/receivers.
37 */
39{
40 Ptr<const Packet> packet; //!< Packet being tracked
41 uint32_t senderId; //!< Node id of the packet sender
42 Time sendTime; //!< Timestamp of pkt radio tx start
43 std::map<int, enum PhyPacketOutcome> outcomes; //!< Reception outcome of this pkt at the end of
44 //!< the tx, mapped by gateway's node id
45};
46
47/**
48 * \ingroup lorawan
49 *
50 * Stores MAC-layer packet metrics of sender/receivers.
51 *
52 * \remark Can be used for both uplink and downlink packets.
53 */
55{
56 Ptr<const Packet> packet; //!< Packet being tracked
57 uint32_t senderId; //!< Node id of the packet sender
58 Time sendTime; //!< Timestamp of the pkt leaving MAC layer to go down the stack of sender
59 Time receivedTime; //!< Time of first reception (placeholder field)
60 //!< \todo Field set to max and not used
61 std::map<int, Time> receptionTimes; //!< Timestamp of the pkt leaving MAC layer to go up the
62 //!< stack, mapped by receiver's node id
63};
64
65/**
66 * \ingroup lorawan
67 *
68 * Stores (optionally enabled) MAC layer packet retransmission process metrics of end devices.
69 */
71{
72 Time firstAttempt; //!< Timestamp of the first transmission attempt
73 Time finishTime; //!< Timestamp of the conclusion of the retransmission process
74 uint8_t reTxAttempts; //!< Number of transmissions attempted during the process
75 bool successful; //!< Whether the retransmission procedure was successful
76};
77
78typedef std::map<Ptr<const Packet>, MacPacketStatus> MacPacketData;
79typedef std::map<Ptr<const Packet>, PacketStatus> PhyPacketData;
80typedef std::map<Ptr<const Packet>, RetransmissionStatus> RetransmissionData;
81
82/**
83 * \ingroup lorawan
84 *
85 * Tracks and stores packets sent in the simulation and provides aggregation functionality
86 */
88{
89 public:
90 LoraPacketTracker(); //!< Default constructor
91 ~LoraPacketTracker(); //!< Destructor
92
93 ///////////////////////////
94 // PHY layer trace sinks //
95 ///////////////////////////
96
97 // Packet transmission by end devices
98
99 /**
100 * Trace a packet TX start by the PHY layer of an end device.
101 *
102 * \param packet The packet being transmitted.
103 * \param systemId Id of end device transmitting the packet.
104 */
105 void TransmissionCallback(Ptr<const Packet> packet, uint32_t systemId);
106
107 // Packet reception outcome at gateways
108
109 /**
110 * Trace a correct packet RX by the PHY layer of a gateway.
111 *
112 * \param packet The packet being received.
113 * \param systemId Id of the gateway receiving the packet.
114 */
116 /**
117 * Trace a gateway packet loss caused by interference.
118 *
119 * \param packet The packet being lost.
120 * \param systemId Id of the gateway losing the packet.
121 */
122 void InterferenceCallback(Ptr<const Packet> packet, uint32_t systemId);
123 /**
124 * Trace a gateway packet loss caused by lack of free reception paths.
125 *
126 * \param packet The packet being lost.
127 * \param systemId Id of the gateway losing the packet.
128 */
130 /**
131 * Trace a gateway packet loss caused by signal strength under sensitivity.
132 *
133 * \param packet The packet being lost.
134 * \param systemId Id of the gateway losing the packet.
135 */
137 /**
138 * Trace a gateway packet loss caused by concurrent downlink transmission.
139 *
140 * \param packet The packet being lost.
141 * \param systemId Id of the gateway losing the packet.
142 */
143 void LostBecauseTxCallback(Ptr<const Packet> packet, uint32_t systemId);
144
145 ///////////////////////////
146 // MAC layer trace sinks //
147 ///////////////////////////
148
149 // Packet send
150
151 /**
152 * Trace a packet leaving a node's MAC layer to go down the stack and be sent by the PHY layer.
153 *
154 * \remark This trace sink is normally connected to both end devices and gateways.
155 *
156 * \param packet The packet being sent.
157 */
159 /**
160 * Trace the exit status of a MAC layer packet retransmission process of an end device.
161 *
162 * \param reqTx Number of transmissions attempted during the process.
163 * \param success Whether the retransmission procedure was successful.
164 * \param firstAttempt Timestamp of the initial transmission attempt.
165 * \param packet The packet being retransmitted.
166 */
167 void RequiredTransmissionsCallback(uint8_t reqTx,
168 bool success,
169 Time firstAttempt,
170 Ptr<Packet> packet);
171
172 // Packet reception by gateways
173
174 /**
175 * Trace a packet leaving a gateway's MAC layer to go up the stack and be delivered to the
176 * node's application.
177 *
178 * \param packet The packet being received.
179 */
181
182 ///////////////////////////////
183 // Packet counting functions //
184 ///////////////////////////////
185
186 /**
187 * Check whether a packet is uplink.
188 *
189 * \param packet The packet to be checked.
190 * \return True if the packet is uplink, false otherwise.
191 */
192 bool IsUplink(Ptr<const Packet> packet);
193
194 // void CountRetransmissions (Time transient, Time simulationTime, MacPacketData
195 // macPacketTracker, RetransmissionData reTransmissionTracker,
196 // PhyPacketData packetTracker);
197
198 /**
199 * Count packets in a time interval to evaluate the performance at PHY level of a specific
200 * gateway. It counts the total number of uplink packets sent over the radio medium, and - from
201 * the perspective of the specified gateway - the number of such packets correctly received,
202 * lost to interference, lost to unavailability of the gateway's reception paths, lost for being
203 * under the RSSI sensitivity threshold, and lost due to concurrent downlink transmission of the
204 * gateway.
205 *
206 * \param startTime Timestamp of the start of the measurement.
207 * \param stopTime Timestamp of the end of the measurement.
208 * \param systemId Node id of the gateway.
209 * \return A vector comprised of the following fields: [totPacketsSent, receivedPackets,
210 * interferedPackets, noMoreGwPackets, underSensitivityPackets, lostBecauseTxPackets].
211 */
212 std::vector<int> CountPhyPacketsPerGw(Time startTime, Time stopTime, int systemId);
213 /**
214 * \copydoc ns3::lorawan::LoraPacketTracker::CountPhyPacketsPerGw
215 * \return Values in the output vector are formatted into a space-separated string.
216 */
217 std::string PrintPhyPacketsPerGw(Time startTime, Time stopTime, int systemId);
218
219 /**
220 * Count packets in a time interval to evaluate the performance at MAC level of a specific
221 * gateway.
222 *
223 * \param startTime Timestamp of the start of the measurement.
224 * \param stopTime Timestamp of the end of the measurement.
225 * \param systemId Node id of the gateway.
226 * \return String of output values.
227 *
228 * \todo Not implemented, this is a placeholder for future implementation.
229 */
230 std::string CountMacPacketsPerGw(Time startTime, Time stopTime, int systemId);
231 /** \copydoc ns3::lorawan::LoraPacketTracker::CountMacPacketsPerGw */
232 std::string PrintMacPacketsPerGw(Time startTime, Time stopTime, int systemId);
233
234 /**
235 * In a time interval, count the number of retransmissions that were needed to correctly deliver
236 * a packet and receive the corresponding acknowledgment.
237 *
238 * \param startTime Timestamp of the start of the measurement.
239 * \param stopTime Timestamp of the end of the measurement.
240 * \return String of output values.
241 *
242 * \todo Not implemented, this is a placeholder for future implementation.
243 */
244 std::string CountRetransmissions(Time startTime, Time stopTime);
245
246 /**
247 * In a time interval, count packets to evaluate the global performance at MAC level of the
248 * whole network. In this case, a MAC layer packet is labeled as successful if it was successful
249 * at at least one of the available gateways.
250 *
251 * \param startTime Timestamp of the start of the measurement.
252 * \param stopTime Timestamp of the end of the measurement.
253 * \return Space-separated string containing two metrics: the number of sent packets and the
254 * number of packets that were received by at least one gateway.
255 */
256 std::string CountMacPacketsGlobally(Time startTime, Time stopTime);
257
258 /**
259 * In a time interval, count packets to evaluate the performance at MAC level of the whole
260 * network. In this case, a MAC layer packet is labeled as successful if it was successful at at
261 * least one of the available gateways, and if the corresponding acknowledgment was correctly
262 * delivered at the device.
263 *
264 * \param startTime Timestamp of the start of the measurement.
265 * \param stopTime Timestamp of the end of the measurement.
266 * \return Space-separated string containing two metrics: the number of sent packets and the
267 * number of packets that generated a successful acknowledgment.
268 */
269 std::string CountMacPacketsGloballyCpsr(Time startTime, Time stopTime);
270
271 private:
272 PhyPacketData m_packetTracker; //!< Packet map of PHY layer metrics
273 MacPacketData m_macPacketTracker; //!< Packet map of MAC layer metrics
274 RetransmissionData m_reTransmissionTracker; //!< Packet map of retransmission process metrics
275};
276} // namespace lorawan
277} // namespace ns3
278#endif
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Tracks and stores packets sent in the simulation and provides aggregation functionality.
void NoMoreReceiversCallback(Ptr< const Packet > packet, uint32_t systemId)
Trace a gateway packet loss caused by lack of free reception paths.
std::string CountRetransmissions(Time startTime, Time stopTime)
In a time interval, count the number of retransmissions that were needed to correctly deliver a packe...
void MacTransmissionCallback(Ptr< const Packet > packet)
Trace a packet leaving a node's MAC layer to go down the stack and be sent by the PHY layer.
PhyPacketData m_packetTracker
Packet map of PHY layer metrics.
void RequiredTransmissionsCallback(uint8_t reqTx, bool success, Time firstAttempt, Ptr< Packet > packet)
Trace the exit status of a MAC layer packet retransmission process of an end device.
void UnderSensitivityCallback(Ptr< const Packet > packet, uint32_t systemId)
Trace a gateway packet loss caused by signal strength under sensitivity.
void LostBecauseTxCallback(Ptr< const Packet > packet, uint32_t systemId)
Trace a gateway packet loss caused by concurrent downlink transmission.
std::string CountMacPacketsPerGw(Time startTime, Time stopTime, int systemId)
Count packets in a time interval to evaluate the performance at MAC level of a specific gateway.
std::vector< int > CountPhyPacketsPerGw(Time startTime, Time stopTime, int systemId)
Count packets in a time interval to evaluate the performance at PHY level of a specific gateway.
std::string PrintPhyPacketsPerGw(Time startTime, Time stopTime, int systemId)
Count packets in a time interval to evaluate the performance at PHY level of a specific gateway.
void MacGwReceptionCallback(Ptr< const Packet > packet)
Trace a packet leaving a gateway's MAC layer to go up the stack and be delivered to the node's applic...
LoraPacketTracker()
Default constructor.
void PacketReceptionCallback(Ptr< const Packet > packet, uint32_t systemId)
Trace a correct packet RX by the PHY layer of a gateway.
MacPacketData m_macPacketTracker
Packet map of MAC layer metrics.
std::string CountMacPacketsGlobally(Time startTime, Time stopTime)
In a time interval, count packets to evaluate the global performance at MAC level of the whole networ...
bool IsUplink(Ptr< const Packet > packet)
Check whether a packet is uplink.
void InterferenceCallback(Ptr< const Packet > packet, uint32_t systemId)
Trace a gateway packet loss caused by interference.
void TransmissionCallback(Ptr< const Packet > packet, uint32_t systemId)
Trace a packet TX start by the PHY layer of an end device.
RetransmissionData m_reTransmissionTracker
Packet map of retransmission process metrics.
std::string PrintMacPacketsPerGw(Time startTime, Time stopTime, int systemId)
Count packets in a time interval to evaluate the performance at MAC level of a specific gateway.
std::string CountMacPacketsGloballyCpsr(Time startTime, Time stopTime)
In a time interval, count packets to evaluate the performance at MAC level of the whole network.
Time stopTime
std::map< Ptr< const Packet >, MacPacketStatus > MacPacketData
std::map< Ptr< const Packet >, PacketStatus > PhyPacketData
std::map< Ptr< const Packet >, RetransmissionStatus > RetransmissionData
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Stores MAC-layer packet metrics of sender/receivers.
Ptr< const Packet > packet
Packet being tracked.
Time receivedTime
Time of first reception (placeholder field)
Time sendTime
Timestamp of the pkt leaving MAC layer to go down the stack of sender.
uint32_t senderId
Node id of the packet sender.
std::map< int, Time > receptionTimes
Timestamp of the pkt leaving MAC layer to go up the stack, mapped by receiver's node id.
Stores PHY-layer uplink packet metrics of sender/receivers.
uint32_t senderId
Node id of the packet sender.
Time sendTime
Timestamp of pkt radio tx start.
Ptr< const Packet > packet
Packet being tracked.
std::map< int, enum PhyPacketOutcome > outcomes
Reception outcome of this pkt at the end of the tx, mapped by gateway's node id.
Stores (optionally enabled) MAC layer packet retransmission process metrics of end devices.
Time finishTime
Timestamp of the conclusion of the retransmission process.
Time firstAttempt
Timestamp of the first transmission attempt.
bool successful
Whether the retransmission procedure was successful.
uint8_t reTxAttempts
Number of transmissions attempted during the process.