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_t >	MapMacAddressesToNodeIds (NodeContainer nodes) const
	Populates the mapping of MAC addresses to node IDs for a given set of nodes.

Private Attributes
Ptr< WifiPhyRxTraceSink >	m_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 127 of file wifi-phy-rx-trace-helper.h.

Constructor & Destructor Documentation

◆ WifiPhyRxTraceHelper()

ns3::WifiPhyRxTraceHelper::WifiPhyRxTraceHelper ( )

Constructor.

Definition at line 57 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

devices The NetDeviceContainer containing nodes to which traces are to be connected.

Definition at line 70 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

nodes The NodeContainer to which traces are to be connected.

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

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

Referenced by TestWifiPhyRxTraceHelper::DoSetup(), TestWifiPhyRxTraceHelperMloStr::DoSetup(), TestWifiPhyRxTraceHelperYans::DoSetup(), 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

nodes	The NodeContainer to which traces are to be connected.
MacToNodeMap	A mapping from MAC address to node ID.

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

References 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 204 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

nodeId	The ID of the node.
deviceId	The ID of the WifiNetDevice (optional, defaults to 0).
linkId	The ID of the link (optional, defaults to 0).

Returns: A reference to a vector of WifiPpduRxRecord instances.

Definition at line 211 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).