A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ns3::WifiPhyRxTraceHelper Class Reference

Assists in tracing and analyzing Wi-Fi Physical Layer (PHY) receptions. More...

#include "wifi-phy-rx-trace-helper.h"

+ Collaboration diagram for ns3::WifiPhyRxTraceHelper:

Public Member Functions

 WifiPhyRxTraceHelper ()
 Constructor.
 
void Enable (NetDeviceContainer devices)
 Enables trace collection for all nodes corresponding to the devices in the specified NetDeviceContainer.
 
void Enable (NodeContainer nodes)
 Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.
 
const std::vector< WifiPpduRxRecord > & GetPpduRecords () const
 Accesses a vector of saved and completed PPDU reception records.
 
std::optional< std::reference_wrapper< const std::vector< WifiPpduRxRecord > > > GetPpduRecords (uint32_t nodeId, uint32_t deviceId=0, uint8_t linkId=0) const
 Accesses PPDU reception records for a specific node, device, and link.
 
WifiPhyTraceStatistics GetStatistics () const
 Retrieves current statistics of successful and failed data PPDUs and MPDUs receptions, for all nodes, devices, and links that have been enabled.
 
WifiPhyTraceStatistics GetStatistics (Ptr< Node > node, uint32_t deviceId=0, uint8_t linkId=0) const
 Retrieves reception statistics for a given node, device, and link.
 
WifiPhyTraceStatistics GetStatistics (uint32_t nodeId, uint32_t deviceId=0, uint8_t linkId=0) const
 Retrieves reception statistics for a given node, device, and link.
 
void PrintStatistics () const
 Print statistics for all nodes, devices, and links during the collection period.
 
void PrintStatistics (Ptr< Node > node, uint32_t deviceId=0, uint8_t linkId=0) const
 Prints statistics collected in the period for a specific node, device, and link.
 
void PrintStatistics (uint32_t nodeId, uint32_t deviceId=0, uint8_t linkId=0) const
 Prints statistics collected in the period for a specific node, device, and link.
 
void Reset ()
 Resets the current statistics, clearing all counts and PPDU records.
 
void Start (Time startTime)
 Starts the collection of statistics from a specified start time.
 
void Stop (Time stopTime)
 Stops the collection of statistics at a specified time.
 

Private Member Functions

void Enable (NodeContainer nodes, const std::map< Mac48Address, uint32_t > &MacToNodeMap)
 Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.
 
std::map< Mac48Address, uint32_tMapMacAddressesToNodeIds (NodeContainer nodes) const
 Populates the mapping of MAC addresses to node IDs for a given set of nodes.
 

Private Attributes

Ptr< WifiPhyRxTraceSinkm_traceSink
 Pointer to the current trace sink object.
 

Friends

class ::TestWifiPhyRxTraceHelper
 
class ::TestWifiPhyRxTraceHelperMloStr
 
class ::TestWifiPhyRxTraceHelperYans
 

Detailed Description

Assists in tracing and analyzing Wi-Fi Physical Layer (PHY) receptions.

The WifiPhyRxTraceHelper class can be used to instrument Wi-Fi nodes (or devices, or links) to keep track of the reception of Wi-Fi signals, and in particular, whether they overlap (collide) with one another. The implementation maintains reception records within internal data structures, and statistics or full reception records can be queried.

The class provides functionality to connect traces to all nodes and WifiNetDevices within scope, enabling the capture of all Physical Protocol Data Units (PPDUs) received. It also allows for the collection and retrieval of statistics related to successful and failed receptions of PPDUs containing unicast data, and their corresponding MAC Protocol Data Units (MPDUs).

Key features include:

  • Enabling trace connections to capture reception data.
  • Starting and stopping the collection of statistics at specified times.
  • Resetting the collected data for fresh starts in data collection.
  • Accessing detailed reception records for further analysis.

Usage involves connecting to desired nodes or devices, (optionally) managing the collection period with start, stop, and reset methods, and finally, accessing the collected statistics or reception records.

Statistics are only compiled for unicast data (WIFI_MAC_DATA and WIFI_MAC_QOSDATA), although PPDU records are kept for all frame types because it is possible for non-data frames to collide with data frames.

Definition at line 116 of file wifi-phy-rx-trace-helper.h.

Constructor & Destructor Documentation

◆ WifiPhyRxTraceHelper()

ns3::WifiPhyRxTraceHelper::WifiPhyRxTraceHelper ( )

Constructor.

Definition at line 46 of file wifi-phy-rx-trace-helper.cc.

References NS_LOG_FUNCTION.

Member Function Documentation

◆ Enable() [1/3]

void ns3::WifiPhyRxTraceHelper::Enable ( NetDeviceContainer devices)

Enables trace collection for all nodes corresponding to the devices in the specified NetDeviceContainer.

Parameters
devicesThe NetDeviceContainer containing nodes to which traces are to be connected.

Definition at line 59 of file wifi-phy-rx-trace-helper.cc.

