A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-phy-rx-trace-helper.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2023 University of Washington
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 */
6
7#ifndef WIFI_PHY_RX_TRACE_HELPER_H
8#define WIFI_PHY_RX_TRACE_HELPER_H
9
10#include "ns3/nstime.h"
11#include "ns3/object.h"
12#include "ns3/phy-entity.h"
13#include "ns3/ptr.h"
14#include "ns3/wifi-phy-common.h"
15#include "ns3/wifi-phy-state.h"
16#include "ns3/wifi-ppdu.h"
17
18#include <functional>
19#include <map>
20#include <optional>
21#include <set>
22#include <string>
23#include <vector>
24
25// Forward declare some friend test classes that access private methods
29
30namespace ns3
31{
32
33class Mac48Address;
34class NetDeviceContainer;
35class Node;
36class NodeContainer;
37struct SpectrumSignalParameters;
38class WifiPhyRxTraceSink;
39class WifiTxVector;
40
41/**
42 * @struct WifiPhyTraceStatistics
43 * @brief Keeps track of PHY layer trace statistics.
44 *
45 * This structure stores various statistics related to the Physical Layer (PHY) of the Wi-Fi
46 * communication, including the number of successful and failed PPDUs containing unicast data,
47 * and unicast data MPDU receptions.
48 */
50{
52 0}; ///< Number of PPDUs that overlapped in time with at least one other PPDU.
54 0}; ///< Number of PPDUs that did not overlap in time with any other PPDU.
55 uint64_t m_receivedPpdus{0}; ///< Number of successfully received PPDUs (with unicast data).
56 uint64_t m_failedPpdus{0}; ///< Number of failed PPDU receptions (with unicast data).
57 uint64_t m_receivedMpdus{0}; ///< Number of successfully received unicast data MPDUs.
58 uint64_t m_failedMpdus{0}; ///< Number of failed unicast data MPDU receptions.
59 std::map<WifiPhyRxfailureReason, uint64_t> m_ppduDropReasons; ///< Counts of the drop reasons
60};
61
62/**
63 * @struct WifiPpduRxRecord
64 * @brief Structure recording a received PPDU (Physical Protocol Data Unit) in a Wi-Fi network.
65 *
66 * This structure contains various details about the received PPDU, such as signal strength,
67 * identifiers for the sender and receiver, timing information, and reception status.
68 */
70{
71 Ptr<const WifiPpdu> m_ppdu{nullptr}; ///< Pointer to the received PPDU.
72 double m_rssi{0}; ///< Received Signal Strength Indicator (RSSI) in dBm.
73 uint64_t m_rxTag{
74 std::numeric_limits<uint64_t>::max()}; ///< Unique tag for the reception of this PPDU.
75 uint32_t m_receiverId{std::numeric_limits<uint32_t>::max()}; ///< Node ID of the receiver.
76 Time m_startTime; ///< Start time of the PPDU reception.
77 Time m_endTime; ///< End time of the PPDU reception.
79 WifiPhyRxfailureReason::UNKNOWN}; ///< Reason for reception failure, if any.
80 std::vector<WifiPpduRxRecord>
81 m_overlappingPpdu; ///< List of PPDUs that overlapped in time with this reception.
82 std::vector<bool> m_statusPerMpdu; ///< Reception status for each MPDU within the PPDU.
83 uint8_t m_linkId{std::numeric_limits<uint8_t>::max()}; ///< The link ID belonging to this record
84 uint32_t m_senderId{std::numeric_limits<uint32_t>::max()}; ///< Node ID of the sender.
85 uint32_t m_senderDeviceId{std::numeric_limits<uint32_t>::max()}; ///< Device ID of Sender
86};
87
88/**
89 * @class WifiPhyRxTraceHelper
90 * @brief Assists in tracing and analyzing Wi-Fi Physical Layer (PHY) receptions.
91 *
92 * The WifiPhyRxTraceHelper class can be used to instrument Wi-Fi nodes (or devices, or
93 * links) to keep track of the reception of Wi-Fi signals, and in particular, whether they overlap
94 * (collide) with one another. The implementation maintains reception records within internal
95 * data structures, and statistics or full reception records can be queried.
96 *
97 * The class provides functionality to connect traces to all nodes and WifiNetDevices within scope,
98 * enabling the capture of all Physical Protocol Data Units (PPDUs) received. It also
99 * allows for the collection and retrieval of statistics related to successful and failed receptions
100 * of PPDUs containing unicast data, and their corresponding MAC Protocol Data Units (MPDUs).
101 *
102 * Key features include:
103 * - Enabling trace connections to capture reception data.
104 * - Starting and stopping the collection of statistics at specified times.
105 * - Resetting the collected data for fresh starts in data collection.
106 * - Accessing detailed reception records for further analysis.
107 *
108 * Usage involves connecting to desired nodes or devices, (optionally) managing the
109 * collection period with start, stop, and reset methods, and finally, accessing the collected
110 * statistics or reception records.
111 *
112 * Statistics are only compiled for unicast data (WIFI_MAC_DATA and WIFI_MAC_QOSDATA), although
113 * PPDU records are kept for all frame types because it is possible for non-data frames to
114 * collide with data frames.
115 */
117{
118 friend class ::TestWifiPhyRxTraceHelper;
119 friend class ::TestWifiPhyRxTraceHelperMloStr;
120 friend class ::TestWifiPhyRxTraceHelperYans;
121
122 public:
123 /**
124 * Constructor.
125 */
127
128 /**
129 * Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.
130 * @param nodes The NodeContainer to which traces are to be connected.
131 */
133
134 /**
135 * Enables trace collection for all nodes corresponding to the devices in the specified
136 * NetDeviceContainer.
137 * @param devices The NetDeviceContainer containing nodes to which traces are to be connected.
138 */
139 void Enable(NetDeviceContainer devices);
140
141 /**
142 * Retrieves current statistics of successful and failed data PPDUs and MPDUs receptions,
143 * for all nodes, devices, and links that have been enabled.
144 *
145 * Statistics are compiled for the current observation window, which extends to the
146 * trace helper start time or last reset time (whichever is later) until the last
147 * stop time or the current time (whichever is earlier).
148 *
149 * @return A WifiPhyTraceStatistics object containing current reception statistics.
150 */
152
153 /**
154 * Retrieves reception statistics for a given node, device, and link.
155 * @param node Ptr to Node.
156 * @param deviceId Device identifier (optional, defaults to 0).
157 * @param linkId Link identifier (optional, defaults to 0).
158 * @return WifiPhyTraceStatistics object with current reception stats.
159 */
161 uint32_t deviceId = 0,
162 uint8_t linkId = 0) const;
163
164 /**
165 * Retrieves reception statistics for a given node, device, and link.
166 * @param nodeId Node identifier.
167 * @param deviceId Device identifier (optional, defaults to 0).
168 * @param linkId Link identifier (optional, defaults to 0).
169 * @return WifiPhyTraceStatistics object with current reception stats.
170 */
172 uint32_t deviceId = 0,
173 uint8_t linkId = 0) const;
174
175 /**
176 * Starts the collection of statistics from a specified start time.
177 * @param startTime The time to start collecting statistics.
178 */
179 void Start(Time startTime);
180
181 /**
182 * Stops the collection of statistics at a specified time.
183 * @param stopTime The time to stop collecting statistics.
184 */
185 void Stop(Time stopTime);
186
187 /**
188 * Resets the current statistics, clearing all counts and PPDU records.
189 */
190 void Reset();
191
192 /**
193 * Accesses a vector of saved and completed PPDU reception records.
194 * @return A constant reference to a vector of WifiPpduRxRecord instances.
195 */
196 const std::vector<WifiPpduRxRecord>& GetPpduRecords() const;
197
198 /**
199 * Accesses PPDU reception records for a specific node, device, and link.
200 *
201 * Because the return value could be null if the specified node/device/link do not have any
202 * records, this method returns a std::optional object, and because we are passing the
203 * underlying vector by const reference to avoid a copy, it must be wrapped by
204 * std::reference_wrapper. See the example program wifi-phy-reception-trace-example.cc for an
205 * example of how to use the value returned.
206 *
207 * @param nodeId The ID of the node.
208 * @param deviceId The ID of the WifiNetDevice (optional, defaults to 0).
209 * @param linkId The ID of the link (optional, defaults to 0).
210 * @return A reference to a vector of WifiPpduRxRecord instances.
211 */
212 std::optional<std::reference_wrapper<const std::vector<WifiPpduRxRecord>>> GetPpduRecords(
213 uint32_t nodeId,
214 uint32_t deviceId = 0,
215 uint8_t linkId = 0) const;
216
217 /**
218 * Print statistics for all nodes, devices, and links during the collection period.
219 */
220 void PrintStatistics() const;
221
222 /**
223 * Prints statistics collected in the period for a specific node, device, and link.
224 * @param node Ptr to Node.
225 * @param deviceId Device identifier (optional, defaults to 0).
226 * @param linkId Link identifier (optional, defaults to 0).
227 */
228 void PrintStatistics(Ptr<Node> node, uint32_t deviceId = 0, uint8_t linkId = 0) const;
229
230 /**
231 * Prints statistics collected in the period for a specific node, device, and link.
232 * @param nodeId Node identifier.
233 * @param deviceId Device identifier (optional, defaults to 0).
234 * @param linkId Link identifier (optional, defaults to 0).
235 */
236 void PrintStatistics(uint32_t nodeId, uint32_t deviceId = 0, uint8_t linkId = 0) const;
237
238 private:
239 /**
240 * Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.
241 * @param nodes The NodeContainer to which traces are to be connected.
242 * @param MacToNodeMap A mapping from MAC address to node ID.
243 */
244 void Enable(NodeContainer nodes, const std::map<Mac48Address, uint32_t>& MacToNodeMap);
245
246 /**
247 * Populates the mapping of MAC addresses to node IDs for a given set of nodes.
248 * @param nodes The container of nodes for which to populate the MAC address to node ID mapping.
249 * @return a copy of the std::map container
250 */
251 std::map<Mac48Address, uint32_t> MapMacAddressesToNodeIds(NodeContainer nodes) const;
252
253 Ptr<WifiPhyRxTraceSink> m_traceSink; ///< Pointer to the current trace sink object.
254};
255
256/**
257 * @class WifiPhyRxTraceSink
258 * @brief Sink class for capturing and analyzing PHY layer reception events in Wi-Fi networks.
259 *
260 * The WifiPhyRxTraceSink class acts as a comprehensive sink for events related to the
261 * reception of signals at the Physical Layer (PHY) of Wi-Fi networks. It is designed to facilitate
262 * the detailed analysis and tracing of reception activities, and the management of reception data
263 * across nodes, devices, and links. This class supports the capture and analysis of detailed
264 * reception records, including successful and failed receptions, and offers capabilities to
265 * manage the collection of reception statistics.
266 *
267 * Features include:
268 * - Unique tag generation for tracking individual reception events.
269 * - Access to detailed PPDU reception records for analysis.
270 * - Management of reception statistics collection through start, stop, and reset operations.
271 * - Mapping of MAC addresses to node IDs for network element identification.
272 * - Handling of PHY signal transmission and reception events for detailed outcome logging.
273 * - Tracking and analysis of overlapping reception events for interference assessment.
274 */
276{
277 public:
278 /**
279 * Constructor.
280 */
282
283 /**
284 * Retrieves the TypeId of the class.
285 * @return The TypeId of the WifiPhyRxTraceSink class.
286 */
287 static TypeId GetTypeId();
288
289 /**
290 * @brief Generating unique tags for more than one instance of a WifiPpdu object
291 *
292 * This class is responsible for generating unique identifiers for each received
293 * WifiPpdu. The WifiPpdu UID is not sufficient because there can be more than one
294 * record per WifiPpdu.
295 */
297 {
298 public:
299 /**
300 * Generates a unique tag for a WifiPpdu. Uses an internal counter and a set of
301 * previously used tags to ensure that each generated tag is unique, allowing accurate
302 * tracking of received frames.
303 * @param ppduUid The PPDU UID to generate a unique tag for.
304 * @return uint64_t The generated unique tag.
305 */
306 uint64_t GenerateUniqueTag(uint64_t ppduUid);
307
308 private:
309 uint64_t counter{0}; ///< Counter to help generate unique tags.
310 std::set<uint64_t> usedTags; ///< Set of already used tags.
311 };
312
313 UniqueTagGenerator m_tagGenerator; ///< Instance of UniqueTagGenerator used for generating
314 ///< unique reception tags.
315
316 /**
317 * Provides access to all saved and completed PPDU reception records across all nodes,
318 * WifiNetDevices, and links.
319 * @return A constant reference to a vector of WifiPpduRxRecord instances.
320 */
321 const std::vector<WifiPpduRxRecord>& GetPpduRecords() const;
322
323 /**
324 * Provides access to PPDU reception records for a specific node, device, and link.
325 * @param nodeId The ID of the node.
326 * @param deviceId The ID of the WifiNetDevice (optional, defaults to 0).
327 * @param linkId The ID of the link (optional, defaults to 0).
328 * @return A constant reference to a vector of WifiPpduRxRecord instances.
329 */
330 std::optional<std::reference_wrapper<const std::vector<WifiPpduRxRecord>>> GetPpduRecords(
331 uint32_t nodeId,
332 uint32_t deviceId = 0,
333 uint8_t linkId = 0) const;
334
335 /**
336 * Creates a vector with all completed WiFi reception records to be returned by the
337 * GetPpduRecords(). This is only called if no specific node, device or link is
338 * provided.
339 */
341
342 /**
343 * Provides a custom mapping of MAC addresses to intended receiver node IDs. This mapping is
344 * crucial for identifying the nodes involved in reception events based on their MAC addresses,
345 * facilitating the analysis of network dynamics at the PHY layer.
346 * @param MacAddressToNodeIdMap A mapping from MAC addresses to node IDs.
347 */
348 void SetMapMacAddressToNodeId(const std::map<Mac48Address, uint32_t>& MacAddressToNodeIdMap);
349
350 /**
351 * Retrieves the frequency and channel number used by a specific link.
352 * @param node The node ID.
353 * @param deviceId The device ID of the WifiNetDevice.
354 * @param link The link ID.
355 * @return A pair containing the channel number (uint8_t) and frequency (uint16_t).
356 */
357 std::optional<std::pair<uint8_t, uint16_t>> GetChannelInfo(uint32_t node,
358 uint32_t deviceId,
359 int link) const;
360
361 /**
362 * Starts the statistics collection period from a specified start time. Ongoing PPDUs when this
363 * method is called will be counted towards this statistics collection period.
364 */
365 void Start();
366
367 /**
368 * Stops the statistics collection period at a specified time. This method ensures that
369 * incomplete PPDUs at the end of the collection period are not included in the current
370 * statistics count.
371 */
372 void Stop();
373
374 /**
375 * Resets the statistics collection, clearing all counts and discarding all fully completed PPDU
376 * records. This allows for a fresh start in data collection and analysis.
377 */
378 void Reset();
379
380 /**
381 * Translates a context string to a link ID, facilitating the association of events with
382 * specific links in the network.
383 * @param context The context string.
384 * @return The link ID associated with the context.
385 */
386 int ContextToLinkId(std::string context) const;
387
388 /**
389 * Translates a context string to a device ID, enabling the identification of devices involved
390 * in reception events based on context information.
391 * @param context The context string.
392 * @return The device ID associated with the context.
393 */
394 int ContextToDeviceId(std::string context) const;
395
396 /**
397 * Translates a context string to a node ID.
398 * @param context The context string to translate.
399 * @return The corresponding node ID, facilitating the identification of the node involved in a
400 * reception event.
401 */
402 uint32_t ContextToNodeId(std::string context) const;
403
404 /**
405 * Translate a context string to a colon-delimited tuple "0:0:0" where the first element
406 * is a node ID, second is a device ID, third is a link ID
407 * @param context The context string to translate.
408 * @return The tuple of node, device, and link IDs
409 */
410 std::string ContextToTuple(std::string context) const;
411
412 /**
413 * Handles the event of a PHY signal transmission.
414 * @param context The context string, providing situational information about the transmission.
415 * @param ppdu The Wi-Fi PPDU being transmitted.
416 * @param txVector The transmission vector, detailing the parameters of the transmission.
417 */
418 void PhySignalTransmission(std::string context,
420 const WifiTxVector& txVector);
421
422 /**
423 * @brief Handles the event of a Wi-Fi PPDU arrival.
424 *
425 * @param context The context string, offering contextual information about the signal
426 * reception.
427 * @param ppdu The received WifiPpdu
428 * @param rxPower The power level at which the signal was received, indicating the signal's
429 * strength.
430 * @param duration The duration of the signal, offering temporal information about the reception
431 * event.
432 */
433 void PhySignalArrival(std::string context,
435 double rxPower,
436 Time duration);
437
438 /**
439 * @brief Handles the event of a PHY signal arrival from a SpectrumChannel.
440 *
441 * @param context The context string, offering contextual information about the signal
442 * reception.
443 * @param signal The received signal parameters, detailing the characteristics of the arriving
444 * signal.
445 * @param senderNodeId The ID of the node sending the signal, providing insight into the source
446 * of the signal.
447 * @param rxPower The power level at which the signal was received, indicating the signal's
448 * strength.
449 * @param duration The duration of the signal, offering temporal information about the reception
450 * event.
451 */
452 void SpectrumPhySignalArrival(std::string context,
454 uint32_t senderNodeId,
455 double rxPower,
456 Time duration);
457
458 /**
459 * Maps nodes to links and channels, creating a structured association between network
460 * elements and their communication channels. This mapping is essential for understanding
461 * what frequency and channel number is used for a given link.
462 * @param nodes NodeContainer of all nodes whose MAC address is going to be link to their
463 * NodeID.
464 */
466
467 /**
468 * Returns statistics on the count of successful and failed PPDUs with unicast data, and their
469 * MPDUs, across all nodes, devices, and links.
470 * @return A WifiPhyTraceStatistics object containing the current statistics. This method does
471 * not reset the collected statistics, allowing for continuous accumulation of data over time.
472 */
474
475 /**
476 * Returns statistics on the count of successful and failed PPDUs with unicast data, and their
477 * MPDUs, for a specific node, device, and link.
478 * @param nodeId The node ID from which to get the statistics.
479 * @param deviceId The device ID from which to get the statistics.
480 * @param linkId The link ID from which to get the statistics.
481 * @return A WifiPhyTraceStatistics object containing the current statistics. This method does
482 * not reset the collected statistics, allowing for continuous accumulation of data over time.
483 */
484 WifiPhyTraceStatistics GetStatistics(uint32_t nodeId, uint32_t deviceId, uint8_t linkId) const;
485
486 /**
487 * Updates the information for signals currently being received by a node.
488 * @param nodeId The node ID for which to update the reception information.
489 * @param deviceId The device ID on the node for which to update the information.
490 * @param linkId The link ID associated with the ongoing reception.
491 */
492 void UpdateCurrentlyReceivedSignal(uint32_t nodeId, uint32_t deviceId, uint8_t linkId);
493
494 /**
495 * Records the outcome of a PPDU transmission, including the signal info, and the success or
496 * failure status of each MPDU within the PPDU.
497 * @param context Descriptive context for the PPDU outcome.
498 * @param ppdu Pointer to the PPDU whose outcome is being recorded.
499 * @param signal Information about the received signal.
500 * @param txVector The transmission vector used for the PPDU.
501 * @param statusPerMpdu A vector indicating the success (true) or failure (false) of each MPDU.
502 */
503 void PpduOutcome(std::string context,
505 RxSignalInfo signal,
506 const WifiTxVector& txVector,
507 const std::vector<bool>& statusPerMpdu);
508
509 /**
510 * Logs the drop of a PPDU at the PHY layer, detailing the context and reason for the drop.
511 * @param context Descriptive context for the PPDU drop.
512 * @param ppdu Pointer to the PPDU that was dropped.
513 * @param reason The reason for the PPDU drop, represented as a WifiPhyRxfailureReason.
514 */
515 void PhyPpduDrop(std::string context, Ptr<const WifiPpdu> ppdu, WifiPhyRxfailureReason reason);
516
517 /**
518 * Handles the end of a PHY reception event, logging the conclusion of a reception and its
519 * associated details.
520 * @param nodeId The node ID where the reception ended.
521 * @param deviceId The device ID on the node where the reception took place.
522 * @param rxTag The unique reception tag associated with the reception event.
523 * @param ppduUid The PPDU UID of the received WifiPpdu
524 */
525 void PhyRxEnd(uint32_t nodeId, uint32_t deviceId, uint64_t rxTag, uint64_t ppduUid);
526
527 /**
528 * Handles the conclusion of a transmission event, facilitating the logging of transmission
529 * outcomes.
530 * @param nodeId The node ID from which the transmission originated.
531 * @param deviceId The device ID on the node that performed the transmission.
532 * @param ppduRecord The WifiPpduRxRecord representing the concluded transmission.
533 */
534 void EndTx(uint32_t nodeId, uint32_t deviceId, WifiPpduRxRecord ppduRecord);
535
536 /**
537 * Counts and aggregates PHY layer statistics including receptions, transmissions, and
538 * performance metrics (Success, Failure, Overlap) of unicast data PPDUs and MPDUs across all
539 * nodes.
540 * @return WifiPhyTraceStatistics object containing aggregated statistics for all nodes.
541 */
543
544 /**
545 * Counts statistics related to PHY layer receptions, transmissions, and performance metrics
546 * such as Success, Failure or Overlap of a PPDU containing unicast data, and the MPDUs within,
547 * for the specific node,
548 * device and link.
549 * @param nodeId Node identifier.
550 * @param deviceId Device identifier.
551 * @param linkId Link identifier.
552 * @return WifiPhyTraceStatistics object with current reception stats.
553 */
555 uint32_t deviceId,
556 uint8_t linkId) const;
557
558 /**
559 * Prints a summary of the statistics collected, offering a concise overview of PHY layer
560 * performance and reception outcomes for all nodes, devices and links.
561 */
562 void PrintStatistics() const;
563
564 /**
565 * Prints statistics collected in the period for a node, device, and link.
566 * @param nodeId Node identifier.
567 * @param deviceId Device identifier.
568 * @param linkId Link identifier.
569 */
570 void PrintStatistics(uint32_t nodeId, uint32_t deviceId, uint8_t linkId) const;
571
572 /**
573 * @brief Returns whether the collection period is active
574 * @return Whether the collection period is active
575 */
576 bool IsCollectionPeriodActive() const;
577
578 /**
579 * @brief Maps a reception tag to the corresponding WifiPpduRxRecord.
580 *
581 * This map links each unique reception tag generated upon receiving a
582 * frame to the corresponding detailed reception record (WifiPpduRxRecord). It is
583 * refreshed every time a new reception record is created.
584 */
585 std::map<uint64_t, WifiPpduRxRecord> m_rxTagToPpduRecord;
586
587 /**
588 * @brief Stores records of PPDUs that have completed reception, organized by node, device, and
589 * link.
590 *
591 * This nested map structure is updated each time a WifiPpduRxRecord is finalized,
592 * keeping a history of all completed packet receptions across different nodes,
593 * devices, and links.
594 */
595 std::map<uint32_t, std::map<uint32_t, std::map<uint8_t, std::vector<WifiPpduRxRecord>>>>
597
598 /**
599 * @brief Stores a flat vector of all records of PPDUs that have completed reception.
600 *
601 * This vector is updated upon the request of GetPpduRecords(),
602 * maintaining all packet receptions.
603 */
604 std::vector<WifiPpduRxRecord> m_records;
605
606 /**
607 * @brief Tracks ongoing frames being transmitted or received per node, device, and link.
608 *
609 * This map associates each node (by its ID) with nested maps keyed by device and link IDs, each
610 * containing vectors of WifiPpduRxRecords. It enables the tracking of current packet
611 * transmissions and receptions.
612 */
613 std::map<uint32_t, std::map<uint32_t, std::map<uint32_t, std::vector<WifiPpduRxRecord>>>>
615
616 /**
617 * @brief Maps each reception tag to a list of overlapping WifiPpduRxRecords.
618 *
619 * For each unique reception tag, this map stores a vector of WifiPpduRxRecords that
620 * overlap with the record corresponding to the tag.
621 */
622 std::map<uint64_t, std::vector<WifiPpduRxRecord>> m_rxTagToListOfOverlappingPpduRecords;
623
624 /**
625 * @brief Aids in correlating PHY reception drops and outcomes with specific reception tags.
626 *
627 * This complex map structure is used to navigate from node and device IDs, and link and packet
628 * IDs (PIDs), to the corresponding reception tag.
629 */
630 std::map<uint64_t, std::map<uint64_t, std::map<uint64_t, std::map<uint64_t, uint64_t>>>>
632
633 /**
634 * @brief Maps WifiPpdu UIDs to WifiPpduRxRecord tags stored by transmitter.
635 *
636 * This map allows a transmit-side PPDU record to be fetched based on the WifiPpdu UID.
637 */
638 std::map<uint64_t, uint64_t> m_ppduUidToTxTag;
639
640 /**
641 * @brief Maps MAC addresses to node IDs.
642 *
643 * This mapping facilitates the identification of nodes within the network based on the MAC
644 * addresses observed in reception events. By translating MAC addresses to node IDs, this map
645 * enables the association of reception data with specific network nodes.
646 */
647 std::map<Mac48Address, uint32_t> m_macAddressToNodeId;
648
649 /**
650 * Maps node IDs to device IDs and further to link IDs, associating each with a pair consisting
651 * of the channel number and frequency. This structure is vital for understanding the channel
652 * and frequency utilization across different links.
653 */
654 std::map<uint32_t, std::map<uint32_t, std::map<int, std::pair<uint8_t, uint16_t>>>>
656
657 private:
658 /**
659 * Flag indicating whether to keep a record of certain statistics or events for analysis. This
660 * boolean flag can be toggled to control the granularity and scope of data collection, enabling
661 * customization of the analysis to focus on specific times of interest.
662 */
664
665 /**
666 * Update the passed-in statistics object with statistics from the passed-in record.
667 * @param statistics The WifiPhyTraceStatistics object to modify
668 * @param record The WifiPpduRxRecord to examine
669 */
671 const WifiPpduRxRecord& record) const;
672
673}; // class WifiPhyRxTraceSink
674
675// Non-member function declarations
676
677/**
678 * @brief Checks if two WifiPpduRxRecord objects are equal.
679 *
680 * Compares two WifiPpduRxRecord objects to determine if they are equal. Two objects
681 * are considered equal if all their corresponding counts have the same values.
682 *
683 * @param lhs The left-hand side WifiPpduRxRecord object in the comparison.
684 * @param rhs The right-hand side WifiPpduRxRecord object in the comparison.
685 * @return true if the objects are equal, false otherwise.
686 */
687bool operator==(const WifiPpduRxRecord& lhs, const WifiPpduRxRecord& rhs);
688
689/**
690 * @brief Checks if two WifiPpduRxRecord objects are not equal.
691 *
692 * Compares two WifiPpduRxRecord objects to determine if they are not equal. Two objects
693 * are considered not equal if at least one of their corresponding counts have different values.
694 *
695 * @param lhs The left-hand side WifiPpduRxRecord object in the comparison.
696 * @param rhs The right-hand side WifiPpduRxRecord object in the comparison.
697 * @return true if the objects are not equal, false otherwise.
698 */
699bool operator!=(const WifiPpduRxRecord& lhs, const WifiPpduRxRecord& rhs);
700
701/**
702 * @brief Determines if one WifiPpduRxRecord object is less than another.
703 *
704 * Compares two WifiPpduRxRecord objects to determine if the left-hand side object is
705 * considered less than the right-hand side object based on a specific criteria of comparison,
706 * such as a key property value.
707 *
708 * @note The specific criteria for comparison should be defined and consistent.
709 *
710 * @param lhs The left-hand side WifiPpduRxRecord object in the comparison.
711 * @param rhs The right-hand side WifiPpduRxRecord object in the comparison.
712 * @return true if lhs is considered less than rhs, false otherwise.
713 */
714bool operator<(const WifiPpduRxRecord& lhs, const WifiPpduRxRecord& rhs);
715
716/**
717 * @brief Checks if two WifiPhyTraceStatistics objects are equal.
718 *
719 * Determines if two WifiPhyTraceStatistics objects are equal by comparing their counts.
720 * Equality is based on the values of all relevant statistical counts being identical.
721 *
722 * @param lhs The left-hand side WifiPhyTraceStatistics object in the comparison.
723 * @param rhs The right-hand side WifiPhyTraceStatistics object in the comparison.
724 * @return true if all counts are equal, false otherwise.
725 */
726bool operator==(const WifiPhyTraceStatistics& lhs, const WifiPhyTraceStatistics& rhs);
727
728/**
729 * @brief Checks if two WifiPhyTraceStatistics objects are not equal.
730 *
731 * Determines if two WifiPhyTraceStatistics objects are not equal by comparing their counts.
732 * Non-equality is based on any of the relevant statistical counts having different values.
733 *
734 * @param lhs The left-hand side WifiPhyTraceStatistics object in the comparison.
735 * @param rhs The right-hand side WifiPhyTraceStatistics object in the comparison.
736 * @return true if any property is different, false otherwise.
737 */
738bool operator!=(const WifiPhyTraceStatistics& lhs, const WifiPhyTraceStatistics& rhs);
739
740/**
741 * @brief Adds two WifiPhyTraceStatistics objects.
742 *
743 * Combines two WifiPhyTraceStatistics objects by summing their counts.
744 * This can be useful for aggregating statistics from multiple sources or time periods.
745 *
746 * @param lhs The left-hand side WifiPhyTraceStatistics object to be added.
747 * @param rhs The right-hand side WifiPhyTraceStatistics object to be added.
748 * @return A new WifiPhyTraceStatistics object that is the result of the addition.
749 */
750WifiPhyTraceStatistics operator+(const WifiPhyTraceStatistics& lhs,
751 const WifiPhyTraceStatistics& rhs);
752
753} // namespace ns3
754
755#endif /* WIFI_PHY_RX_TRACE_HELPER_H */
Implements a test case to evaluate the reception process of WiFi Physical Layer (PHY) frames (PPDU) w...
Implements a test case to evaluate the reception process of WiFi Physical Layer (PHY) frames (PPDU) c...
Implements a test case to evaluate the reception process of WiFi Physical Layer (PHY) frames (PPDU) w...
holds a vector of ns3::NetDevice pointers
keep track of a set of node pointers.
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
Assists in tracing and analyzing Wi-Fi Physical Layer (PHY) receptions.
const std::vector< WifiPpduRxRecord > & GetPpduRecords() const
Accesses a vector of saved and completed PPDU reception records.
void PrintStatistics() const
Print statistics for all nodes, devices, and links during the collection period.
void Reset()
Resets the current statistics, clearing all counts and PPDU records.
Ptr< WifiPhyRxTraceSink > m_traceSink
Pointer to the current trace sink object.
void Stop(Time stopTime)
Stops the collection of statistics at a specified time.
WifiPhyTraceStatistics GetStatistics() const
Retrieves current statistics of successful and failed data PPDUs and MPDUs receptions,...
void Enable(NodeContainer nodes)
Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.
std::map< Mac48Address, uint32_t > MapMacAddressesToNodeIds(NodeContainer nodes) const
Populates the mapping of MAC addresses to node IDs for a given set of nodes.
void Start(Time startTime)
Starts the collection of statistics from a specified start time.
Generating unique tags for more than one instance of a WifiPpdu object.
std::set< uint64_t > usedTags
Set of already used tags.
uint64_t GenerateUniqueTag(uint64_t ppduUid)
Generates a unique tag for a WifiPpdu.
uint64_t counter
Counter to help generate unique tags.
Sink class for capturing and analyzing PHY layer reception events in Wi-Fi networks.
std::map< uint64_t, std::map< uint64_t, std::map< uint64_t, std::map< uint64_t, uint64_t > > > > m_nodeDeviceLinkPidToRxId
Aids in correlating PHY reception drops and outcomes with specific reception tags.
void Reset()
Resets the statistics collection, clearing all counts and discarding all fully completed PPDU records...
std::map< uint32_t, std::map< uint32_t, std::map< uint8_t, std::vector< WifiPpduRxRecord > > > > m_completedRecords
Stores records of PPDUs that have completed reception, organized by node, device, and link.
void CreateVectorFromRecords()
Creates a vector with all completed WiFi reception records to be returned by the GetPpduRecords().
void SpectrumPhySignalArrival(std::string context, Ptr< const SpectrumSignalParameters > signal, uint32_t senderNodeId, double rxPower, Time duration)
Handles the event of a PHY signal arrival from a SpectrumChannel.
const std::vector< WifiPpduRxRecord > & GetPpduRecords() const
Provides access to all saved and completed PPDU reception records across all nodes,...
bool m_statisticsCollectionPeriodStarted
Flag indicating whether to keep a record of certain statistics or events for analysis.
void Stop()
Stops the statistics collection period at a specified time.
WifiPhyTraceStatistics CountStatistics() const
Counts and aggregates PHY layer statistics including receptions, transmissions, and performance metri...
void PhyRxEnd(uint32_t nodeId, uint32_t deviceId, uint64_t rxTag, uint64_t ppduUid)
Handles the end of a PHY reception event, logging the conclusion of a reception and its associated de...
bool IsCollectionPeriodActive() const
Returns whether the collection period is active.
std::map< uint64_t, WifiPpduRxRecord > m_rxTagToPpduRecord
Maps a reception tag to the corresponding WifiPpduRxRecord.
std::map< Mac48Address, uint32_t > m_macAddressToNodeId
Maps MAC addresses to node IDs.
void PhyPpduDrop(std::string context, Ptr< const WifiPpdu > ppdu, WifiPhyRxfailureReason reason)
Logs the drop of a PPDU at the PHY layer, detailing the context and reason for the drop.
std::optional< std::pair< uint8_t, uint16_t > > GetChannelInfo(uint32_t node, uint32_t deviceId, int link) const
Retrieves the frequency and channel number used by a specific link.
std::vector< WifiPpduRxRecord > m_records
Stores a flat vector of all records of PPDUs that have completed reception.
void PhySignalTransmission(std::string context, Ptr< const WifiPpdu > ppdu, const WifiTxVector &txVector)
Handles the event of a PHY signal transmission.
void PrintStatistics() const
Prints a summary of the statistics collected, offering a concise overview of PHY layer performance an...
WifiPhyTraceStatistics GetStatistics() const
Returns statistics on the count of successful and failed PPDUs with unicast data, and their MPDUs,...
std::map< uint64_t, std::vector< WifiPpduRxRecord > > m_rxTagToListOfOverlappingPpduRecords
Maps each reception tag to a list of overlapping WifiPpduRxRecords.
std::string ContextToTuple(std::string context) const
Translate a context string to a colon-delimited tuple "0:0:0" where the first element is a node ID,...
void Start()
Starts the statistics collection period from a specified start time.
void PpduOutcome(std::string context, Ptr< const WifiPpdu > ppdu, RxSignalInfo signal, const WifiTxVector &txVector, const std::vector< bool > &statusPerMpdu)
Records the outcome of a PPDU transmission, including the signal info, and the success or failure sta...
std::map< uint32_t, std::map< uint32_t, std::map< uint32_t, std::vector< WifiPpduRxRecord > > > > m_nodeDeviceLinkRxRecords
Tracks ongoing frames being transmitted or received per node, device, and link.
void EndTx(uint32_t nodeId, uint32_t deviceId, WifiPpduRxRecord ppduRecord)
Handles the conclusion of a transmission event, facilitating the logging of transmission outcomes.
int ContextToDeviceId(std::string context) const
Translates a context string to a device ID, enabling the identification of devices involved in recept...
void CountStatisticsForRecord(WifiPhyTraceStatistics &statistics, const WifiPpduRxRecord &record) const
Update the passed-in statistics object with statistics from the passed-in record.
void PhySignalArrival(std::string context, Ptr< const WifiPpdu > ppdu, double rxPower, Time duration)
Handles the event of a Wi-Fi PPDU arrival.
UniqueTagGenerator m_tagGenerator
Instance of UniqueTagGenerator used for generating unique reception tags.
void SetMapMacAddressToNodeId(const std::map< Mac48Address, uint32_t > &MacAddressToNodeIdMap)
Provides a custom mapping of MAC addresses to intended receiver node IDs.
void UpdateCurrentlyReceivedSignal(uint32_t nodeId, uint32_t deviceId, uint8_t linkId)
Updates the information for signals currently being received by a node.
uint32_t ContextToNodeId(std::string context) const
Translates a context string to a node ID.
int ContextToLinkId(std::string context) const
Translates a context string to a link ID, facilitating the association of events with specific links ...
void MapNodeToLinkToChannel(NodeContainer nodes)
Maps nodes to links and channels, creating a structured association between network elements and thei...
std::map< uint32_t, std::map< uint32_t, std::map< int, std::pair< uint8_t, uint16_t > > > > m_nodeToDeviceToLinkToChannelInfo
Maps node IDs to device IDs and further to link IDs, associating each with a pair consisting of the c...
std::map< uint64_t, uint64_t > m_ppduUidToTxTag
Maps WifiPpdu UIDs to WifiPpduRxRecord tags stored by transmitter.
static TypeId GetTypeId()
Retrieves the TypeId of the class.
This class mimics the TXVECTOR which is to be passed to the PHY in order to define the parameters whi...
Time stopTime
int64x64_t operator+(const int64x64_t &lhs, const int64x64_t &rhs)
Addition operator.
Definition int64x64.h:76
WifiPhyRxfailureReason
Enumeration of the possible reception failure reasons.
NodeContainer nodes
Every class exported by the ns3 library is enclosed in the ns3 namespace.
bool operator!=(Callback< R, Args... > a, Callback< R, Args... > b)
Inequality test.
Definition callback.h:658
bool operator==(const EventId &a, const EventId &b)
Definition event-id.h:155
bool operator<(const EventId &a, const EventId &b)
Definition event-id.h:168
RxSignalInfo structure containing info on the received signal.
Definition wifi-types.h:72
Keeps track of PHY layer trace statistics.
std::map< WifiPhyRxfailureReason, uint64_t > m_ppduDropReasons
Counts of the drop reasons.
uint64_t m_failedMpdus
Number of failed unicast data MPDU receptions.
uint64_t m_failedPpdus
Number of failed PPDU receptions (with unicast data).
uint64_t m_receivedPpdus
Number of successfully received PPDUs (with unicast data).
uint64_t m_receivedMpdus
Number of successfully received unicast data MPDUs.
uint64_t m_overlappingPpdus
Number of PPDUs that overlapped in time with at least one other PPDU.
uint64_t m_nonOverlappingPpdus
Number of PPDUs that did not overlap in time with any other PPDU.
Structure recording a received PPDU (Physical Protocol Data Unit) in a Wi-Fi network.
Ptr< const WifiPpdu > m_ppdu
Pointer to the received PPDU.
double m_rssi
Received Signal Strength Indicator (RSSI) in dBm.
Time m_endTime
End time of the PPDU reception.
Time m_startTime
Start time of the PPDU reception.
uint8_t m_linkId
The link ID belonging to this record.
WifiPhyRxfailureReason m_reason
Reason for reception failure, if any.
uint32_t m_senderDeviceId
Device ID of Sender.
uint32_t m_senderId
Node ID of the sender.
std::vector< bool > m_statusPerMpdu
Reception status for each MPDU within the PPDU.
std::vector< WifiPpduRxRecord > m_overlappingPpdu
List of PPDUs that overlapped in time with this reception.
uint32_t m_receiverId
Node ID of the receiver.
uint64_t m_rxTag
Unique tag for the reception of this PPDU.