@c ========================================================================
@c Begin document body here
@c ========================================================================
@c ========================================================================
@c PART: Building Topologies
@c ========================================================================
@c The below chapters are under the major heading "Building Topologies"
@c This is similar to the Latex \part command
@c
@c ========================================================================
@c Building Topologies
@c ========================================================================
@node Building Topologies
@chapter Building Topologies
@menu
* Building a Bus Network Topology::
* Building a Wireless Network Topology::
@end menu
@c ========================================================================
@c Building a Bus Network Topology
@c ========================================================================
@node Building a Bus Network Topology
@section Building a Bus Network Topology
@cindex topology
@cindex bus network topology
In this section we are going to expand our mastery of @command{ns-3} network
devices and channels to cover an example of a bus network. @command{Ns-3}
provides a net device and channel we call CSMA (Carrier Sense Multiple Access).
The @command{ns-3} CSMA device models a simple network in the spirit of
Ethernet. A real Ethernet uses CSMA/CD (Carrier Sense Multiple Access with
Collision Detection) scheme with exponentially increasing backoff to contend
for the shared transmission medium. The @command{ns-3} CSMA device and
channel models only a subset of this.
Just as we have seen point-to-point topology helper objects when constructing
point-to-point topologies, we will see equivalent CSMA topology helpers in
this section. The appearance and operation of these helpers should look
quite familiar to you.
We provide an example script in our @code{examples} directory. This script
builds on the @code{first.cc} script and adds a CSMA network to the
point-to-point simulation we've already considered. Go ahead and open
@code{examples/second.cc} in your favorite editor. You will have already seen
enough @command{ns-3} code to understand most of what is going on in this
example, but we will go over the entire script and examine some of the output.
Just as in the @code{first.cc} example (and in all ns-3 examples) the file
begins with an emacs mode line and some GPL boilerplate.
One thing that can be surprisingly useful is a small bit of ASCII art that
shows a cartoon of the network topology constructed in the example. You will
find a similar ``drawing'' in most of our examples.
In this case, you can see that we are going to extend our point-to-point
example (the link between the nodes n0 and n1 below) by hanging a bus network
off of the right side. Notice that this is the default network topology
since you can actually vary the number of nodes created on the LAN. If you
set nCsma to one, there will be a total of two nodes on the LAN (CSMA
channel) --- one required node and one ``extra'' node. By default there are
three ``extra'' nodes as seen below:
@verbatim
// Default Network Topology
//
// 10.1.1.0
// n0 -------------- n1 n2 n3 n4
// point-to-point | | | |
// ================
// LAN 10.1.2.0
@end verbatim
The actual code begins by loading module include files just as was done in the
@code{first.cc} example. Then the ns-3 namespace is @code{used} and a logging
component is defined. This is all just as it was in @code{first.cc}, so there
is nothing new yet.
@verbatim
#include "ns3/core-module.h"
#include "ns3/simulator-module.h"
#include "ns3/node-module.h"
#include "ns3/helper-module.h"
#include "ns3/global-routing-module.h"
using namespace ns3;
NS_LOG_COMPONENT_DEFINE ("SecondScriptExample");
@end verbatim
The main program begins by enabling the @code{UdpEchoClientApplication} and
@code{UdpEchoServerApplication} logging components at @code{INFO} level so
we can see some output when we run the example. This should be entirely
familiar to you so far.
@verbatim
int
main (int argc, char *argv[])
{
LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);
@end verbatim
A fixed seed is provided to the random number generators so that they will
generate repeatable results.
@verbatim
RandomVariable::UseGlobalSeed (1, 1, 2, 3, 5, 8);
@end verbatim
Next, you will see some familiar code that will allow you to change the number
of devices on the CSMA network via command line argument. We did something
similar when we allowed the number of packets sent to be changed in the section
on command line arguments.
@verbatim
uint32_t nCsma = 3;
CommandLine cmd;
cmd.AddValue ("nCsma", "Number of \"extra\" CSMA nodes/devices", nCsma);
cmd.Parse (argc,argv);
@end verbatim
The next step is to create two nodes that we will connect via the
point-to-point link. The @code{NodeContainer} is used to do this just as was
done in @code{first.cc}.
@verbatim
NodeContainer p2pNodes;
p2pNodes.Create (2);
@end verbatim
Next, we delare another @code{NodeContainer} to hold the nodes that will be
part of the bus (CSMA) network. First, we just instantiate the container
object itself.
@verbatim
NodeContainer csmaNodes;
csmaNodes.Add (p2pNodes.Get (1));
csmaNodes.Create (nCsma);
@end verbatim
The next line of code @code{Gets} the first node (as in having an index of one)
from the point-to-point node container and adds it to the container of nodes
that will get CSMA devices. The node in question is going to end up with a
point-to-point device @emph{and} a CSMA device. We then create a number of
``extra'' nodes that compose the remainder of the CSMA network.
The next bit of code should be quite familiar by now. We instantiate a
@code{PointToPointHelper} and set the associated default attributes so that
we create a five megabit per second transmitter on devices created using the
helper and a two millisecond delay on channels created by the helper.
@verbatim
PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
NetDeviceContainer p2pDevices;
p2pDevices = pointToPoint.Install (p2pNodes);
@end verbatim
We then instantiate a @code{NetDeviceContainer} to keep track of the
point-to-point net devices and we @code{Install} devices on the
point-to-point nodes.
We mentioned above that you were going to see a helper for CSMA devices and
channels, and the next lines introduce them. The @code{CsmaHelper} works just
like a @code{PointToPointHelper}, but it creates and connects CSMA devices and
channels. In the case of a CSMA device and channel pair, notice that the data
rate is specified by a @em{channel} attribute instead of a device attribute.
This is because a real CSMA network does not allow one to mix, for example,
10Base-T and 100Base-T devices on a given channel. We first set the data rate
to 100 megabits per second, and then set the speed-of-light delay of the channel
to 6560 nano-seconds (arbitrarily chosen as 1 nanosecond per foot over a 100
meter segment). Notice that you can set an attribute using its native data
type.
@verbatim
CsmaHelper csma;
csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));
csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));
NetDeviceContainer csmaDevices;
csmaDevices = csma.Install (csmaNodes);
@end verbatim
Just as we created a @code{NetDeviceContainer} to hold the devices created by
the @code{PointToPointHelper} we create a @code{NetDeviceContainer} to hold
the devices created by our @code{CsmaHelper}. We call the @code{Install}
method of the @code{CsmaHelper} to install the devices into the nodes of the
@code{csmaNodes NodeContainer}.
We now have our nodes, devices and channels created, but we have no protocol
stacks present. Just as in the @code{first.cc} script, we will use the
@code{InternetStackHelper} to install these stacks.
@verbatim
InternetStackHelper stack;
stack.Install (p2pNodes.Get (0));
stack.Install (csmaNodes);
@end verbatim
Recall that we took one of the nodes from the @code{p2pNodes} container and
added it to the @code{csmaNodes} container. Thus we only need to install
the stacks on the remaining @code{p2pNodes} node, and all of the nodes in the
@code{csmaNodes} container to cover all of the nodes in the simulation.
Just as in the @code{first.cc} example script, we are going to use the
@code{Ipv4AddressHelper} to assign IP addresses to our device interfaces.
First we use the network 10.1.1.0 to create the two addresses needed for our
two point-to-point devices.
@verbatim
Ipv4AddressHelper address;
address.SetBase ("10.1.1.0", "255.255.255.0");
Ipv4InterfaceContainer p2pInterfaces;
p2pInterfaces = address.Assign (p2pDevices);
@end verbatim
Recall that we save the created interfaces in a container to make it easy to
pull out addressing information later for use in setting up the applications.
We now need to assign IP addresses to our CSMA device interfaces. The
operation works just as it did for the point-to-point case, except we now
are performing the operation on a container that has a variable number of
CSMA devices --- remember we made the number of CSMA devices changeable by
command line argument. The CSMA devices will be associated with IP addresses
from network number 10.1.2.0 in this case, as seen below.
@verbatim
address.SetBase ("10.1.2.0", "255.255.255.0");
Ipv4InterfaceContainer csmaInterfaces;
csmaInterfaces = address.Assign (csmaDevices);
@end verbatim
Now we have a topology built, but we need applications. This section is
going to be fundamentally similar to the applications section of
@code{first.cc} but we are going to instantiate the server on one of the
nodes that has a CSMA node and the client on the node having only a
point-to-point device.
First, we set up the echo server. We create a @code{UdpEchoServerHelper} and
provide a required attribute value to the constructor which is the server port
number. Recall that this port can be changed later using the
@code{SetAttribute} method if desired, but we require it to be provided to
the constructor.
@verbatim
UdpEchoServerHelper echoServer (9);
ApplicationContainer serverApps = echoServer.Install (csmaNodes.Get (nCsma));
serverApps.Start (Seconds (1.0));
serverApps.Stop (Seconds (10.0));
@end verbatim
Recall that the @code{csmaNodes NodeContainer} contains one of the
nodes created for the point-to-point network and @code{nCsma} ``extra'' nodes.
What we want to get at is the last of the ``extra'' nodes. The zeroth entry of
the @code{csmaNodes} container will the the point-to-point node. The easy
way to think of this, then, is if we create one ``extra'' CSMA node, then it
will be be at index one of the @code{csmaNodes} container. By induction,
if we create @code{nCsma} ``extra'' nodes the last one will be at index
@code{nCsma}. You see this exhibited in the @code{Get} of the first line of
code.
The client application is set up exactly as we did in the @code{first.cc}
example script. Again, we provide required attributes to the
@code{UdpEchoClientHelper} in the constructor (in this case the remote address
and port). We tell the client to send packets to the server we just installed
on the last of the ``extra'' CSMA nodes. We install the client on the
leftmost point-to-point node seen in the topology illustration.
@verbatim
UdpEchoClientHelper echoClient (csmaInterfaces.GetAddress (nCsma), 9);
echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.)));
echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
ApplicationContainer clientApps = echoClient.Install (p2pNodes.Get (0));
clientApps.Start (Seconds (2.0));
clientApps.Stop (Seconds (10.0));
@end verbatim
Since we have actually built an internetwork here, we need some form of
internetwork routing. @command{Ns-3} provides what we call a global route
manager to set up the routing tables on nodes. This route manager has a
global function that runs though the nodes created for the simulation and does
the hard work of setting up routing for you.
Basically, what happens is that each node behaves as if it were an OSPF router
that communicates instantly and magically with all other routers behind the
scenes. Each node generates link advertisements and communicates them
directly to a global route manager which uses this global information to
construct the routing tables for each node. Setting up this form of routing
is a one-liner:
@verbatim
GlobalRouteManager::PopulateRoutingTables ();
@end verbatim
The remainder of the script should be very familiar to you. We just enable
pcap tracing, run the simulation and exit the script. Notice that enabling
pcap tracing using the CSMA helper is done in the same way as for the pcap
tracing with the point-to-point helper.
@verbatim
PointToPointHelper::EnablePcapAll ("second");
CsmaHelper::EnablePcapAll ("second");
Simulator::Run ();
Simulator::Destroy ();
return 0;
}
@end verbatim
In order to run this example, you have to copy the @code{second.cc} example
script into the scratch directory and use Waf to build just as you did with
the @code{first.cc} example. If you are in the top-level directory of the
repository you would type,
@verbatim
cp examples/second.cc scratch/
./waf
./waf --run scratch/second
@end verbatim
Since we have set up the UDP echo applications to log just as we did in
@code{first.cc}, you will see similar output when you run the script.
@verbatim
~/repos/ns-3-dev > ./waf --run scratch/second
Entering directory `/home/craigdo/repos/ns-3-dev/build'
Compilation finished successfully
Sent 1024 bytes to 10.1.2.4
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.2.4
~/repos/ns-3-dev >
@end verbatim
Recall that the first message, @code{Sent 1024 bytes to 10.1.2.4} is the
UDP echo client sending a packet to the server. In this case, the server
is on a different network (10.1.2.0). The second message, @code{Received 1024
bytes from 10.1.1.1}, is from the UDP echo server, generated when it receives
the echo packet. The final message, @code{Received 1024 bytes from 10.1.2.4}
is from the echo client, indicating that it has received its echo back from
the server.
If you now go and look in the top level directory, you will find a number of
trace files:
@verbatim
~/repos/ns-3-dev > ls *.pcap
second-0-0.pcap second-1-1.pcap second-3-0.pcap
second-1-0.pcap second-2-0.pcap second-4-0.pcap
~/repos/ns-3-dev >
@end verbatim
Let's take a moment to look at the naming of these files. They all have the
same form, @code{<name>-<node>-<device>.pcap}. For example, the first file
in the listing is @code{second-0-0.pcap} which is the pcap trace from node
zero - device zero. There are no other devices on node zero so this is the
only trace from that node.
Now look at @code{second-1-0.pcap} and @code{second-1-1.pcap}. The former is
the pcap trace for device zero on node one and the latter is the trace file
for device one on node one. If you refer back to the topology illustrration at
the start of the section, you will see that node one is the node that has
both a point-to-point device and a CSMA device, so we should expect two pcap
traces for that node.
Now, let's follow the echo packet through the internetwork. First, do a
tcpdump of the trace file for the leftmost point-to-point node --- node zero.
@verbatim
~/repos/ns-3-dev > tcpdump -r second-0-0.pcap -nn -tt
reading from file second-0-0.pcap, link-type PPP (PPP)
2.000000 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
2.007382 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024
~/repos/ns-3-dev >
@end verbatim
The first line of the dump indicates that the link type is PPP (point-to-point)
which we expect. You then see the echo packet leaving node zero via the
device associated with IP address 10.1.1.1 headed for IP address
10.1.2.4 (the rightmost CSMA node). This packet will move over the
point-to-point link and be received by the point-to-point net device on node
one. Let's take a look:
@verbatim
~/repos/ns-3-dev > tcpdump -r second-1-0.pcap -nn -tt
reading from file second-1-0.pcap, link-type PPP (PPP)
2.003686 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
2.003695 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024
~/repos/ns-3-dev >
@end verbatim
Here we see that the link type is also PPP as we would expect. You see the
packet from IP address 10.1.1.1 headed toward 10.1.2.4 appear on this
interface. Now, internally to this node, the packet will be forwarded to the
CSMA interface and we should see it pop out the other device headed for its
ultimate destination. Let's then look at second-1-1.pcap and see if its there.
@verbatim
~/repos/ns-3-dev > tcpdump -r second-1-1.pcap -nn -tt
reading from file second-1-1.pcap, link-type EN10MB (Ethernet)
2.003686 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
2.003687 arp reply 10.1.2.4 is-at 00:00:00:00:00:06
2.003687 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
2.003691 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4
2.003691 arp reply 10.1.2.1 is-at 00:00:00:00:00:03
2.003695 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024
~/repos/ns-3-dev >
@end verbatim
As you can see, the link type is now ``Ethernet.'' Something new has appeared,
though. The bus network needs @code{ARP}, the Address Resolution Protocol.
The node knows it needs to send the packet to IP address 10.1.2.4, but it
doesn't know the MAC address of the corresponding node. It broadcasts on the
CSMA network (ff:ff:ff:ff:ff:ff) asking for the device that has IP address
10.1.2.4. In this case, the rightmost node replies saying it is at MAC address
00:00:00:00:00:06. This exchange is seen in the following lines,
@verbatim
2.003686 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
2.003687 arp reply 10.1.2.4 is-at 00:00:00:00:00:06
@end verbatim
Then node one, device one goes ahead and sends the echo packet to the UDP echo
server at IP address 10.1.2.4. We can now look at the pcap trace for the
echo server,
@verbatim
~/repos/ns-3-dev > tcpdump -r second-4-0.pcap -nn -tt
reading from file second-4-0.pcap, link-type EN10MB (Ethernet)
2.003686 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
2.003686 arp reply 10.1.2.4 is-at 00:00:00:00:00:06
2.003690 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
2.003690 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4
2.003692 arp reply 10.1.2.1 is-at 00:00:00:00:00:03
2.003692 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024
~/repos/ns-3-dev >
@end verbatim
Again, you see that the link type is ``Ethernet.'' The first two entries are
the ARP exchange we just explained. The third packet is the echo packet
being delivered to its final destination.
The echo server turns the packet around and needs to send it back to the echo
client on 10.1.1.1 but it knows that this address is on another network that
it reaches via IP address 10.1.2.1. This is because we initialized global
routing and it has figured all of this out for us. But, the echo server node
doesn't know the MAC address of the first CSMA node, so it has to ARP for it
just like the first CSMA node had to do. We leave it as an exercise for you
to find the entries corresponding to the packet returning back on its way to
the client (we have already dumped the traces and you can find them in those
tcpdumps above.
Let's take a look at one of the CSMA nodes that wasn't involved in the packet
exchange:
@verbatim
~/repos/ns-3-dev > tcpdump -r second-2-0.pcap -nn -tt
reading from file second-2-0.pcap, link-type EN10MB (Ethernet)
2.003686 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
2.003691 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4
~/repos/ns-3-dev >
@end verbatim
You can see that the CSMA channel is a broadcast medium and so all of the
devices see the ARP requests involved in the packet exchange. The remaining
pcap trace will be identical to this one.
Finally, recall that we added the ability to control the number of CSMA devices
in the simulation by command line argument. You can change this argument in
the same way as when we looked at changing the number of packets echoed in the
@code{first.cc} example. Try setting the number of ``extra'' devices to four:
@verbatim
~/repos/ns-3-dev > ./waf --run "scratch/second --nCsma=4"
Entering directory `/home/craigdo/repos/ns-3-dev/build'
Compilation finished successfully
Sent 1024 bytes to 10.1.2.5
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.2.5
~/repos/ns-3-dev >
@end verbatim
Notice that the echo server has now been relocated to the last of the CSMA
nodes, which is 10.1.2.5 instead of the default case, 10.1.2.4. You can
increase the number to your hearts content, but remember that you will get a
pcap trace file for every node in the simulation. One thing you can do to
keep from getting all of those pcap traces with nothing but ARP exchanges in
them is to be more specific about which nodes and devices you want to trace.
Let's take a look at @code{scratch/second.cc} and add that code enabling us
to be more specific. The file we provided used the @code{EnablePcapAll}
methods of the helpers to enable pcap on all devices. We now want to use the
more specific method, @code{EnablePcap}, which takes a node number and device
number as parameters. Go ahead and replace the @code{EnablePcapAll} calls
with the calls below.
@verbatim
PointToPointHelper::EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
CsmaHelper::EnablePcap ("second", csmaNodes.Get (nCsma)->GetId (), 0);
@end verbatim
We know that we want to create a pcap file with the base name "second" and
we also know that the device of interest in both cases is going to be zero,
so those parameters are not really interesting. In order to get the node
number, you have two choices: first, nodes are numbered in a monotonically
increasing fashion starting from zero in the order in which you created them.
One way to get a node number is to figure this number out ``manually'' by
contemplating the order of node creation. If you take a look at the network
topology illustration at the beginning of the file, we did this for you and
you can see that the last CSMA node is going to be node number
@code{nCsma + 1}. This approach can become annoyingly difficult in larger
simulations.
An alternate way, which we use here, is to realize that the
@code{NodeContainers} contain pointers to @command{ns-3} @code{Node} Objects.
The @code{Node} Object has a method called @code{GetId} which will return that
node's ID, which is the node number we seek. Let's go take a look at the
Doxygen for the @code{Node} and locate that method, which is further down in
the @command{ns-3} core code than we've seen so far; but sometimes you have to
search diligently for useful things.
Go to the Doxygen documentation for your release (recall that you can find it
on the project web site). You can get to the @code{Node} documentation by
looking through at the ``Classes'' tab and scrolling down the ``Class List''
until you find @code{ns3::Node}. Select @code{ns3::Node} and you will be taken
to the documentation for the @code{Node} class. If you now scroll down to the
@code{GetId} method and select it, you will be taken to the detailed
documentation for the method. Using the @code{GetId} method can make
determining node numbers much easier in complex topologies.
Now that we have got some trace filtering in place, it is reasonable to start
increasing the number of CSMA devices in our simulation. If you build the
new script and run the simulation setting @code{nCsma} to 100, you will see
the following output:
@verbatim
~/repos/ns-3-dev > ./waf --run "scratch/second --nCsma=100"
Entering directory `/home/craigdo/repos/ns-3-dev/build'
Compilation finished successfully
Sent 1024 bytes to 10.1.2.101
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.2.101
~/repos/ns-3-dev >
@end verbatim
Note that the echo server is now located at 10.1.2.101 which corresponds to
having 100 ``extra'' CSMA nodes with the echo server on the last one. If you
list the pcap files in the top level directory,
@verbatim
~/repos/ns-3-dev > ls *.pcap
second-0-0.pcap second-101-0.pcap
~/repos/ns-3-dev >
@end verbatim
you will see that we have, in fact, only created two trace files. The trace
file @code{second-0-0.pcap} is the ``leftmost'' point-to-point device which is
the echo packet source. The file @code{second-101-0.pcap} corresponds to the
rightmost CSMA device which is where the echo server resides.
@c ========================================================================
@c Building a Wireless Network Topology
@c ========================================================================
@node Building a Wireless Network Topology
@section Building a Wireless Network Topology
@cindex topology
@cindex wireless network topology
In this section we are going to further expand our knowledge of @command{ns-3}
network devices and channels to cover an example of a wireless network.
@command{Ns-3} provides a set of 802.11 models that attempt to provide an
accurate MAC-level implementation of the 802.11 specification and a
``not-so-slow'' PHY-level model of the 802.11a specification.
Just as we have seen both point-to-point and CSMA topology helper objects when
constructing point-to-point topologies, we will see equivalent @code{Wifi}
topology helpers in this section. The appearance and operation of these
helpers should look quite familiar to you.
We provide an example script in our @code{examples} directory. This script
builds on the @code{second.cc} script and adds a Wifi network. Go ahead and
open @code{examples/third.cc} in your favorite editor. You will have already
seen enough @command{ns-3} code to understand most of what is going on in
this example, but there are a few new things, so we will go over the entire
script and examine some of the output.
Just as in the @code{second.cc} example (and in all @command{ns-3} examples)
the file begins with an emacs mode line and some GPL boilerplate.
Take a look at the ASCII art (reproduced below) that shows the default network
topology constructed in the example. You can see that we are going to
further extend our example by hanging a wireless network off of the left side.
Notice that this is a default network topology since you can actually vary the
number of nodes created on the wired and wireless networks. Just as in the
@code{second.cc} script case, if you change @code{nCsma}, it will give you a
number of ``extra'' CSMA nodes. Similarly, you can set @code{nWifi} to
control how many @code{STA} (station) nodes are created in the simulation.
There will always be one @code{AP} (access point) node on the wireless
network. By default there are three ``extra'' CSMA nodes and three wireless
@code{STA} nodes.
The code begins by loading module include files just as was done in the
@code{second.cc} example. There are a couple of new includes corresponding
to the Wifi module and the mobility module which we will discuss below.
@verbatim
#include "ns3/core-module.h"
#include "ns3/simulator-module.h"
#include "ns3/node-module.h"
#include "ns3/helper-module.h"
#include "ns3/global-routing-module.h"
#include "ns3/wifi-module.h"
#include "ns3/mobility-module.h"
@end verbatim
The network topology illustration follows:
@verbatim
// Default Network Topology
//
// Wifi 10.1.3.0
// AP
// * * * *
// | | | | 10.1.1.0
// n5 n6 n7 n0 -------------- n1 n2 n3 n4
// point-to-point | | | |
// ================
// LAN 10.1.2.0
@end verbatim
You can see that we are adding a new network device to the node on the left
side of the point-to-point link that becomes the access point for the wireless
network. A number of wireless STA nodes are created to fill out the new
10.1.3.0 network as shown on the left side of the illustration.
After the illustration, the @code{ns-3} namespace is @code{used} and a logging
component is defined. This should all be quite familiar by now.
@verbatim
using namespace ns3;
NS_LOG_COMPONENT_DEFINE ("ThirdScriptExample");
@end verbatim
As has become the norm in this tutorial, the main program begins by enabling
the @code{UdpEchoClientApplication} and @code{UdpEchoServerApplication}
logging components at @code{INFO} level so we can see some output when we run
the simulation.
@verbatim
int
main (int argc, char *argv[])
{
LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);
@end verbatim
A fixed seed is provided to the random number generators so that they will
generate repeatable results.
@verbatim
RandomVariable::UseGlobalSeed (1, 1, 2, 3, 5, 8);
@end verbatim
Next, you will see more familiar code that will allow you to change the number
of devices on the CSMA and Wifi networks via command line argument.
@verbatim
uint32_t nCsma = 3;
uint32_t nWifi = 3;
CommandLine cmd;
cmd.AddValue ("nCsma", "Number of \"extra\" CSMA nodes/devices", nCsma);
cmd.AddValue ("nWifi", "Number of wifi STA devices", nWifi);
cmd.Parse (argc,argv);
@end verbatim
Just as in all of the previous examples, the next step is to create two nodes
that we will connect via the point-to-point link.
@verbatim
NodeContainer p2pNodes;
p2pNodes.Create (2);
@end verbatim
Next, we see an old friend. We instantiate a @code{PointToPointHelper} and
set the associated default attributes so that we create a five megabit per
second transmitter on devices created using the helper and a two millisecond
delay on channels created by the helper. We then @code{Intall} the devices
on the nodes and the channel between them.
@verbatim
PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
NetDeviceContainer p2pDevices;
p2pDevices = pointToPoint.Install (p2pNodes);
@end verbatim
Next, we delare another @code{NodeContainer} to hold the nodes that will be
part of the bus (CSMA) network.
@verbatim
NodeContainer csmaNodes;
csmaNodes.Add (p2pNodes.Get (1));
csmaNodes.Create (nCsma);
@end verbatim
The next line of code @code{Gets} the first node (as in having an index of one)
from the point-to-point node container and adds it to the container of nodes
that will get CSMA devices. The node in question is going to end up with a
point-to-point device and a CSMA device. We then create a number of ``extra''
nodes that compose the remainder of the CSMA network.
We then instantiate a @code{CsmaHelper} and set its attributes as we did in
the previous example. We create a @code{NetDeviceContainer} to keep track of
the created CSMA net devices and then we @code{Install} CSMA devices on the
selected nodes.
@verbatim
CsmaHelper csma;
csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));
csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));
NetDeviceContainer csmaDevices;
csmaDevices = csma.Install (csmaNodes);
@end verbatim
Next, we are going to create the nodes that will be part of the Wifi network.
We are going to create a number of ``station'' nodes as specified by the
command line argument, and we are going to use the ``leftmost'' node of the
point-to-point link as the node for the access point.
@verbatim
NodeContainer wifiStaNodes;
wifiStaNodes.Create (nWifi);
NodeContainer wifiApNode = p2pNodes.Get (0);
@end verbatim
The next bit of code constructs the wifi devices and the interconnection
channel between these wifi nodes. First, we configure the PHY and channel
helpers:
@verbatim
YansWifiChannelHelper channel = YansWifiChannelHelper::Default ();
YansWifiPhyHelper phy = YansWifiPhyHelper::Default ();
@end verbatim
For simplicity, this code uses the default PHY layer configuration and
channel models which are documented in the API doxygen documentation for
the @code{YansWifiChannelHelper::Default} and @code{YAnsWifiPhyHelper::Default}
methods. Once these objects are created, we create a channel object
and associate it to our PHY layer object manager to make sure
that all the PHY objects created layer by the @code{YansWifiPhyHelper}
all share the same underlying channel, that is, they share the same
wireless medium and can communication and interfere:
@verbatim
phy.SetChannel (channel.Create ());
@end verbatim
Once the PHY helper is configured, we can focus on the MAC layer:
@verbatim
WifiHelper wifi = WifiHelper::Default ();
wifi.SetRemoteStationManager ("ns3::AarfWifiManager");
@end verbatim
The @code{SetRemoteStationManager} method tells the helper the type of
rate control algorithm to use. Here, it is asking the helper to use the AARF
algorithm --- details are, of course, available in Doxygen.
Next, we configure the SSID of the infrastructure network we want to setup
and make sure that our stations don't perform active probing:
@verbatim
Ssid ssid = Ssid ("ns-3-ssid");
wifi.SetMac ("ns3::NqstaWifiMac",
"Ssid", SsidValue (ssid),
"ActiveProbing", BooleanValue (false));
@end verbatim
This code first creates an 802.11 service set identifier (SSID) object that
will be used to set the value of the ``Ssid'' @code{Attribute} of the MAC
layer implementation. The particular kind of MAC layer is specified by
@code{Attribute} as being of the "ns3::NqstaWifiMac" type. This means that
the MAC will use a ``non-QoS station'' (nqsta) state machine. Finally, the
``ActiveProbing'' attribute is set to false. This means that probe requests
will not be sent by MACs created by this helper.
Once all the station-specific parameters are fully configured, both at the
MAC and PHY layers, we can invoke our now-familiar @code{Install} method to
create the wifi devices of these stations:
@verbatim
NetDeviceContainer staDevices;
staDevices = wifi.Install (phy, wifiStaNodes);
@end verbatim
We have configured Wifi for all of our STA nodes, and now we need to
configure the AP (access point) node. We begin this process by changing
the default @code{Attributes} of the @code{WifiHelper} to reflect the
requirements of the AP.
@verbatim
wifi.SetMac ("ns3::NqapWifiMac",
"Ssid", SsidValue (ssid),
"BeaconGeneration", BooleanValue (true),
"BeaconInterval", TimeValue (Seconds (2.5)));
@end verbatim
In this case, the @code{WifiHelper} is going to create MAC layers of the
``ns3::NqapWifiMac'' (Non-Qos Access Point) type. We set the
``BeaconGeneration'' attribute to true and also set an interval between
beacons of 2.5 seconds.
The next lines create the single AP which shares the same set of PHY-level
attributes (and channel) as the stations:
@verbatim
NetDeviceContainer apDevices;
apDevices = wifi.Install (phy, wifiApNode);
@end verbatim
Now, we are going to add mobility models. We want the STA nodes to be mobile,
wandering around inside a bounding box, and we want to make the AP node
stationary. We use the @code{MobilityHelper} to make this easy for us.
First, we instantiate a @code{MobilityHelper} obejct and set some attributes
controlling the ``position allocator'' functionality.
@verbatim
MobilityHelper mobility;
mobility.SetPositionAllocator ("ns3::GridPositionAllocator",
"MinX", DoubleValue (0.0),
"MinY", DoubleValue (0.0),
"DeltaX", DoubleValue (5.0),
"DeltaY", DoubleValue (10.0),
"GridWidth", UintegerValue (3),
"LayoutType", StringValue ("RowFirst"));
@end verbatim
This code tells the mobility helper to use a two-dimensional grid to initially
place the STA nodes. Feel free to explore the Doxygen for class
@code{ns3::GridPositionAllocator} to see exactly what is being done.
We have aranged our nodes on an initial grid, but now we need to tell them
how to move. We choose the @code{RandomWalk2dMobilityModel} which has the
nodes move in a random direction at a random speed around inside a bounding
box.
@verbatim
mobility.SetMobilityModel ("ns3::RandomWalk2dMobilityModel",
"Bounds", RectangleValue (Rectangle (-50, 50, -50, 50)));
@end verbatim
We now tell the @code{MobilityHelper} to install the mobility models on the
STA nodes.
@verbatim
mobility.Install (wifiStaNodes);
@end verbatim
We want the access point to remain in a fixed position during the simulation.
We accomplish this by setting the mobility model for this node to be the
@code{ns3::StaticMobilityModel}:
@verbatim
mobility.SetMobilityModel ("ns3::StaticMobilityModel");
mobility.Install (wifiApNode);
@end verbatim
We now have our nodes, devices and channels created, and mobility models
chosen for the Wifi nodes, but we have no protocol stacks present. Just as
we have done previously many times, we will use the @code{InternetStackHelper}
to install these stacks.
@verbatim
InternetStackHelper stack;
stack.Install (csmaNodes);
stack.Install (wifiApNode);
stack.Install (wifiStaNodes);
@end verbatim
Just as in the @code{second.cc} example script, we are going to use the
@code{Ipv4AddressHelper} to assign IP addresses to our device interfaces.
First we use the network 10.1.1.0 to create the two addresses needed for our
two point-to-point devices. Then we use network 10.1.2.0 to assign addresses
the the CSMA network and then we assign addresses from network 10.1.3.0 to
both the STA devices and the AP on the wireless network.
@verbatim
Ipv4AddressHelper address;
address.SetBase ("10.1.1.0", "255.255.255.0");
Ipv4InterfaceContainer p2pInterfaces;
p2pInterfaces = address.Assign (p2pDevices);
address.SetBase ("10.1.2.0", "255.255.255.0");
Ipv4InterfaceContainer csmaInterfaces;
csmaInterfaces = address.Assign (csmaDevices);
address.SetBase ("10.1.3.0", "255.255.255.0");
address.Assign (staDevices);
address.Assign (apDevices);
@end verbatim
We put the echo server on the ``rightmost'' node in the illustration at the
start of the file. We have done this before.
@verbatim
UdpEchoServerHelper echoServer (9);
ApplicationContainer serverApps = echoServer.Install (csmaNodes.Get (nCsma));
serverApps.Start (Seconds (1.0));
serverApps.Stop (Seconds (10.0));
@end verbatim
And we put the echo client on the last STA node we created, pointing it to
the server on the CSMA network. We have also seen similar operations before.
@verbatim
UdpEchoClientHelper echoClient (csmaInterfaces.GetAddress (nCsma), 9);
echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.)));
echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
ApplicationContainer clientApps =
echoClient.Install (wifiStaNodes.Get (nWifi - 1));
clientApps.Start (Seconds (2.0));
clientApps.Stop (Seconds (10.0));
@end verbatim
Since we have built an internetwork here, we need enable internetwork routing
just as we did in the @code{second.cc} example script.
@verbatim
GlobalRouteManager::PopulateRoutingTables ();
@end verbatim
One thing that can surprise some users is the fact that the simulation we just
created will never ``naturally'' stop. This is because we asked the wireless
access point to generate beacons. It will generate beacons forever, so we must
tell the simulator to stop even though it may have beacon generation events
scheduled. The following line of code tells the simulator to stop so that
we don't simulate beacons forever and enter what is essentially an endless
loop.
@verbatim
Simulator::Stop (Seconds (10.0));
@end verbatim
We use the same trick as in the @code{second.cc} script to only generate
pcap traces from the nodes we find interesting. Note that we use the same
``formula'' to get pcap tracing enabled on Wifi devices as we did on the
CSMA and point-to-point devices.
@verbatim
WifiHelper::EnablePcap ("third",
wifiStaNodes.Get (nWifi - 1)->GetId (), 0);
CsmaHelper::EnablePcap ("third",
csmaNodes.Get (nCsma)->GetId (), 0);
@end verbatim
Finally, we actually run the simulation, clean up and then exit the program.
@verbatim
Simulator::Run ();
Simulator::Destroy ();
return 0;
}
@end verbatim
In order to run this example, you have to copy the @code{third.cc} example
script into the scratch directory and use Waf to build just as you did with
the @code{second.cc} example. If you are in the top-level directory of the
repository you would type,
@verbatim
cp examples/third.cc scratch/
./waf
./waf --run scratch/third
@end verbatim
Since we have set up the UDP echo applications just as we did in the
@code{second.cc} script, you will see similar output.
@verbatim
~/repos/ns-3-dev > ./waf --run scratch/third
Entering directory `/home/craigdo/repos/ns-3-dev/build'
Compilation finished successfully
Sent 1024 bytes to 10.1.2.4
Received 1024 bytes from 10.1.3.3
Received 1024 bytes from 10.1.2.4
~/repos/ns-3-dev >
@end verbatim
Recall that the first message, @code{Sent 1024 bytes to 10.1.2.4} is the
UDP echo client sending a packet to the server. In this case, the client
is on the wireless network (10.1.3.0). The second message,
@code{Received 1024 bytes from 10.1.3.3}, is from the UDP echo server,
generated when it receives the echo packet. The final message,
@code{Received 1024 bytes from 10.1.2.4} is from the echo client, indicating
that it has received its echo back from the server.
If you now go and look in the top level directory, you will find two trace
files:
@verbatim
~/repos/ns-3-dev > ls *.pcap
third-4-0.pcap third-7-0.pcap
~/repos/ns-3-dev >
@end verbatim
The file ``third-4-0.pcap'' corresponds to the pcap trace for node four -
device zero. This is the CSMA network node that acted as the echo server.
Take a look at the tcpdump for this device:
@verbatim
~/repos/ns-3-dev > tcpdump -r third-4-0.pcap -nn -tt
reading from file third-4-0.pcap, link-type EN10MB (Ethernet)
2.005855 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
2.005855 arp reply 10.1.2.4 is-at 00:00:00:00:00:06
2.005859 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
2.005859 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4
2.005861 arp reply 10.1.2.1 is-at 00:00:00:00:00:03
2.005861 IP 10.1.2.4.9 > 10.1.3.3.49153: UDP, length 1024
~/repos/ns-3-dev >
@end verbatim
This should be familiar and easily understood. If you've forgotten, go back
and look at the discussion in @code{second.cc}. This is the same sequence.
Now, take a look at the other trace file, ``third-7-0.pcap.'' This is the
trace file for the wireless STA node that acts as the echo client.
@verbatim
~/repos/ns-3-dev > tcpdump -r third-7-0.pcap -nn -tt
reading from file third-7-0.pcap, link-type IEEE802_11 (802.11)
0.000146 Beacon (ns-3-ssid) ...
H: 0
0.000180 Assoc Request (ns-3-ssid) ...
0.000336 Acknowledgment RA:00:00:00:00:00:07
0.000454 Assoc Response AID(0) :: Succesful
0.000514 Acknowledgment RA:00:00:00:00:00:0a
0.000746 Assoc Request (ns-3-ssid) ...
0.000902 Acknowledgment RA:00:00:00:00:00:09
0.001020 Assoc Response AID(0) :: Succesful
0.001036 Acknowledgment RA:00:00:00:00:00:0a
0.001219 Assoc Request (ns-3-ssid) ...
0.001279 Acknowledgment RA:00:00:00:00:00:08
0.001478 Assoc Response AID(0) :: Succesful
0.001538 Acknowledgment RA:00:00:00:00:00:0a
2.000000 arp who-has 10.1.3.4 (ff:ff:ff:ff:ff:ff) tell 10.1.3.3
2.000172 Acknowledgment RA:00:00:00:00:00:09
2.000318 arp who-has 10.1.3.4 (ff:ff:ff:ff:ff:ff) tell 10.1.3.3
2.000581 arp reply 10.1.3.4 is-at 00:00:00:00:00:0a
2.000597 Acknowledgment RA:00:00:00:00:00:0a
2.000693 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
2.002229 Acknowledgment RA:00:00:00:00:00:09
2.009663 arp who-has 10.1.3.3 (ff:ff:ff:ff:ff:ff) tell 10.1.3.4
2.009697 arp reply 10.1.3.3 is-at 00:00:00:00:00:09
2.009869 Acknowledgment RA:00:00:00:00:00:09
2.011487 IP 10.1.2.4.9 > 10.1.3.3.49153: UDP, length 1024
2.011503 Acknowledgment RA:00:00:00:00:00:0a
2.500112 Beacon[|802.11]
5.000112 Beacon[|802.11]
7.500112 Beacon[|802.11]
~/repos/ns-3-dev >
@end verbatim
You can see that the link type is now 802.11 as you would expect. We leave
it as an exercise to parse the dump and trace packets across the internetwork.
Now, we spent a lot of time setting up mobility models for the wireless network
and so it would be a shame to finish up without even showing that the STA
nodes are actually moving around. Let's do this by hooking into the
@code{MobilityModel} course change trace source. This is usually considered
a fairly advanced topic, but let's just go for it.
As mentioned in the Tweaking Ns-3 section, the @command{ns-3} tracing system
is divided into trace sources and trace sinks, and we provide functions to
connect the two. We will use the mobility model predefined course change
trace source to originate the trace events. We will need to write a trace
sink to connect to that source that will display some pretty information for
us. Despite its reputation as being difficult, it's really quite simple.
Just before the main program of the @code{scratch/third.cc} script, add the
following function:
@verbatim
void
CourseChange (std::string context, Ptr<const MobilityModel> model)
{
Vector position = model->GetPosition ();
NS_LOG_UNCOND (context <<
" x = " << position.x << ", y = " << position.y);
}
@end verbatim
This code just pulls the position information from the mobility model and
unconditionally logs the x and y position of the node. We are
going to arrange for this function to be called every time the wireless
node with the echo client changes its position. We do this using the
@code{Config::Connect} function. Add the following lines of code to the
script just before the @code{Simulator::Run} call.
@verbatim
std::ostringstream oss;
oss <<
"/NodeList/" << wifiStaNodes.Get (nWifi - 1)->GetId () <<
"/$ns3::MobilityModel/CourseChange";
Config::Connect (oss.str (), MakeCallback (&CourseChange));
@end verbatim
What we do here is to create a string containing the tracing namespace path
of the event to which we want to connect. First, we have to figure out which
node it is we want using the @code{GetId} method as described earlier. In the
case of the default number of CSMA and wireless nodes, this turns out to be
node seven and the tracing namespace path to the mobility model would look
like,
@verbatim
/NodeList/7/$ns3::MobilityModel/CourseChange
@end verbatim
Based on the discussion in the tracing section, you can easily infer that
this trace path references the seventh node in the NodeList. It specifies
what is called an aggregated object of type @code{ns3::MobilityModel}. The
dollar sign prefix implies that the MobilityModel is aggregated to node seven.
The last component of the path means that we are hooking into the
``CourseChange'' event of that model.
We make a connection between the trace source in node seven with our trace
sink by calling @code{Config::Connect} and passing this namespace path. Once
this is done, every course change event on node seven will be hooked into our
trace sink, which will in turn print out the new position.
If you now run the simulation, you will see the course changes displayed as
they happen.
@verbatim
~/repos/ns-3-dev > ./waf --run scratch/third
Entering directory `/home/craigdo/repos/ns-3-dev/build'
Compilation finished successfully
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10, y = 0
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.1304, y = 0.493761
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.70417, y = 1.39837
/NodeList/7/$ns3::MobilityModel/CourseChange x = 7.94799, y = 2.05274
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.82597, y = 1.57404
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.3003, y = 0.723347
Sent 1024 bytes to 10.1.2.4
Received 1024 bytes from 10.1.3.3
Received 1024 bytes from 10.1.2.4
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.74083, y = 1.62109
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.00146, y = 0.655647
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.98731, y = 0.823279
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.50206, y = 1.69766
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.68108, y = 2.26862
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.25992, y = 1.45317
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.55655, y = 0.742346
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.21992, y = 1.68398
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.81273, y = 0.878638
/NodeList/7/$ns3::MobilityModel/CourseChange x = 7.83171, y = 1.07256
/NodeList/7/$ns3::MobilityModel/CourseChange x = 7.60027, y = 0.0997156
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.45367, y = 0.620978
/NodeList/7/$ns3::MobilityModel/CourseChange x = 7.68484, y = 1.26043
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.53659, y = 0.736479
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.51876, y = 0.548502
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.89778, y = 1.47389
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.98984, y = 1.893
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.91524, y = 1.51402
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.98761, y = 1.14054
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.16617, y = 0.570239
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.02954, y = 1.56086
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.09551, y = 2.55868
~/repos/ns-3-dev >
@end verbatim
If you are feeling brave, there is a list of all trace sources in the
@uref{http://www.nsnam.org/doxygen-release/index.html,,ns-3 Doxygen}
which you can find in the ``Modules'' tab.
Under the ``core'' section, you will find a link to ``The list of all trace
sources.'' You may find it interesting to try and hook some of these
traces yourself. Additionally in the ``Modules'' documentation, there is
a link to ``The list of all attributes.'' You can set the default value of
any of these attributes via the command line as we have previously discussed.
We have just scratched the surface of @command{ns-3} in this tutorial, but we
hope we have covered enough to get you started doing useful work.
-- The @command{ns-3} development team.