References Enable(), ns3::NetDeviceContainer::Get(), ns3::NetDeviceContainer::GetN(), MapMacAddressesToNodeIds(), nodes, and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ Enable() [2/3]

void ns3::WifiPhyRxTraceHelper::Enable ( NodeContainer nodes)

Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.

Parameters
nodesThe NodeContainer to which traces are to be connected.

Definition at line 52 of file wifi-phy-rx-trace-helper.cc.

References Enable(), MapMacAddressesToNodeIds(), nodes, and NS_LOG_FUNCTION.

Referenced by TestWifiPhyRxTraceHelper::DoSetup(), TestWifiPhyRxTraceHelperMloStr::DoSetup(), TestWifiPhyRxTraceHelperYans::DoSetup(), Enable(), and Enable().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Enable() [3/3]

void ns3::WifiPhyRxTraceHelper::Enable ( NodeContainer nodes,
const std::map< Mac48Address, uint32_t > & MacToNodeMap )
private

Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.

Parameters
nodesThe NodeContainer to which traces are to be connected.
MacToNodeMapA mapping from MAC address to node ID.

Definition at line 78 of file wifi-phy-rx-trace-helper.cc.

References ns3::CreateObject(), ns3::DynamicCast(), m_traceSink, ns3::MakeCallback(), nodes, NS_ABORT_MSG_IF, NS_ASSERT_MSG, NS_FATAL_ERROR, NS_LOG_DEBUG, NS_LOG_FUNCTION, ns3::WifiPhyRxTraceSink::PhyPpduDrop(), ns3::WifiPhyRxTraceSink::PhySignalArrival(), ns3::WifiPhyRxTraceSink::PhySignalTransmission(), ns3::WifiPhyRxTraceSink::PpduOutcome(), and ns3::WifiPhyRxTraceSink::SpectrumPhySignalArrival().

+ Here is the call graph for this function:

◆ GetPpduRecords() [1/2]

const std::vector< WifiPpduRxRecord > & ns3::WifiPhyRxTraceHelper::GetPpduRecords ( ) const

Accesses a vector of saved and completed PPDU reception records.

Returns
A constant reference to a vector of WifiPpduRxRecord instances.

Definition at line 193 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink.

Referenced by TestWifiPhyRxTraceHelper::CheckRecords(), TestWifiPhyRxTraceHelperMloStr::CheckRecords(), and TestWifiPhyRxTraceHelperYans::CheckRecords().

+ Here is the caller graph for this function:

◆ GetPpduRecords() [2/2]

std::optional< std::reference_wrapper< const std::vector< WifiPpduRxRecord > > > ns3::WifiPhyRxTraceHelper::GetPpduRecords ( uint32_t nodeId,
uint32_t deviceId = 0,
uint8_t linkId = 0 ) const

Accesses PPDU reception records for a specific node, device, and link.

Because the return value could be null if the specified node/device/link do not have any records, this method returns a std::optional object, and because we are passing the underlying vector by const reference to avoid a copy, it must be wrapped by std::reference_wrapper. See the example program wifi-phy-reception-trace-example.cc for an example of how to use the value returned.

Parameters
nodeIdThe ID of the node.
deviceIdThe ID of the WifiNetDevice (optional, defaults to 0).
linkIdThe ID of the link (optional, defaults to 0).
Returns
A reference to a vector of WifiPpduRxRecord instances.

Definition at line 200 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink.

◆ GetStatistics() [1/3]

WifiPhyTraceStatistics ns3::WifiPhyRxTraceHelper::GetStatistics ( ) const

Retrieves current statistics of successful and failed data PPDUs and MPDUs receptions, for all nodes, devices, and links that have been enabled.

Statistics are compiled for the current observation window, which extends to the trace helper start time or last reset time (whichever is later) until the last stop time or the current time (whichever is earlier).

Returns
A WifiPhyTraceStatistics object containing current reception statistics.

Definition at line 214 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink.

Referenced by TestWifiPhyRxTraceHelper::CheckAllStats(), TestWifiPhyRxTraceHelperMloStr::CheckAllStats(), TestWifiPhyRxTraceHelperYans::CheckAllStats(), TestWifiPhyRxTraceHelper::CheckStats(), TestWifiPhyRxTraceHelperMloStr::CheckStats(), TestWifiPhyRxTraceHelperMloStr::CheckStats(), TestWifiPhyRxTraceHelperMloStr::CheckStats(), and TestWifiPhyRxTraceHelperYans::CheckStats().

+ Here is the caller graph for this function:

◆ GetStatistics() [2/3]

WifiPhyTraceStatistics ns3::WifiPhyRxTraceHelper::GetStatistics ( Ptr< Node > node,
uint32_t deviceId = 0,
uint8_t linkId = 0 ) const

Retrieves reception statistics for a given node, device, and link.

Parameters
nodePtr to Node.
deviceIdDevice identifier (optional, defaults to 0).
linkIdLink identifier (optional, defaults to 0).
Returns
WifiPhyTraceStatistics object with current reception stats.

