A Discrete-Event Network Simulator

Design Documentation

ns-3 nodes can contain a collection of NetDevice objects, much like an actual computer contains separate interface cards for Ethernet, Wifi, Bluetooth, etc. This chapter describes the ns-3 WifiNetDevice and related models. By adding WifiNetDevice objects to ns-3 nodes, one can create models of 802.11-based infrastructure and ad hoc networks.

Overview of the model

The WifiNetDevice models a wireless network interface controller based on the IEEE 802.11 standard [ieee80211]. We will go into more detail below but in brief, ns-3 provides models for these aspects of 802.11:

  • basic 802.11 DCF with infrastructure and adhoc modes
  • 802.11a, 802.11b, 802.11g, 802.11n (both 2.4 and 5 GHz bands), 802.11ac and 802.11ax Draft 1.0 (both 2.4 and 5 GHz bands) physical layers
  • MSDU aggregation and MPDU aggregation extensions of 802.11n, and both can be combined together (two-level aggregation)
  • QoS-based EDCA and queueing extensions of 802.11e
  • the ability to use different propagation loss models and propagation delay models, please see the chapter on Propagation for more detail
  • various rate control algorithms including Aarf, Arf, Cara, Onoe, Rraa, ConstantRate, and Minstrel
  • 802.11s (mesh), described in another chapter
  • 802.11p and WAVE (vehicular), described in another chapter

The set of 802.11 models provided in ns-3 attempts to provide an accurate MAC-level implementation of the 802.11 specification and to provide a packet-level abstraction of the PHY-level for different PHYs, corresponding to 802.11a/b/e/g/n/ac/ax specifications.

In ns-3, nodes can have multiple WifiNetDevices on separate channels, and the WifiNetDevice can coexist with other device types. With the use of the SpectrumWifiPhy framework, one can also build scenarios involving cross-channel interference or multiple wireless technologies on a single channel.

The source code for the WifiNetDevice and its models lives in the directory src/wifi.

The implementation is modular and provides roughly three sublayers of models:

  • the PHY layer models
  • the so-called MAC low models: they model functions such as medium access (DCF and EDCA), RTS/CTS and ACK. In ns-3, the lower-level MAC is further subdivided into a MAC low and MAC middle sublayering, with channel access grouped into the MAC middle.
  • the so-called MAC high models: they implement non-time-critical processes in Wifi such as the MAC-level beacon generation, probing, and association state machines, and a set of Rate control algorithms. In the literature, this sublayer is sometimes called the upper MAC and consists of more software-oriented implementations vs. time-critical hardware implementations.

Next, we provide an design overview of each layer, shown in Figure WifiNetDevice architecture..


WifiNetDevice architecture.

MAC high models

There are presently three MAC high models that provide for the three (non-mesh; the mesh equivalent, which is a sibling of these with common parent ns3::RegularWifiMac, is not discussed here) Wi-Fi topological elements - Access Point (AP) (ns3::ApWifiMac), non-AP Station (STA) (ns3::StaWifiMac), and STA in an Independent Basic Service Set (IBSS - also commonly referred to as an ad hoc network (ns3::AdhocWifiMac).

The simplest of these is ns3::AdhocWifiMac, which implements a Wi-Fi MAC that does not perform any kind of beacon generation, probing, or association. The ns3::StaWifiMac class implements an active probing and association state machine that handles automatic re-association whenever too many beacons are missed. Finally, ns3::ApWifiMac implements an AP that generates periodic beacons, and that accepts every attempt to associate.

These three MAC high models share a common parent in ns3::RegularWifiMac, which exposes, among other MAC configuration, an attribute QosSupported that allows configuration of 802.11e/WMM-style QoS support, an attribute HtSupported that allows configuration of 802.11n High Throughput style support, an attribute VhtSupported that allows configuration of 802.11ac Very High Throughput style support and an attribute HeSupported that allows configuration of 802.11ax High Efficiency style support.

There are also several rate control algorithms that can be used by the MAC low layer. A complete list of available rate control algorithms is provided in a separate section.

MAC low layer

The MAC low layer is split into three main components:

  1. ns3::MacLow which takes care of RTS/CTS/DATA/ACK transactions.
  2. ns3::DcfManager and ns3::DcfState which implements the DCF and EDCAF functions.
  3. ns3::DcaTxop and ns3::EdcaTxopN which handle the packet queue, packet fragmentation, and packet retransmissions if they are needed. The ns3::DcaTxop object is used by high MACs that are not QoS-enabled, and for transmission of frames (e.g., of type Management) that the standard says should access the medium using the DCF. ns3::EdcaTxopN is is used by QoS-enabled high MACs and also performs 802.11n-style MSDU aggregation.

PHY layer models

In short, the physical layer models are mainly responsible for modeling the reception of packets and for tracking energy consumption. There are typically three main components to packet reception:

  • each packet received is probabilistically evaluated for successful or failed reception. The probability depends on the modulation, on the signal to noise (and interference) ratio for the packet, and on the state of the physical layer (e.g. reception is not possible while transmission or sleeping is taking place);
  • an object exists to track (bookkeeping) all received signals so that the correct interference power for each packet can be computed when a reception decision has to be made; and
  • one or more error models corresponding to the modulation and standard are used to look up probability of successful reception.

ns-3 offers users a choice between two physical layer models, with a base interface defined in the ns3::WifiPhy class. The YansWifiPhy class has been the only physical layer model until recently; the model implemented there is described in a paper entitled Yet Another Network Simulator The acronym Yans derives from this paper title. The SpectrumWifiPhy class is an alternative implementation based on the Spectrum framework used for other ns-3 wireless models. Spectrum allows a fine-grained frequency decomposition of the signal, and permits scenarios to include multiple technologies coexisting on the same channel.

Scope and Limitations

The IEEE 802.11 standard [ieee80211] is a large specification, and not all aspects are covered by ns-3; the documentation of ns-3‘s conformance by itself would lead to a very long document. This section attempts to summarize compliance with the standard and with behavior found in practice.

The physical layer and channel models operate on a per-packet basis, with no frequency-selective propagation or interference effects when using the default YansWifiPhy model. Directional antennas are also not supported at this time. For additive white Gaussian noise (AWGN) scenarios, or wideband interference scenarios, performance is governed by the application of analytical models (based on modulation and factors such as channel width) to the received signal-to-noise ratio, where noise combines the effect of thermal noise and of interference from other Wi-Fi packets. Moreover, interference from other technologies is not modeled. The following details pertain to the physical layer and channel models:

  • 802.11ax is still in draft phase, not all functionalities are implemented yet
  • 802.11ax does not contain any of the high-density improvement
  • 802.11ax MU-OFDMA is not supported
  • 802.11ax can only be used with Constant rate control algorithm
  • 802.11ax only supports SU PPDU format
  • 802.11ac/ax MU-MIMO is not supported, and no more than 4 antennas can be configured
  • 802.11n/ac/ax beamforming is not supported
  • 802.11 PCF and 802.11 HCF/HCCA are not implemented
  • Authentication and encryption are missing
  • Processing delays are not modeled
  • PLCP preamble reception is not modeled
  • PHY_RXSTART is not supported
  • The current implementation assumes that secondary channels are always higher than primary channels
  • Cases where RTS/CTS and ACK are transmitted using HT/VHT/HE formats are not supported
  • Energy consumption model does not consider MIMO

At the MAC layer, most of the main functions found in deployed Wi-Fi equipment for 802.11a/b/e/g/n/ac/ax are implemented, but there are scattered instances where some limitations in the models exist. Support for 802.11n and ac is evolving.

Some implementation choices that are not imposed by the standard are listed below:

  • BSSBasicRateSet for 802.11b has been assumed to be 1-2 Mbit/s
  • BSSBasicRateSet for 802.11a/g has been assumed to be 6-12-24 Mbit/s
  • The wifi manager always selects the lowest basic rate for management frames.

Design Details

The remainder of this section is devoted to more in-depth design descriptions of some of the Wi-Fi models. Users interested in skipping to the section on usage of the wifi module (User Documentation) may do so at this point. We organize these more detailed sections from the bottom-up, in terms of layering, by describing the channel and PHY models first, followed by the MAC models.

We focus first on the choice between physical layer frameworks. ns-3 contains support for a Wi-Fi-only physical layer model called YansWifiPhy that offers no frequency-level decomposition of the signal. For simulations that involve only Wi-Fi signals on the Wi-Fi channel, and that do not involve frequency-dependent propagation loss or fading models, the default YansWifiPhy framework is a suitable choice. For simulations involving mixed technologies on the same channel, or frequency dependent effects, the SpectrumWifiPhy is more appropriate. The two frameworks are very similarly configured.

The SpectrumWifiPhy framework uses the Spectrum channel framework, which is not documented herein but in the Spectrum module documentation.

The YansWifiChannel is the only concrete channel model class in the ns-3 wifi module. The ns3::YansWifiChannel implementation uses the propagation loss and delay models provided within the ns-3 Propagation module. In particular, a number of propagation models can be added (chained together, if multiple loss models are added) to the channel object, and a propagation delay model also added. Packets sent from a ns3::YansWifiPhy object onto the channel with a particular signal power, are copied to all of the other ns3::YansWifiPhy objects after the signal power is reduced due to the propagation loss model(s), and after a delay corresponding to transmission (serialization) delay and propagation delay due any channel propagation delay model (typically due to speed-of-light delay between the positions of the devices).

Only objects of ns3::YansWifiPhy may be attached to a ns3::YansWifiChannel; therefore, objects modeling other (interfering) technologies such as LTE are not allowed. Furthermore, packets from different channels do not interact; if a channel is logically configured for e.g. channels 5 and 6, the packets do not cause adjacent channel interference (even if their channel numbers overlap).

The MAC model

The 802.11 Distributed Coordination Function is used to calculate when to grant access to the transmission medium. While implementing the DCF would have been particularly easy if we had used a recurring timer that expired every slot, we chose to use the method described in [ji2004sslswn] where the backoff timer duration is lazily calculated whenever needed since it is claimed to have much better performance than the simpler recurring timer solution.

The backoff procedure of DCF is described in section of [ieee80211].

  • “The backoff procedure shall be invoked for a STA to transfer a frame when finding the medium busy as indicated by either the physical or virtual CS mechanism.”
  • “A backoff procedure shall be performed immediately after the end of every transmission with the More Fragments bit set to 0 of an MPDU of type Data, Management, or Control with subtype PS-Poll, even if no additional transmissions are currently queued.”

Thus, if the queue is empty, a newly arrived packet should be transmitted immediately after channel is sensed idle for DIFS. If queue is not empty and after a successful MPDU that has no more fragments, a node should also start the backoff timer.

Some users have observed that the 802.11 MAC with an empty queue on an idle channel will transmit the first frame arriving to the model immediately without waiting for DIFS or backoff, and wonder whether this is compliant. According to the standard, “The backoff procedure shall be invoked for a STA to transfer a frame when finding the medium busy as indicated by either the physical or virtual CS mechanism.” So in this case, the medium is not found to be busy in recent past and the station can transmit immediately.

The higher-level MAC functions are implemented in a set of other C++ classes and deal with:

  • packet fragmentation and defragmentation,
  • use of the RTS/CTS protocol,
  • rate control algorithm,
  • connection and disconnection to and from an Access Point,
  • the MAC transmission queue,
  • beacon generation,
  • MSDU aggregation,
  • etc.

Rate control algorithms

Multiple rate control algorithms are available in ns-3. Some rate control algorithms are modeled after real algorithms used in real devices; others are found in literature. The following rate control algorithms can be used by the MAC low layer:

Algorithms found in real devices:

  • ArfWifiManager (default for WifiHelper)
  • OnoeWifiManager
  • ConstantRateWifiManager
  • MinstrelWifiManager

Algorithms in literature:


The constant rate control algorithm always uses the same transmission mode for every packet. Users can set a desired ‘DataMode’ for all ‘unicast’ packets and ‘ControlMode’ for all ‘request’ control packets (e.g. RTS).

To specify different data mode for non-unicast packets, users must set the ‘NonUnicastMode’ attribute of the WifiRemoteStationManager. Otherwise, WifiRemoteStationManager will use a mode with the lowest rate for non-unicast packets.

The 802.11 standard is quite clear on the rules for selection of transmission parameters for control response frames (e.g. CTS and ACK). ns-3 follows the standard and selects the rate of control response frames from the set of basic rates or mandatory rates. This means that control response frames may be sent using different rate even though the ConstantRateWifiManager is used. The ControlMode attribute of the ConstantRateWifiManager is used for RTS frames only. The rate of CTS and ACK frames are selected according to the 802.11 standard. However, users can still manually add WifiMode to the basic rate set that will allow control response frames to be sent at other rates. Please consult the project wiki on how to do this.

Available attributes:

  • DataMode (default WifiMode::OfdmRate6Mbps): specify a mode for all non-unicast packets
  • ControlMode (default WifiMode::OfdmRate6Mbps): specify a mode for all ‘request’ control packets


The ideal rate control algorithm selects the best mode according to the SNR of the previous packet sent. Consider node A sending a unicast packet to node B. When B successfully receives the packet sent from A, B records the SNR of the received packet into a ns3::SnrTag and adds the tag to an ACK back to A. By doing this, A is able to learn the SNR of the packet sent to B using an out-of-band mechanism (thus the name ‘ideal’). A then uses the SNR to select a transmission mode based on a set of SNR thresholds, which was built from a target BER and mode-specific SNR/BER curves.

Available attribute:

  • BerThreshold (default 10e-6): The maximum Bit Error Rate that is used to calculate the SNR threshold for each mode.


The minstrel rate control algorithm is a rate control algorithm originated from madwifi project. It is currently the default rate control algorithm of the Linux kernel.

Minstrel keeps track of the probability of successfully sending a frame of each available rate. Minstrel then calculates the expected throughput by multiplying the probability with the rate. This approach is chosen to make sure that lower rates are not selected in favor of the higher rates (since lower rates are more likely to have higher probability).

In minstrel, roughly 10 percent of transmissions are sent at the so-called lookaround rate. The goal of the lookaround rate is to force minstrel to try higher rate than the currently used rate.

For a more detailed information about minstrel, see [linuxminstrel].

Modifying Wifi model

Modifying the default wifi model is one of the common tasks when performing research. We provide an overview of how to make changes to the default wifi model in this section. Depending on your goal, the common tasks are (in no particular order):

  • Creating or modifying the default Wi-Fi frames/headers by making changes to wifi-mac-header.*.
  • MAC low modification. For example, handling new/modified control frames (think RTS/CTS/ACK/Block ACK), making changes to two-way transaction/four-way transaction. Users usually make changes to mac-low.* to accomplish this. Handling of control frames is performed in MacLow::ReceiveOk.
  • MAC high modification. For example, handling new management frames (think beacon/probe), beacon/probe generation. Users usually make changes to regular-wifi-mac.*, sta-wifi-mac.*, ap-wifi-mac.*, or adhoc-wifi-mac.* to accomplish this.
  • Wi-Fi queue management. The files dca-txop.* and edca-txop-n.* are of interested for this task.
  • Channel access management. Users should modify the files dcf-manager.*, which grant access to DcaTxop and EdcaTxopN.
  • Fragmentation and RTS threholds are handled by Wi-Fi remote station manager. Note that Wi-Fi remote station manager simply indicates if fragmentation and RTS are needed. Fragmentation is handled by DcaTxop or EdcaTxopN while RTS/CTS transaction is hanled by MacLow.
  • Modifying or creating new rate control algorithms can be done by creating a new child class of Wi-Fi remote station manager or modifying the existing ones.