1 @node Wifi NetDevice

     2 @chapter Wifi NetDevice

     3 @anchor{chap:wifi}

     4 

     5 ns-3 nodes can contain a collection of NetDevice objects, much like an actual 

     6 computer contains separate interface cards for Ethernet, Wifi, Bluetooth, etc.  This chapter describes the ns-3 WifiNetDevice and related models.  By

     7 adding WifiNetDevice objects to ns-3 nodes, one can create models of

     8 802.11-based infrastructure and ad hoc networks.

     9 

    10 @menu

    11 * Overview of the model::

    12 * Using the WifiNetDevice::

    13 * The WifiChannel and WifiPhy models::

    14 * The MAC model::

    15 * Wifi Attributes::

    16 * Wifi Tracing::

    17 @end menu

    18 

    19 @node Overview of the model

    20 @section Overview of the model

    21 

    22 @strong{Note:}  This overview is taken largely from the Doxygen for the

    23 WifiNetDevice module.

    24 

    25 The set of 802.11 models provided in ns-3 attempts to provide

    26 an accurate MAC-level implementation of the 802.11 specification

    27 and to provide a not-so-slow PHY-level model of the 802.11a

    28 specification.

    29 

    30 The current implementation provides roughly four levels of models:

    31 @itemize @bullet

    32 @item the @strong{PHY layer models}

    33 @item the so-called @strong{MAC low models}: they implement DCF

    34 @item the so-called @strong{MAC high models}: they implement the MAC-level

    35 beacon generation, probing, and association state machines, and

    36 @item a set of @strong{Rate control algorithms} used by the MAC low models

    37 @end itemize

    38 

    39 There are presently three @strong{MAC high models}:

    40 @enumerate

    41 @item a simple adhoc state machine that does not perform any

    42 kind of beacon generation, probing, or association. This

    43 state machine is implemented by the @code{ns3::AdhocWifiNetDevice}

    44 and @code{ns3::MacHighAdhoc} classes.

    45 @item  an active probing and association state machine that handles

    46 automatic re-association whenever too many beacons are missed

    47 is implemented by the @code{ns3::NqstaWifiNetDevice} and

    48 @code{ns3::MacHighNqsta} classes.

    49 @item an access point that generates periodic beacons, and that

    50 accepts every attempt to associate. This AP state machine

    51 is implemented by the @code{ns3::NqapWifiNetDevice} and

    52 @code{ns3::MacHighNqap} classes.

    53 @end enumerate 

    54 

    55 The @strong{MAC low layer} is split into three components:

    56 @enumerate

    57 @item @code{ns3::MacLow} which takes care of RTS/CTS/DATA/ACK transactions.

    58 @item @code{ns3::DcfManager} and @code{ns3::DcfState} which implements the DCF function.

    59 @item @code{ns3::DcaTxop} which handles the packet queue, packet fragmentation,

    60 and packet retransmissions if they are needed.

    61 @end enumerate

    62 

    63 There are also several @strong{rate control algorithms} that can be used by the Mac low layer:

    64 @itemize @bullet

    65 @item @code{ns3::ArfMacStations}

    66 @item @code{ns3::AArfMacStations}

    67 @item @code{ns3::IdealMacStations}

    68 @item @code{ns3::CrMacStations}

    69 @item @code{ns3::OnoeMacStations}

    70 @item @code{ns3::AmrrMacStations}

    71 @end itemize

    72 

    73 The PHY layer implements a single model in the 

    74 @code{ns3::WifiPhy class}: the

    75 physical layer model implemented there is described fully in a paper 

    76 entitled @uref{http://cutebugs.net/files/wns2-yans.pdf,,"Yet Another Network Simulator"}. 

    77 

    78 In ns-3, nodes can have multiple WifiNetDevices on separate channels,

    79 and the WifiNetDevice can coexist with other device types; this removes

    80 an architectural limitation found in ns-2.  Presently, however, there

    81 is no model for cross-channel interference or coupling.

    82 

    83 The source code for the Wifi NetDevice lives in the directory

    84 @code{src/devices/wifi}.

    85 

    86 @node Using the WifiNetDevice

    87 @section Using the WifiNetDevice

    88 

    89 Users who use the low-level ns-3 API and who wish to add a WifiNetDevice

    90 to their node must create an instance of a WifiNetDevice, plus 

    91 a number of consitutent objects, and bind them together appropriately

    92 (the WifiNetDevice is very modular in this regard, for future

    93 extensibility).  At the low-level API, this can be done

    94 with about 20 lines of code (see @code{ns3::WifiHelper::Install} and

    95 @code{ns3::YansWifiPhyHelper::Create}).  They also must create,

    96 at some point, a WifiChannel, which also contains a number of

    97 constituent objects (see @code{ns3::YansWifiChannelHelper::Create}).

    98 

    99 However, a few helpers are available for users to add these devices

   100 and channels with only a few lines of code, if they are willing to

   101 use defaults, and the helpers provide additional API to allow the

   102 passing of attribute values to change default values.  The scripts

   103 in @code{src/examples} can be browsed to see how this is done.

   104 

   105 @subsection YansWifiChannelHelper

   106 

   107 The YansWifiChannelHelper has an unusual name.  Readers may wonder why

   108 it is named this way.  The reference is to the 

   109 @uref{http://cutebugs.net/files/wns2-yans.pdf,,yans simulator},

   110 from which this model is taken.  The helper can be used to create

   111 a WifiChannel with a default PropagationLoss and PropagationDelay model.  

   112 Specifically, the default is a channel model

   113 with a propagation delay equal to a constant, the speed of light,

   114 and a propagation loss based on a log distance model with a reference 

   115 loss of 46.6777 dB at reference distance of 1m.

   116 

   117 Users will typically type code such as:

   118 @verbatim

   119   YansWifiChannelHelper wifiChannelHelper = YansWifiChannelHelper::Default ();

   120   Ptr<WifiChannel> wifiChannel = wifiChannelHelper.Create ();

   121 @end verbatim

   122 to get the defaults.  Note the distinction above in creating a helper

   123 object vs. an actual simulation object.

   124 In ns-3, helper objects (used at the helper API only) are created on the

   125 stack (they could also be created with operator new and later deleted).

   126 However, the actual ns-3 objects typically inherit from 

   127 @code{class ns3::Object} and are assigned to a smart pointer.  See the

   128 chapter on 

   129 @uref{Object model} for a discussion of the ns-3 object model, if you

   130 are not familiar with it.

   131 

   132 @emph{Todo:  Add notes about how to configure attributes with this helper API}

   133 

   134 @subsection YansWifiPhyHelper

   135 

   136 Physical devices (base class @code{ns3::Phy}) connect to 

   137 @code{ns3::Channel} models in ns-3.  We need to create Phy objects appropriate

   138 for the YansWifiChannel; here the @code{YansWifiPhyHelper} will

   139 do the work.

   140 

   141 The YansWifiPhyHelper class configures an object factory to create instances

   142 of a @code{YansWifiPhy} and

   143 adds some other objects to it, including possibly a supplemental 

   144 ErrorRateModel and a pointer to a MobilityModel.  The user code is

   145 typically:

   146 @verbatim

   147   YansWifiPhyHelper wifiPhyHelper = YansWifiPhyHelper::Default ();

   148   wifiPhyHelper.SetChannel (wifiChannel);

   149 @end verbatim

   150 Note that we haven't actually created any WifiPhy objects yet; we've 

   151 just prepared the YansWifiPhyHelper by telling it which channel it is 

   152 connected to.  The phy objects are created in the next step.

   153 

   154 @subsection WifiHelper

   155 

   156 We're now ready to create WifiNetDevices.  First, let's create

   157 a WifiHelper with default settings:

   158 @verbatim

   159   WifiHelper wifiHelper = WifiHelper::Default ();

   160 @end verbatim

   161 What does this do?  It sets the RemoteStationManager to

   162 @code{ns3::ArfWifiManager} and the upper MAC to @code{ns3::AdhocWifiMac}

   163 by default (which can be overridden by other arguments).

   164 Now, let's use the wifiPhyHelper created above to install WifiNetDevices

   165 on a set of nodes in a NodeContainer "c":

   166 @verbatim

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

   168 @end verbatim

   169 This creates the WifiNetDevice which includes also a WifiRemoteStationManager,

   170 a WifiMac, and a WifiPhy (connected to the matching WifiChannel).

   171 

   172 There are many ns-3 @uref{Attributes} that can be set on the above

   173 helpers to deviate from the default behavior; the example scripts

   174 show how to do some of this reconfiguration.

   175 

   176 @subsection AdHoc WifiNetDevice configuration 

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

   178 

   179 @emph{Write me}

   180 

   181 @subsection Infrastructure (Access Point and clients) WifiNetDevice configuration 

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

   183 

   184 @emph{Write me}

   185 

   186 @node The WifiChannel and WifiPhy models

   187 @section The WifiChannel and WifiPhy models

   188 

   189 The WifiChannel subclass can be used to connect together a set of

   190 @code{ns3::WifiNetDevice} network interfaces. The class @code{ns3::WifiPhy}

   191 is the

   192 object within the WifiNetDevice that receives bits from the channel.

   193 A WifiChannel contains

   194 a @code{ns3::PropagationLossModel} and a @code{ns3::PropagationDelayModel} 

   195 which can

   196 be overridden by the WifiChannel::SetPropagationLossModel

   197 and the WifiChannel::SetPropagationDelayModel methods. By default,

   198 no propagation models are set.

   199 

   200 The WifiPhy models an 802.11a channel, in terms of frequency, modulation,

   201 and bit rates, and interacts with the PropagationLossModel and 

   202 PropagationDelayModel found in the channel.  

   203 

   204 This section summarizes

   205 the description of the BER calculations found in the yans paper

   206 taking into account the

   207 Forward Error Correction present in 802.11a and describes

   208 the algorithm we implemented to decide whether or not a 

   209 packet can be successfully received.  See @uref{http://cutebugs.net/files/wns2-yans.pdf,,"Yet Another Network Simulator"} for more details.

   210 

   211 The PHY layer can be in one of three states:

   212 @enumerate

   213 @item TX: the PHY is currently transmitting a signal

   214 on behalf of its associated MAC

   215 @item RX: the PHY is synchronized on a signal and

   216 is waiting until it has received its last bit to forward

   217 it to the MAC.

   218 @item IDLE: the PHY is not in the TX or RX states.

   219 @end enumerate

   220 

   221 When the first bit of a new packet is received while

   222 the PHY is not IDLE (that is, it is already synchronized

   223 on the reception of another earlier packet or it is

   224 sending data itself), the received packet is dropped. 

   225 Otherwise, if the PHY is IDLE, we calculate the received

   226 energy of the first bit of this new signal and compare it 

   227 against our Energy Detection threshold (as defined 

   228 by the Clear Channel Assessment function mode 1). 

   229 If the energy of the packet k is higher, then the PHY moves 

   230 to RX state and schedules an event when the last bit of 

   231 the packet is expected to be received. Otherwise, the 

   232 PHY stays in IDLE state and drops the packet.

   233 

   234 The energy of the received signal is assumed

   235 to be zero outside of the reception interval of packet k and

   236 is calculated from the transmission power with a path-loss 

   237 propagation model in the reception interval.

   238 where the path loss exponent, @math{n}, is chosen equal to 3, 

   239 the reference distance, @math{d_0} is choosen equal to 

   240 @math{1.0m} and 

   241 the reference energy is based based on a Friis

   242 propagation model.

   243 

   244 When the last bit of the packet upon which the PHY is 

   245 synchronized is received, we need to calculate the 

   246 probability that the packet is received with any error

   247 to decide whether or not 

   248 the packet on which we were synchronized could

   249 be successfully received or not: a random number 

   250 is drawn from a uniform distribution and is compared against

   251 the probability of error.

   252 

   253 To evaluate the probability of error, we start from the piecewise linear 

   254 functions shown in Figure @ref{fig:snir} and calculate the 

   255 SNIR function. 

   256 

   257 @float Figure,fig:snir

   258 @caption{SNIR function over time}

   259 @image{figures/snir,,3in} 

   260 @end float 

   261 

   262 From the SNIR function we can derive bit error rates for BPSK and QAM

   263 modulations.  Then, for each interval l where BER is

   264 constant, we define the upper bound of a probability that an error is

   265 present in the chunk of bits located in the interval l for packet k.

   266 If we assume an AWGN channel, 

   267 binary convolutional coding (which is the case in 802.11a)

   268 and hard-decision Viterbi decoding, the error rate is thus derived,

   269 and the packet error probability for packet k can be computed.. 

   270 

   271 @subsection WifiChannel configuration

   272 

   273 WifiChannel models include both a PropagationDelayModel and a 

   274 PropagationLossModel.  The following PropagationDelayModels are available:

   275 @itemize @bullet

   276 @item ConstantSpeedPropagationDelayModel

   277 @item RandomPropagationDelayModel

   278 @end itemize

   279 

   280 The following PropagationLossModels are available:

   281 @itemize @bullet

   282 @item RandomPropagationLossModel

   283 @item FriisPropagationLossModel

   284 @item LogDistancePropagationLossModel

   285 @item JakesPropagationLossModel

   286 @item CompositePropagationLossModel

   287 @end itemize

   288 

   289 @node The MAC model

   290 @section The MAC model

   291 

   292 The 802.11 Distributed Coordination Function is used to

   293 calculate when to grant access to the transmission medium. While

   294 implementing the DCF would have been particularly easy if we

   295 had used a recurring timer that expired every slot, we

   296 chose to use the method described in @emph{(missing reference here from

   297 Yans paper)}

   298 where the backoff timer duration is lazily calculated whenever

   299 needed since it is claimed to have much better performance than

   300 the simpler recurring timer solution.

   301 

   302 The higher-level MAC functions are implemented in a set of other

   303 C++ classes and deal with:

   304 @itemize @bullet

   305 @item packet fragmentation and defragmentation,

   306 @item use of the rts/cts protocol,

   307 @item rate control algorithm,

   308 @item connection and disconnection to and from an Access Point,

   309 @item the MAC transmission queue,

   310 @item beacon generation,

   311 @item etc.

   312 @end itemize

   313 

   314 @node Wifi Attributes

   315 @section Wifi Attributes

   316 

   317 The WifiNetDevice makes heavy use of the ns-3 @ref{Attributes} subsystem for

   318 configuration and default value management.  Presently, approximately

   319 100 values are stored in this system.

   320 

   321 For instance, class @code{ns-3::WifiMac} exports these attributes:

   322 @itemize @bullet

   323 @item CtsTimeout: When this timeout expires, the RTS/CTS handshake has failed.

   324 @item AckTimeout: When this timeout expires, the DATA/ACK handshake has failed.

   325 @item Sifs: The value of the SIFS constant.

   326 @item EifsNoDifs: The value of EIFS-DIFS

   327 @item Slot: The duration of a Slot.

   328 @item Pifs: The value of the PIFS constant.

   329 @item MaxPropagationDelay: The maximum propagation delay. Unused for now.

   330 @item MaxMsduSize: The maximum size of an MSDU accepted by the MAC layer.This value conforms to the specification.

   331 @item Ssid: The ssid we want to belong to.

   332 @end itemize

   333 

   334 @node Wifi Tracing

   335 @section Wifi Tracing

   336 

   337 @emph{This needs revised/updating based on the latest Doxygen}

   338 

   339 ns-3 has a sophisticated tracing infrastructure that allows users to hook

   340 into existing trace sources, or to define and export new ones.  

   341 

   342 Wifi-related trace sources that are available by default include:

   343 @itemize @bullet

   344 @item @code{ns3::WifiNetDevice}

   345 @itemize @bullet

   346 @item Rx: Received payload from the MAC layer.

   347 @item Tx: Send payload to the MAC layer.

   348 @end itemize

   349 @item @code{ns3::WifiPhy}

   350 @itemize @bullet

   351 @item State: The WifiPhy state

   352 @item RxOk: A packet has been received successfully.

   353 @item RxError: A packet has been received unsuccessfully.

   354 @item Tx: Packet transmission is starting.

   355 @end itemize

   356 @end itemize

   357 Briefly, this means, for example, that a user can hook a processing 

   358 function to the "State" tracing hook above and be notified whenever the

   359 WifiPhy model changes state.