Definition at line 220 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink.

◆ GetStatistics() [3/3]

WifiPhyTraceStatistics ns3::WifiPhyRxTraceHelper::GetStatistics ( uint32_t nodeId,
uint32_t deviceId = 0,
uint8_t linkId = 0 ) const

Retrieves reception statistics for a given node, device, and link.

Parameters
nodeIdNode identifier.
deviceIdDevice identifier (optional, defaults to 0).
linkIdLink identifier (optional, defaults to 0).
Returns
WifiPhyTraceStatistics object with current reception stats.

Definition at line 226 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink.

◆ MapMacAddressesToNodeIds()

std::map< Mac48Address, uint32_t > ns3::WifiPhyRxTraceHelper::MapMacAddressesToNodeIds ( NodeContainer nodes) const
private

Populates the mapping of MAC addresses to node IDs for a given set of nodes.

Parameters
nodesThe container of nodes for which to populate the MAC address to node ID mapping.
Returns
a copy of the std::map container

Definition at line 232 of file wifi-phy-rx-trace-helper.cc.

References ns3::Mac48Address::ConvertFrom(), ns3::DynamicCast(), nodes, and NS_LOG_DEBUG.

Referenced by Enable(), and Enable().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ PrintStatistics() [1/3]

void ns3::WifiPhyRxTraceHelper::PrintStatistics ( ) const

Print statistics for all nodes, devices, and links during the collection period.

Definition at line 161 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink.

◆ PrintStatistics() [2/3]

void ns3::WifiPhyRxTraceHelper::PrintStatistics ( Ptr< Node > node,
uint32_t deviceId = 0,
uint8_t linkId = 0 ) const

Prints statistics collected in the period for a specific node, device, and link.

Parameters
nodePtr to Node.
deviceIdDevice identifier (optional, defaults to 0).
linkIdLink identifier (optional, defaults to 0).

Definition at line 167 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink.

◆ PrintStatistics() [3/3]

void ns3::WifiPhyRxTraceHelper::PrintStatistics ( uint32_t nodeId,
uint32_t deviceId = 0,
uint8_t linkId = 0 ) const

Prints statistics collected in the period for a specific node, device, and link.

Parameters
nodeIdNode identifier.
deviceIdDevice identifier (optional, defaults to 0).
linkIdLink identifier (optional, defaults to 0).

Definition at line 173 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink.

◆ Reset()

void ns3::WifiPhyRxTraceHelper::Reset ( )

Resets the current statistics, clearing all counts and PPDU records.

Definition at line 206 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by TestWifiPhyRxTraceHelper::CheckAllStats(), TestWifiPhyRxTraceHelperMloStr::CheckAllStats(), and TestWifiPhyRxTraceHelperYans::CheckAllStats().

+ Here is the caller graph for this function:

◆ Start()

void ns3::WifiPhyRxTraceHelper::Start ( Time startTime)

Starts the collection of statistics from a specified start time.

Parameters
startTimeThe time to start collecting statistics.

Definition at line 179 of file wifi-phy-rx-trace-helper.cc.

References ns3::Time::As(), m_traceSink, NS_LOG_FUNCTION, ns3::Time::S, ns3::Simulator::Schedule(), and ns3::WifiPhyRxTraceSink::Start().

Referenced by TestWifiPhyRxTraceHelper::DoRun(), TestWifiPhyRxTraceHelperMloStr::DoRun(), and TestWifiPhyRxTraceHelperYans::DoRun().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Stop()

void ns3::WifiPhyRxTraceHelper::Stop ( Time stopTime)

Stops the collection of statistics at a specified time.

Parameters
stopTimeThe time to stop collecting statistics.

Definition at line 186 of file wifi-phy-rx-trace-helper.cc.

References m_traceSink, NS_LOG_FUNCTION, ns3::Time::S, ns3::Simulator::Schedule(), ns3::WifiPhyRxTraceSink::Stop(), and stopTime.

Referenced by TestWifiPhyRxTraceHelper::DoRun(), TestWifiPhyRxTraceHelperMloStr::DoRun(), and TestWifiPhyRxTraceHelperYans::DoRun().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ ::TestWifiPhyRxTraceHelper

friend class ::TestWifiPhyRxTraceHelper
friend

Definition at line 118 of file wifi-phy-rx-trace-helper.h.

◆ ::TestWifiPhyRxTraceHelperMloStr

friend class ::TestWifiPhyRxTraceHelperMloStr
friend

Definition at line 119 of file wifi-phy-rx-trace-helper.h.

◆ ::TestWifiPhyRxTraceHelperYans

friend class ::TestWifiPhyRxTraceHelperYans
friend

Definition at line 120 of file wifi-phy-rx-trace-helper.h.

Member Data Documentation

◆ m_traceSink

Ptr<WifiPhyRxTraceSink> ns3::WifiPhyRxTraceHelper::m_traceSink
private

The documentation for this class was generated from the following files: