18.2 Using the WifiNetDevice

The modularity provided by the implementation makes low-level configuration of the WifiNetDevice powerful but complex. For this reason, we provide some helper classes to perform common operations in a simple matter, and leverage the ns-3 attribute system to allow users to control the parametrization of the underlying models.

Users who use the low-level ns-3 API and who wish to add a WifiNetDevice to their node must create an instance of a WifiNetDevice, plus a number of constituent objects, and bind them together appropriately (the WifiNetDevice is very modular in this regard, for future extensibility). At the low-level API, this can be done with about 20 lines of code (see ns3::WifiHelper::Install, and ns3::YansWifiPhyHelper::Create). They also must create, at some point, a WifiChannel, which also contains a number of constituent objects (see ns3::YansWifiChannelHelper::Create).

However, a few helpers are available for users to add these devices and channels with only a few lines of code, if they are willing to use defaults, and the helpers provide additional API to allow the passing of attribute values to change default values. The scripts in src/examples can be browsed to see how this is done.

18.2.1 YansWifiChannelHelper

The YansWifiChannelHelper has an unusual name. Readers may wonder why it is named this way. The reference is to the yans simulator, from which this model is taken. The helper can be used to create a WifiChannel with a default PropagationLoss and PropagationDelay model. Specifically, the default is a channel model with a propagation delay equal to a constant, the speed of light, and a propagation loss based on a log distance model with a reference loss of 46.6777 dB at reference distance of 1m.

Users will typically type code such as:

  YansWifiChannelHelper wifiChannelHelper = YansWifiChannelHelper::Default ();
  Ptr<WifiChannel> wifiChannel = wifiChannelHelper.Create ();

to get the defaults. Note the distinction above in creating a helper object vs. an actual simulation object. In ns-3, helper objects (used at the helper API only) are created on the stack (they could also be created with operator new and later deleted). However, the actual ns-3 objects typically inherit from class ns3::Object and are assigned to a smart pointer. See the chapter on Object model for a discussion of the ns-3 object model, if you are not familiar with it.

Todo: Add notes about how to configure attributes with this helper API

18.2.2 YansWifiPhyHelper

Physical devices (base class ns3::Phy) connect to ns3::Channel models in ns-3. We need to create Phy objects appropriate for the YansWifiChannel; here the YansWifiPhyHelper will do the work.

The YansWifiPhyHelper class configures an object factory to create instances of a YansWifiPhy and adds some other objects to it, including possibly a supplemental ErrorRateModel and a pointer to a MobilityModel. The user code is typically:

  YansWifiPhyHelper wifiPhyHelper = YansWifiPhyHelper::Default ();
  wifiPhyHelper.SetChannel (wifiChannel);

Note that we haven’t actually created any WifiPhy objects yet; we’ve just prepared the YansWifiPhyHelper by telling it which channel it is connected to. The phy objects are created in the next step.

18.2.3 NqosWifiMacHelper and QosWifiMacHelper

The ns3::NqosWifiMacHelper and ns3::QosWifiMacHelper configure an object factory to create instances of a ns3::WifiMac. They are used to configure MAC parameters like type of MAC, values of contention windows and so on. Setting up a non-QoS MAC layers the object we use is ns3::NqosWifiMacHelper. For example the following user code configures a non-QoS MAC sta and changes its default values for contention window and Aifsn:

  NqosWifiMacHelper wifiMacHelper = NqosWifiMacHelper::Default ();
  Ssid ssid = Ssid ("ns-3-ssid");
  wifiMacHelper.SetType ("ns3::NqstaWifiMac", "Ssid", SsidValue (ssid), 
"ActiveProbing", BooleanValue (false));
  wifiMacHelper.SetDcaParameters ("MinCw", UintegerValue (20), "Aifsn", 
UintegerValue (3));

Setting up a QoS MACs we use a ns3::QosWifiMacHelper instead. This object could be also used to change default EDCA parameters, and to set a possible MSDU aggregator for a particular access class in order to use 802.11n MSDU aggregation feature. A possible user code:

  QosWifiMacHelper wifiMacHelper = QosWifiMacHelper::Default ();
  wifiMacHelper.SetType ("ns3::QapWifiMac", 
    "Ssid", SsidValue (ssid), 
    "BeaconGeneration", BooleanValue (true), 
    "BeaconInterval", TimeValue (Seconds (2.5)));
  wifiMacHelper.SetMsduAggregatorForAc (AC_VO, "ns3::MsduStandardAggregator", 
    "MaxAmsduSize", UintegerValue (3839));

Call to QosWifiMacHelper::Default () is needed in order to set default EDCA parameters properly for all access classes; otherwise we should set them one by one.

18.2.4 WifiHelper

We’re now ready to create WifiNetDevices. First, let’s create a WifiHelper with default settings:

  WifiHelper wifiHelper = WifiHelper::Default ();

What does this do? It sets the RemoteStationManager to ns3::ArfWifiManager. Now, let’s use the wifiPhyHelper and wifiMacHelper created above to install WifiNetDevices on a set of nodes in a NodeContainer "c":

  NetDeviceContainer wifiContainer = WifiHelper::Install (wifiPhyHelper, wifiMacHelper, c);

This creates the WifiNetDevice which includes also a WifiRemoteStationManager, a WifiMac, and a WifiPhy (connected to the matching WifiChannel).

There are many ns-3 Attributes that can be set on the above helpers to deviate from the default behavior; the example scripts show how to do some of this reconfiguration.

18.2.5 AdHoc WifiNetDevice configuration

This is a typical example of how a user might configure an adhoc network.

18.2.6 Infrastructure (Access Point and clients) WifiNetDevice configuration

This is a typical example of how a user might configure an access point and a set of clients.

This document was generated by root on May 3, 2010 using texi2html 1.82.