NS3

https://www.nsnam.org/docs/tutorial/html/building-topologies.html

In this section we are going to expand our mastery of ns-3 networkdevices and channels to cover an example of a bus network. ns-3provides a net device and channel we call CSMA (Carrier Sense Multiple Access).

The ns-3 CSMA device models a simple network in the spirit ofEthernet. A real Ethernet uses CSMA/CD (Carrier Sense Multiple Access withCollision Detection) scheme with exponentially increasing backoff to contendfor the shared transmission medium. The ns-3 CSMA device andchannel models only a subset of this.

Just as we have seen point-to-point topology helper objects when constructingpoint-to-point topologies, we will see equivalent CSMA topology helpers inthis section. The appearance and operation of these helpers should lookquite familiar to you.

We provide an example script in our examples/tutorial directory. This scriptbuilds on the first.cc script and adds a CSMA network to thepoint-to-point simulation we’ve already considered. Go ahead and openexamples/tutorial/second.cc in your favorite editor. You will have already seenenough ns-3 code to understand most of what is going on in thisexample, but we will go over the entire script and examine some of the output.

Just as in the first.cc example (and in all ns-3 examples) the filebegins with an emacs mode line and some GPL boilerplate.

The actual code begins by loading module include files just as was done in thefirst.cc example.

#include "ns3/core-module.h"
#include "ns3/network-module.h"
#include "ns3/csma-module.h"
#include "ns3/internet-module.h"
#include "ns3/point-to-point-module.h"
#include "ns3/applications-module.h"
#include "ns3/ipv4-global-routing-helper.h"

One thing that can be surprisingly useful is a small bit of ASCII art thatshows a cartoon of the network topology constructed in the example. You willfind a similar “drawing” in most of our examples.

In this case, you can see that we are going to extend our point-to-pointexample (the link between the nodes n0 and n1 below) by hanging a bus networkoff of the right side. Notice that this is the default network topologysince you can actually vary the number of nodes created on the LAN. If youset nCsma to one, there will be a total of two nodes on the LAN (CSMAchannel) — one required node and one “extra” node. By default there arethree “extra” nodes as seen below:

// Default Network Topology
//
//       10.1.1.0
// n0 -------------- n1   n2   n3   n4
//    point-to-point  |    |    |    |
//                    ================
//                      LAN 10.1.2.0

Then the ns-3 namespace is used and a logging component is defined.This is all just as it was in first.cc, so there is nothing new yet.

using namespace ns3;

NS_LOG_COMPONENT_DEFINE ("SecondScriptExample");

The main program begins with a slightly different twist. We use a verboseflag to determine whether or not the UdpEchoClientApplication andUdpEchoServerApplication logging components are enabled. This flagdefaults to true (the logging components are enabled) but allows us to turnoff logging during regression testing of this example.

You will see some familiar code that will allow you to change the numberof devices on the CSMA network via command line argument. We did somethingsimilar when we allowed the number of packets sent to be changed in the sectionon command line arguments. The last line makes sure you have at least one“extra” node.

The code consists of variations of previously covered API so you should beentirely comfortable with the following code at this point in the tutorial.

bool verbose = true;
uint32_t nCsma = 3;

CommandLine cmd;
cmd.AddValue ("nCsma", "Number of "extra" CSMA nodes/devices", nCsma);
cmd.AddValue ("verbose", "Tell echo applications to log if true", verbose);

cmd.Parse (argc, argv);

if (verbose)
  {
    LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
    LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);
  }

nCsma = nCsma == 0 ? 1 : nCsma;

The next step is to create two nodes that we will connect via thepoint-to-point link. The NodeContainer is used to do this just as wasdone in first.cc.

NodeContainer p2pNodes;
p2pNodes.Create (2);

Next, we declare another NodeContainer to hold the nodes that will bepart of the bus (CSMA) network. First, we just instantiate the containerobject itself.

NodeContainer csmaNodes;
csmaNodes.Add (p2pNodes.Get (1));
csmaNodes.Create (nCsma);

The next line of 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 nodesthat will get CSMA devices. The node in question is going to end up with apoint-to-point device and a CSMA device. We then create a number of“extra” nodes that compose the remainder of the CSMA network. Since wealready have one node in the CSMA network – the one that will have both apoint-to-point and CSMA net device, the number of “extra” nodes means thenumber nodes you desire in the CSMA section minus one.

The next bit of code should be quite familiar by now. We instantiate aPointToPointHelper and set the associated default Attributes sothat we create a five megabit per second transmitter on devices created usingthe helper and a two millisecond delay on channels created by the helper.

PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));

NetDeviceContainer p2pDevices;
p2pDevices = pointToPoint.Install (p2pNodes);

We then instantiate a NetDeviceContainer to keep track of thepoint-to-point net devices and we Install devices on thepoint-to-point nodes.

We mentioned above that you were going to see a helper for CSMA devices andchannels, and the next lines introduce them. The CsmaHelper works justlike a PointToPointHelper, but it creates and connects CSMA devices andchannels. In the case of a CSMA device and channel pair, notice that the datarate is specified by a channel Attribute instead of a deviceAttribute. 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 setthe data rate to 100 megabits per second, and then set the speed-of-light delayof the channel to 6560 nano-seconds (arbitrarily chosen as 1 nanosecond per footover a 100 meter segment). Notice that you can set an Attribute usingits native data type.

CsmaHelper csma;
csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));
csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));

NetDeviceContainer csmaDevices;
csmaDevices = csma.Install (csmaNodes);

Just as we created a NetDeviceContainer to hold the devices created bythe PointToPointHelper we create a NetDeviceContainer to holdthe devices created by our CsmaHelper. We call the Installmethod of the CsmaHelper to install the devices into the nodes of thecsmaNodes NodeContainer.

We now have our nodes, devices and channels created, but we have no protocolstacks present. Just as in the first.cc script, we will use theInternetStackHelper to install these stacks.

InternetStackHelper stack;
stack.Install (p2pNodes.Get (0));
stack.Install (csmaNodes);

Recall that we took one of the nodes from the p2pNodes container andadded it to the csmaNodes container. Thus we only need to installthe stacks on the remaining p2pNodes node, and all of the nodes in thecsmaNodes container to cover all of the nodes in the simulation.

Just as in the first.cc example script, we are going to use theIpv4AddressHelper to assign IP addresses to our device interfaces.First we use the network 10.1.1.0 to create the two addresses needed for ourtwo point-to-point devices.

Ipv4AddressHelper address;
address.SetBase ("10.1.1.0", "255.255.255.0");
Ipv4InterfaceContainer p2pInterfaces;
p2pInterfaces = address.Assign (p2pDevices);

Recall that we save the created interfaces in a container to make it easy topull out addressing information later for use in setting up the applications.

We now need to assign IP addresses to our CSMA device interfaces. Theoperation works just as it did for the point-to-point case, except we noware performing the operation on a container that has a variable number ofCSMA devices — remember we made the number of CSMA devices changeable bycommand line argument. The CSMA devices will be associated with IP addressesfrom network number 10.1.2.0 in this case, as seen below.

address.SetBase ("10.1.2.0", "255.255.255.0");
Ipv4InterfaceContainer csmaInterfaces;
csmaInterfaces = address.Assign (csmaDevices);

Now we have a topology built, but we need applications. This section isgoing to be fundamentally similar to the applications section offirst.cc but we are going to instantiate the server on one of thenodes that has a CSMA device and the client on the node having only apoint-to-point device.

First, we set up the echo server. We create a UdpEchoServerHelper andprovide a required Attribute value to the constructor which is the serverport number. Recall that this port can be changed later using theSetAttribute method if desired, but we require it to be provided tothe constructor.

UdpEchoServerHelper echoServer (9);

ApplicationContainer serverApps = echoServer.Install (csmaNodes.Get (nCsma));
serverApps.Start (Seconds (1.0));
serverApps.Stop (Seconds (10.0));

Recall that the csmaNodes NodeContainer contains one of thenodes created for the point-to-point network and nCsma “extra” nodes.What we want to get at is the last of the “extra” nodes. The zeroth entry ofthe csmaNodes container will be the point-to-point node. The easyway to think of this, then, is if we create one “extra” CSMA node, then itwill be at index one of the csmaNodes container. By induction,if we create nCsma “extra” nodes the last one will be at indexnCsma. You see this exhibited in the Get of the first line ofcode.

The client application is set up exactly as we did in the first.ccexample script. Again, we provide required Attributes to theUdpEchoClientHelper in the constructor (in this case the remote addressand port). We tell the client to send packets to the server we just installedon the last of the “extra” CSMA nodes. We install the client on theleftmost point-to-point node seen in the topology illustration.

UdpEchoClientHelper echoClient (csmaInterfaces.GetAddress (nCsma), 9);
echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.0)));
echoClient.SetAttribute ("PacketSize", UintegerValue (1024));

ApplicationContainer clientApps = echoClient.Install (p2pNodes.Get (0));
clientApps.Start (Seconds (2.0));
clientApps.Stop (Seconds (10.0));

Since we have actually built an internetwork here, we need some form ofinternetwork routing. ns-3 provides what we call global routing tohelp you out. Global routing takes advantage of the fact that the entireinternetwork is accessible in the simulation and runs through the all of thenodes created for the simulation — it does the hard work of setting up routingfor you without having to configure routers.

Basically, what happens is that each node behaves as if it were an OSPF routerthat communicates instantly and magically with all other routers behind thescenes. Each node generates link advertisements and communicates themdirectly to a global route manager which uses this global information toconstruct the routing tables for each node. Setting up this form of routingis a one-liner:

Ipv4GlobalRoutingHelper::PopulateRoutingTables ();

Next we enable pcap tracing. The first line of code to enable pcap tracingin the point-to-point helper should be familiar to you by now. The secondline enables pcap tracing in the CSMA helper and there is an extra parameteryou haven’t encountered yet.

pointToPoint.EnablePcapAll ("second");
csma.EnablePcap ("second", csmaDevices.Get (1), true);

The CSMA network is a multi-point-to-point network. This means that therecan (and are in this case) multiple endpoints on a shared medium. Each ofthese endpoints has a net device associated with it. There are two basicalternatives to gathering trace information from such a network. One wayis to create a trace file for each net device and store only the packetsthat are emitted or consumed by that net device. Another way is to pickone of the devices and place it in promiscuous mode. That single devicethen “sniffs” the network for all packets and stores them in a singlepcap file. This is how tcpdump, for example, works. That finalparameter tells the CSMA helper whether or not to arrange to capturepackets in promiscuous mode.

In this example, we are going to select one of the devices on the CSMAnetwork and ask it to perform a promiscuous sniff of the network, therebyemulating what tcpdump would do. If you were on a Linux machineyou might do something like tcpdump -i eth0 to get the trace.In this case, we specify the device using csmaDevices.Get(1),which selects the first device in the container. Setting the finalparameter to true enables promiscuous captures.

The last section of code just runs and cleans up the simulation just likethe first.cc example.

  Simulator::Run ();
  Simulator::Destroy ();
  return 0;
}

In order to run this example, copy the second.cc example script intothe scratch directory and use waf to build just as you did withthe first.cc example. If you are in the top-level directory of therepository you just type,

$ cp examples/tutorial/second.cc scratch/mysecond.cc
$ ./waf

Warning: We use the file second.cc as one of our regression tests toverify that it works exactly as we think it should in order to make yourtutorial experience a positive one. This means that an executable namedsecond already exists in the project. To avoid any confusionabout what you are executing, please do the renaming to mysecond.ccsuggested above.

If you are following the tutorial religiously (you are, aren’t you) you willstill have the NS_LOG variable set, so go ahead and clear that variable andrun the program.

$ export NS_LOG=
$ ./waf --run scratch/mysecond

Since we have set up the UDP echo applications to log just as we did infirst.cc, you will see similar output when you run the script.

Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (0.415s)
Sent 1024 bytes to 10.1.2.4
Received 1024 bytes from 10.1.1.1
Received 1024 bytes from 10.1.2.4

Recall that the first message, “Sent 1024 bytes to 10.1.2.4,” is theUDP echo client sending a packet to the server. In this case, the serveris on a different network (10.1.2.0). The second message, “Received 1024bytes from 10.1.1.1,” is from the UDP echo server, generated when it receivesthe echo packet. The final message, “Received 1024 bytes from 10.1.2.4,”is from the echo client, indicating that it has received its echo back fromthe server.

If you now go and look in the top level directory, you will find three tracefiles:

second-0-0.pcap  second-1-0.pcap  second-2-0.pcap

Let’s take a moment to look at the naming of these files. They all have thesame form, <name>-<node>-<device>.pcap. For example, the first filein the listing is second-0-0.pcap which is the pcap trace from nodezero, device zero. This is the point-to-point net device on node zero. Thefile second-1-0.pcap is the pcap trace for device zero on node one,also a point-to-point net device; and the file second-2-0.pcap is thepcap trace for device zero on node two.

If you refer back to the topology illustration at the start of the section,you will see that node zero is the leftmost node of the point-to-point linkand node one is the node that has both a point-to-point device and a CSMAdevice. You will see that node two is the first “extra” node on the CSMAnetwork and its device zero was selected as the device to capture thepromiscuous-mode trace.

Now, let’s follow the echo packet through the internetwork. First, do atcpdump of the trace file for the leftmost point-to-point node — node zero.

$ tcpdump -nn -tt -r second-0-0.pcap

You should see the contents of the pcap file displayed:

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.017607 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

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 thedevice associated with IP address 10.1.1.1 headed for IP address10.1.2.4 (the rightmost CSMA node). This packet will move over thepoint-to-point link and be received by the point-to-point net device on nodeone. Let’s take a look:

$ tcpdump -nn -tt -r second-1-0.pcap

You should now see the pcap trace output of the other side of the point-to-pointlink:

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.013921 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

Here we see that the link type is also PPP as we would expect. You see thepacket from IP address 10.1.1.1 (that was sent at 2.000000 seconds) headedtoward IP address 10.1.2.4 appear on this interface. Now, internally to thisnode, the packet will be forwarded to the CSMA interface and we should see itpop out on that device headed for its ultimate destination.

Remember that we selected node 2 as the promiscuous sniffer node for the CSMAnetwork so let’s then look at second-2-0.pcap and see if its there.

$ tcpdump -nn -tt -r second-2-0.pcap

You should now see the promiscuous dump of node two, device zero:

reading from file second-2-0.pcap, link-type EN10MB (Ethernet)
007698 ARP, Request who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1, length 50
007710 ARP, Reply 10.1.2.4 is-at 00:00:00:00:00:06, length 50
007803 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
013815 ARP, Request who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4, length 50
013828 ARP, Reply 10.1.2.1 is-at 00:00:00:00:00:03, length 50
013921 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

As you can see, the link type is now “Ethernet”. Something new has appeared,though. The bus network needs ARP, the Address Resolution Protocol.Node one knows it needs to send the packet to IP address 10.1.2.4, but itdoesn’t know the MAC address of the corresponding node. It broadcasts on theCSMA network (ff:ff:ff:ff:ff:ff) asking for the device that has IP address10.1.2.4. In this case, the rightmost node replies saying it is at MAC address00:00:00:00:00:06. Note that node two is not directly involved in thisexchange, but is sniffing the network and reporting all of the traffic it sees.

This exchange is seen in the following lines,

2.007698 ARP, Request who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1, length 50
2.007710 ARP, Reply 10.1.2.4 is-at 00:00:00:00:00:06, length 50

Then node one, device one goes ahead and sends the echo packet to the UDP echoserver at IP address 10.1.2.4.

2.007803 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024

The server receives the echo request and turns the packet around trying to sendit back to the source. The server knows that this address is on another networkthat it reaches via IP address 10.1.2.1. This is because we initialized globalrouting and it has figured all of this out for us. But, the echo server nodedoesn’t know the MAC address of the first CSMA node, so it has to ARP for itjust like the first CSMA node had to do.

2.013815 ARP, Request who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4, length 50
2.013828 ARP, Reply 10.1.2.1 is-at 00:00:00:00:00:03, length 50

The server then sends the echo back to the forwarding node.

2.013921 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

Looking back at the rightmost node of the point-to-point link,

$ tcpdump -nn -tt -r second-1-0.pcap

You can now see the echoed packet coming back onto the point-to-point link asthe last line of the trace dump.

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.013921 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

Lastly, you can look back at the node that originated the echo

$ tcpdump -nn -tt -r second-0-0.pcap

and see that the echoed packet arrives back at the source at 2.017607 seconds,

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.017607 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024

Finally, recall that we added the ability to control the number of CSMA devicesin the simulation by command line argument. You can change this argument inthe same way as when we looked at changing the number of packets echoed in thefirst.cc example. Try running the program with the number of “extra”devices set to four:

$ ./waf --run "scratch/mysecond --nCsma=4"

You should now see,

Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (0.405s)
At time 2s client sent 1024 bytes to 10.1.2.5 port 9
At time 2.0118s server received 1024 bytes from 10.1.1.1 port 49153
At time 2.0118s server sent 1024 bytes to 10.1.1.1 port 49153
At time 2.02461s client received 1024 bytes from 10.1.2.5 port 9

Notice that the echo server has now been relocated to the last of the CSMAnodes, which is 10.1.2.5 instead of the default case, 10.1.2.4.

It is possible that you may not be satisfied with a trace file generated bya bystander in the CSMA network. You may really want to get a trace froma single device and you may not be interested in any other traffic on thenetwork. You can do this fairly easily.

Let’s take a look at scratch/mysecond.cc and add that code enabling usto be more specific. ns-3 helpers provide methods that take a nodenumber and device number as parameters. Go ahead and replace theEnablePcap calls with the calls below.

pointToPoint.EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
csma.EnablePcap ("second", csmaNodes.Get (nCsma)->GetId (), 0, false);
csma.EnablePcap ("second", csmaNodes.Get (nCsma-1)->GetId (), 0, false);

We know that we want to create a pcap file with the base name “second” andwe 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 arenumbered in a monotonically increasing fashion starting from zero in theorder in which you created them. One way to get a node number is to figurethis number out “manually” by contemplating the order of node creation.If you take a look at the network topology illustration at the beginning ofthe file, we did this for you and you can see that the last CSMA node isgoing to be node number nCsma + 1. This approach can becomeannoyingly difficult in larger simulations.

An alternate way, which we use here, is to realize that theNodeContainers contain pointers to ns-3 Node Objects.The Node Object has a method called GetId which will return thatnode’s ID, which is the node number we seek. Let’s go take a look at theDoxygen for the Node and locate that method, which is further down inthe ns-3 core code than we’ve seen so far; but sometimes you have tosearch diligently for useful things.

Go to the Doxygen documentation for your release (recall that you can find iton the project web site). You can get to the Node documentation bylooking through at the “Classes” tab and scrolling down the “Class List”until you find ns3::Node. Select ns3::Node and you will be takento the documentation for the Node class. If you now scroll down to theGetId method and select it, you will be taken to the detaileddocumentation for the method. Using the GetId method can makedetermining node numbers much easier in complex topologies.

Let’s clear the old trace files out of the top-level directory to avoid confusionabout what is going on,

$ rm *.pcap
$ rm *.tr

If you build the new script and run the simulation setting nCsma to 100,

$ ./waf --run "scratch/mysecond --nCsma=100"

you will see the following output:

Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (0.407s)
At time 2s client sent 1024 bytes to 10.1.2.101 port 9
At time 2.0068s server received 1024 bytes from 10.1.1.1 port 49153
At time 2.0068s server sent 1024 bytes to 10.1.1.1 port 49153
At time 2.01761s client received 1024 bytes from 10.1.2.101 port 9

Note that the echo server is now located at 10.1.2.101 which corresponds tohaving 100 “extra” CSMA nodes with the echo server on the last one. If youlist the pcap files in the top level directory you will see,

second-0-0.pcap  second-100-0.pcap  second-101-0.pcap

The trace file second-0-0.pcap is the “leftmost” point-to-point devicewhich is the echo packet source. The file second-101-0.pcap correspondsto the rightmost CSMA device which is where the echo server resides. You mayhave noticed that the final parameter on the call to enable pcap tracing on theecho server node was false. This means that the trace gathered on that nodewas in non-promiscuous mode.

To illustrate the difference between promiscuous and non-promiscuous traces, wealso requested a non-promiscuous trace for the next-to-last node. Go ahead andtake a look at the tcpdump for second-100-0.pcap.

$ tcpdump -nn -tt -r second-100-0.pcap

You can now see that node 100 is really a bystander in the echo exchange. Theonly packets that it receives are the ARP requests which are broadcast to theentire CSMA network.

reading from file second-100-0.pcap, link-type EN10MB (Ethernet)
2.006698 ARP, Request who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1, length 50
2.013815 ARP, Request who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.101, length 50

Now take a look at the tcpdump for second-101-0.pcap.

$ tcpdump -nn -tt -r second-101-0.pcap

You can now see that node 101 is really the participant in the echo exchange.

reading from file second-101-0.pcap, link-type EN10MB (Ethernet)
006698 ARP, Request who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1, length 50
006698 ARP, Reply 10.1.2.101 is-at 00:00:00:00:00:67, length 50
006803 IP 10.1.1.1.49153 > 10.1.2.101.9: UDP, length 1024
013803 ARP, Request who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.101, length 50
013828 ARP, Reply 10.1.2.1 is-at 00:00:00:00:00:03, length 50
013828 IP 10.1.2.101.9 > 10.1.1.1.49153: UDP, length 1024

Models, Attributes and Reality

This is a convenient place to make a small excursion and make an importantpoint. It may or may not be obvious to you, but whenever one is using asimulation, it is important to understand exactly what is being modeled andwhat is not. It is tempting, for example, to think of the CSMA devicesand channels used in the previous section as if they were real Ethernetdevices; and to expect a simulation result to directly reflect what willhappen in a real Ethernet. This is not the case.

A model is, by definition, an abstraction of reality. It is ultimately theresponsibility of the simulation script author to determine the so-called“range of accuracy” and “domain of applicability” of the simulation asa whole, and therefore its constituent parts.

In some cases, like Csma, it can be fairly easy to determine what isnot modeled. By reading the model description (csma.h) youcan find that there is no collision detection in the CSMA model and decideon how applicable its use will be in your simulation or what caveats youmay want to include with your results. In other cases, it can be quite easyto configure behaviors that might not agree with any reality you can go outand buy. It will prove worthwhile to spend some time investigating a fewsuch instances, and how easily you can swerve outside the bounds of realityin your simulations.

As you have seen, ns-3 provides Attributes which a usercan easily set to change model behavior. Consider two of the Attributesof the CsmaNetDevice: Mtu and EncapsulationMode.The Mtu attribute indicates the Maximum Transmission Unit to thedevice. This is the size of the largest Protocol Data Unit (PDU) that thedevice can send.

The MTU defaults to 1500 bytes in the CsmaNetDevice. This defaultcorresponds to a number found in RFC 894, “A Standard for the Transmissionof IP Datagrams over Ethernet Networks.” The number is actually derivedfrom the maximum packet size for 10Base5 (full-spec Ethernet) networks –1518 bytes. If you subtract the DIX encapsulation overhead for Ethernetpackets (18 bytes) you will end up with a maximum possible data size (MTU)of 1500 bytes. One can also find that the MTU for IEEE 802.3 networksis 1492 bytes. This is because LLC/SNAP encapsulation adds an extra eightbytes of overhead to the packet. In both cases, the underlying hardware canonly send 1518 bytes, but the data size is different.

In order to set the encapsulation mode, the CsmaNetDevice providesan Attribute called EncapsulationMode which can take on thevalues Dix or Llc. These correspond to Ethernet and LLC/SNAPframing respectively.

If one leaves the Mtu at 1500 bytes and changes the encapsulation modeto Llc, the result will be a network that encapsulates 1500 byte PDUswith LLC/SNAP framing resulting in packets of 1526 bytes, which would beillegal in many networks, since they can transmit a maximum of 1518 bytes perpacket. This would most likely result in a simulation that quite subtly doesnot reflect the reality you might be expecting.

Just to complicate the picture, there exist jumbo frames (1500 < MTU <= 9000 bytes)and super-jumbo (MTU > 9000 bytes) frames that are not officially sanctionedby IEEE but are available in some high-speed (Gigabit) networks and NICs. Onecould leave the encapsulation mode set to Dix, and set the MtuAttribute on a CsmaNetDevice to 64000 bytes – even though anassociated CsmaChannel DataRate was set at 10 megabits per second.This would essentially model an Ethernet switch made out of vampire-tapped1980s-style 10Base5 networks that support super-jumbo datagrams. This iscertainly not something that was ever made, nor is likely to ever be made,but it is quite easy for you to configure.

In the previous example, you used the command line to create a simulation thathad 100 Csma nodes. You could have just as easily created a simulationwith 500 nodes. If you were actually modeling that 10Base5 vampire-tap network,the maximum length of a full-spec Ethernet cable is 500 meters, with a minimumtap spacing of 2.5 meters. That means there could only be 200 taps on areal network. You could have quite easily built an illegal network in thatway as well. This may or may not result in a meaningful simulation dependingon what you are trying to model.

Similar situations can occur in many places in ns-3 and in anysimulator. For example, you may be able to position nodes in such a way thatthey occupy the same space at the same time, or you may be able to configureamplifiers or noise levels that violate the basic laws of physics.

ns-3 generally favors flexibility, and many models will allow freelysetting Attributes without trying to enforce any arbitrary consistencyor particular underlying spec.

The thing to take home from this is that ns-3 is going to provide asuper-flexible base for you to experiment with. It is up to you to understandwhat you are asking the system to do and to make sure that the simulations youcreate have some meaning and some connection with a reality defined by you.

Building a Wireless Network Topology

In this section we are going to further expand our knowledge of ns-3network devices and channels to cover an example of a wireless network.ns-3 provides a set of 802.11 models that attempt to provide anaccurate 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 whenconstructing point-to-point topologies, we will see equivalent Wifitopology helpers in this section. The appearance and operation of thesehelpers should look quite familiar to you.

We provide an example script in our examples/tutorial directory. This scriptbuilds on the second.cc script and adds a Wifi network. Go ahead andopen examples/tutorial/third.cc in your favorite editor. You will have alreadyseen enough ns-3 code to understand most of what is going on inthis example, but there are a few new things, so we will go over the entirescript and examine some of the output.

Just as in the second.cc example (and in all 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 networktopology constructed in the example. You can see that we are going tofurther 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 thenumber of nodes created on the wired and wireless networks. Just as in thesecond.cc script case, if you change nCsma, it will give you anumber of “extra” CSMA nodes. Similarly, you can set nWifi tocontrol how many STA (station) nodes are created in the simulation.There will always be one AP (access point) node on the wirelessnetwork. By default there are three “extra” CSMA nodes and three wirelessSTA nodes.

The code begins by loading module include files just as was done in thesecond.cc example. There are a couple of new includes correspondingto the Wifi module and the mobility module which we will discuss below.

#include "ns3/core-module.h"
#include "ns3/point-to-point-module.h"
#include "ns3/network-module.h"
#include "ns3/applications-module.h"
#include "ns3/wifi-module.h"
#include "ns3/mobility-module.h"
#include "ns3/csma-module.h"
#include "ns3/internet-module.h"

The network topology illustration follows:

// 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

You can see that we are adding a new network device to the node on the leftside of the point-to-point link that becomes the access point for the wirelessnetwork. A number of wireless STA nodes are created to fill out the new10.1.3.0 network as shown on the left side of the illustration.

After the illustration, the ns-3 namespace is used and a loggingcomponent is defined. This should all be quite familiar by now.

using namespace ns3;

NS_LOG_COMPONENT_DEFINE ("ThirdScriptExample");

The main program begins just like second.cc by adding some command lineparameters for enabling or disabling logging components and for changing thenumber of devices created.

bool verbose = true;
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.AddValue ("verbose", "Tell echo applications to log if true", verbose);

cmd.Parse (argc,argv);

if (verbose)
  {
    LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
    LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);
  }

Just as in all of the previous examples, the next step is to create two nodesthat we will connect via the point-to-point link.

NodeContainer p2pNodes;
p2pNodes.Create (2);

Next, we see an old friend. We instantiate a PointToPointHelper andset the associated default Attributes so that we create a five megabitper second transmitter on devices created using the helper and a two milliseconddelay on channels created by the helper. We then Install the deviceson the nodes and the channel between them.

PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));

NetDeviceContainer p2pDevices;
p2pDevices = pointToPoint.Install (p2pNodes);

Next, we declare another NodeContainer to hold the nodes that will bepart of the bus (CSMA) network.

NodeContainer csmaNodes;
csmaNodes.Add (p2pNodes.Get (1));
csmaNodes.Create (nCsma);

We then instantiate a CsmaHelper and set its Attributes as we didin the previous example. We create a NetDeviceContainer to keep track ofthe created CSMA net devices and then we Install CSMA devices on theselected nodes.

CsmaHelper csma;
csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));
csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));

NetDeviceContainer csmaDevices;
csmaDevices = csma.Install (csmaNodes);

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 thecommand line argument, and we are going to use the “leftmost” node of thepoint-to-point link as the node for the access point.

NodeContainer wifiStaNodes;
wifiStaNodes.Create (nWifi);
NodeContainer wifiApNode = p2pNodes.Get (0);

The next bit of code constructs the wifi devices and the interconnectionchannel between these wifi nodes. First, we configure the PHY and channelhelpers:

YansWifiChannelHelper channel = YansWifiChannelHelper::Default ();
YansWifiPhyHelper phy = YansWifiPhyHelper::Default ();

For simplicity, this code uses the default PHY layer configuration andchannel models which are documented in the API doxygen documentation forthe YansWifiChannelHelper::Default and YansWifiPhyHelper::Defaultmethods. Once these objects are created, we create a channel objectand associate it to our PHY layer object manager to make surethat all the PHY layer objects created by the YansWifiPhyHelpershare the same underlying channel, that is, they share the samewireless medium and can communication and interfere:

phy.SetChannel (channel.Create ());

Once the PHY helper is configured, we can focus on the MAC layer. Here we choose towork with non-Qos MACs so we use a NqosWifiMacHelper object to set MAC parameters.

WifiHelper wifi = WifiHelper::Default ();
wifi.SetRemoteStationManager ("ns3::AarfWifiManager");

NqosWifiMacHelper mac = NqosWifiMacHelper::Default ();

The SetRemoteStationManager method tells the helper the type ofrate control algorithm to use. Here, it is asking the helper to use the AARFalgorithm — details are, of course, available in Doxygen.

Next, we configure the type of MAC, the SSID of the infrastructure network wewant to setup and make sure that our stations don’t perform active probing:

Ssid ssid = Ssid ("ns-3-ssid");
mac.SetType ("ns3::StaWifiMac",
  "Ssid", SsidValue (ssid),
  "ActiveProbing", BooleanValue (false));

This code first creates an 802.11 service set identifier (SSID) objectthat will be used to set the value of the “Ssid” Attribute ofthe MAC layer implementation. The particular kind of MAC layer thatwill be created by the helper is specified by Attribute asbeing of the “ns3::StaWifiMac” type. The use ofNqosWifiMacHelper will ensure that the “QosSupported”Attribute for created MAC objects is set false. The combinationof these two configurations means that the MAC instance next createdwill be a non-QoS non-AP station (STA) in an infrastructure BSS (i.e.,a BSS with an AP). Finally, the “ActiveProbing” Attribute isset to false. This means that probe requests will not be sent by MACscreated by this helper.

Once all the station-specific parameters are fully configured, both at theMAC and PHY layers, we can invoke our now-familiar Install method tocreate the wifi devices of these stations:

NetDeviceContainer staDevices;
staDevices = wifi.Install (phy, mac, wifiStaNodes);

We have configured Wifi for all of our STA nodes, and now we need toconfigure the AP (access point) node. We begin this process by changingthe default Attributes of the NqosWifiMacHelper to reflect therequirements of the AP.

mac.SetType ("ns3::ApWifiMac",
             "Ssid", SsidValue (ssid));

In this case, the NqosWifiMacHelper is going to create MAClayers of the “ns3::ApWifiMac”, the latter specifying that a MACinstance configured as an AP should be created, with the helper typeimplying that the “QosSupported” Attribute should be set tofalse - disabling 802.11e/WMM-style QoS support at created APs.

The next lines create the single AP which shares the same set of PHY-levelAttributes (and channel) as the stations:

NetDeviceContainer apDevices;
apDevices = wifi.Install (phy, mac, wifiApNode);

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 nodestationary. We use the MobilityHelper to make this easy for us.First, we instantiate a MobilityHelper object and set someAttributes controlling the “position allocator” functionality.

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"));

This code tells the mobility helper to use a two-dimensional grid to initiallyplace the STA nodes. Feel free to explore the Doxygen for classns3::GridPositionAllocator to see exactly what is being done.

We have arranged our nodes on an initial grid, but now we need to tell themhow to move. We choose the RandomWalk2dMobilityModel which has thenodes move in a random direction at a random speed around inside a boundingbox.

mobility.SetMobilityModel ("ns3::RandomWalk2dMobilityModel",
  "Bounds", RectangleValue (Rectangle (-50, 50, -50, 50)));

We now tell the MobilityHelper to install the mobility models on theSTA nodes.

mobility.Install (wifiStaNodes);

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 thens3::ConstantPositionMobilityModel:

mobility.SetMobilityModel ("ns3::ConstantPositionMobilityModel");
mobility.Install (wifiApNode);

We now have our nodes, devices and channels created, and mobility modelschosen for the Wifi nodes, but we have no protocol stacks present. Just aswe have done previously many times, we will use the InternetStackHelperto install these stacks.

InternetStackHelper stack;
stack.Install (csmaNodes);
stack.Install (wifiApNode);
stack.Install (wifiStaNodes);

Just as in the second.cc example script, we are going to use theIpv4AddressHelper to assign IP addresses to our device interfaces.First we use the network 10.1.1.0 to create the two addresses needed for ourtwo point-to-point devices. Then we use network 10.1.2.0 to assign addressesto the CSMA network and then we assign addresses from network 10.1.3.0 toboth the STA devices and the AP on the wireless network.

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);

We put the echo server on the “rightmost” node in the illustration at thestart of the file. We have done this before.

UdpEchoServerHelper echoServer (9);

ApplicationContainer serverApps = echoServer.Install (csmaNodes.Get (nCsma));
serverApps.Start (Seconds (1.0));
serverApps.Stop (Seconds (10.0));

And we put the echo client on the last STA node we created, pointing it tothe server on the CSMA network. We have also seen similar operations before.

UdpEchoClientHelper echoClient (csmaInterfaces.GetAddress (nCsma), 9);
echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.0)));
echoClient.SetAttribute ("PacketSize", UintegerValue (1024));

ApplicationContainer clientApps =
  echoClient.Install (wifiStaNodes.Get (nWifi - 1));
clientApps.Start (Seconds (2.0));
clientApps.Stop (Seconds (10.0));

Since we have built an internetwork here, we need to enable internetwork routingjust as we did in the second.cc example script.

Ipv4GlobalRoutingHelper::PopulateRoutingTables ();

One thing that can surprise some users is the fact that the simulation we justcreated will never “naturally” stop. This is because we asked the wirelessaccess point to generate beacons. It will generate beacons forever, and thiswill result in simulator events being scheduled into the future indefinitely,so we must tell the simulator to stop even though it may have beacon generationevents scheduled. The following line of code tells the simulator to stop so thatwe don’t simulate beacons forever and enter what is essentially an endlessloop.

Simulator::Stop (Seconds (10.0));

We create just enough tracing to cover all three networks:

pointToPoint.EnablePcapAll ("third");
phy.EnablePcap ("third", apDevices.Get (0));
csma.EnablePcap ("third", csmaDevices.Get (0), true);

These three lines of code will start pcap tracing on both of the point-to-pointnodes that serves as our backbone, will start a promiscuous (monitor) modetrace on the Wifi network, and will start a promiscuous trace on the CSMAnetwork. This will let us see all of the traffic with a minimum number oftrace files.

Finally, we actually run the simulation, clean up and then exit the program.

  Simulator::Run ();
  Simulator::Destroy ();
  return 0;
}

In order to run this example, you have to copy the third.cc examplescript into the scratch directory and use Waf to build just as you did withthe second.cc example. If you are in the top-level directory of therepository you would type,

$ cp examples/tutorial/third.cc scratch/mythird.cc
$ ./waf
$ ./waf --run scratch/mythird

Again, since we have set up the UDP echo applications just as we did in thesecond.cc script, you will see similar output.

Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (0.407s)
At time 2s client sent 1024 bytes to 10.1.2.4 port 9
At time 2.01796s server received 1024 bytes from 10.1.3.3 port 49153
At time 2.01796s server sent 1024 bytes to 10.1.3.3 port 49153
At time 2.03364s client received 1024 bytes from 10.1.2.4 port 9

Recall that the first message, Sent 1024 bytes to 10.1.2.4,” is theUDP echo client sending a packet to the server. In this case, the clientis on the wireless network (10.1.3.0). The second message,“Received 1024 bytes from 10.1.3.3,” is from the UDP echo server,generated when it receives the echo packet. The final message,“Received 1024 bytes from 10.1.2.4,” is from the echo client, indicatingthat it has received its echo back from the server.

If you now go and look in the top level directory, you will find four tracefiles from this simulation, two from node zero and two from node one:

third-0-0.pcap  third-0-1.pcap  third-1-0.pcap  third-1-1.pcap

The file “third-0-0.pcap” corresponds to the point-to-point device on nodezero – the left side of the “backbone”. The file “third-1-0.pcap”corresponds to the point-to-point device on node one – the right side of the“backbone”. The file “third-0-1.pcap” will be the promiscuous (monitormode) trace from the Wifi network and the file “third-1-1.pcap” will be thepromiscuous trace from the CSMA network. Can you verify this by inspectingthe code?

Since the echo client is on the Wifi network, let’s start there. Let’s takea look at the promiscuous (monitor mode) trace we captured on that network.

$ tcpdump -nn -tt -r third-0-1.pcap

You should see some wifi-looking contents you haven’t seen here before:

reading from file third-0-1.pcap, link-type IEEE802_11 (802.11)
000025 Beacon (ns-3-ssid) [6.0* 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit] IBSS
000308 Assoc Request (ns-3-ssid) [6.0 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit]
000324 Acknowledgment RA:00:00:00:00:00:08
000402 Assoc Response AID(0) :: Successful
000546 Acknowledgment RA:00:00:00:00:00:0a
000721 Assoc Request (ns-3-ssid) [6.0 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit]
000737 Acknowledgment RA:00:00:00:00:00:07
000824 Assoc Response AID(0) :: Successful
000968 Acknowledgment RA:00:00:00:00:00:0a
001134 Assoc Request (ns-3-ssid) [6.0 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit]
001150 Acknowledgment RA:00:00:00:00:00:09
001273 Assoc Response AID(0) :: Successful
001417 Acknowledgment RA:00:00:00:00:00:0a
102400 Beacon (ns-3-ssid) [6.0* 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit] IBSS
204800 Beacon (ns-3-ssid) [6.0* 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit] IBSS
307200 Beacon (ns-3-ssid) [6.0* 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit] IBSS

You can see that the link type is now 802.11 as you would expect. You canprobably understand what is going on and find the IP echo request and responsepackets in this trace. We leave it as an exercise to completely parse thetrace dump.

Now, look at the pcap file of the left side of the point-to-point link,

$ tcpdump -nn -tt -r third-0-0.pcap

Again, you should see some familiar looking contents:

reading from file third-0-0.pcap, link-type PPP (PPP)
2.008151 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
2.026758 IP 10.1.2.4.9 > 10.1.3.3.49153: UDP, length 1024

This is the echo packet going from left to right (from Wifi to CSMA) and backagain across the point-to-point link.

Now, look at the pcap file of the right side of the point-to-point link,

$ tcpdump -nn -tt -r third-1-0.pcap

Again, you should see some familiar looking contents:

reading from file third-1-0.pcap, link-type PPP (PPP)
2.011837 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
2.023072 IP 10.1.2.4.9 > 10.1.3.3.49153: UDP, length 1024

This is also the echo packet going from left to right (from Wifi to CSMA) andback again across the point-to-point link with slightly different timingsas you might expect.

The echo server is on the CSMA network, let’s look at the promiscuous tracethere:

$ tcpdump -nn -tt -r third-1-1.pcap

You should see some familiar looking contents:

reading from file third-1-1.pcap, link-type EN10MB (Ethernet)
017837 ARP, Request who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1, length 50
017861 ARP, Reply 10.1.2.4 is-at 00:00:00:00:00:06, length 50
017861 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
022966 ARP, Request who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4, length 50
022966 ARP, Reply 10.1.2.1 is-at 00:00:00:00:00:03, length 50
023072 IP 10.1.2.4.9 > 10.1.3.3.49153: UDP, length 1024

This should be easily understood. If you’ve forgotten, go back and look atthe discussion in second.cc. This is the same sequence.

Now, we spent a lot of time setting up mobility models for the wireless networkand so it would be a shame to finish up without even showing that the STAnodes are actually moving around during the simulation. Let’s do this by hookinginto the MobilityModel course change trace source. This is just a sneakpeek into the detailed tracing section which is coming up, but this seems a verynice place to get an example in.

As mentioned in the “Tweaking ns-3” section, the ns-3 tracing systemis divided into trace sources and trace sinks, and we provide functions toconnect the two. We will use the mobility model predefined course changetrace source to originate the trace events. We will need to write a tracesink to connect to that source that will display some pretty information forus. Despite its reputation as being difficult, it’s really quite simple.Just before the main program of the scratch/mythird.cc script (i.e.,just after the NS_LOG_COMPONENT_DEFINE statement), add thefollowing function:

void
CourseChange (std::string context, Ptr<const MobilityModel> model)
{
  Vector position = model->GetPosition ();
  NS_LOG_UNCOND (context <<
    " x = " << position.x << ", y = " << position.y);
}

This code just pulls the position information from the mobility model andunconditionally logs the x and y position of the node. We aregoing to arrange for this function to be called every time the wirelessnode with the echo client changes its position. We do this using theConfig::Connect function. Add the following lines of code to thescript just before the Simulator::Run call.

std::ostringstream oss;
oss <<
  "/NodeList/" << wifiStaNodes.Get (nWifi - 1)->GetId () <<
  "/$ns3::MobilityModel/CourseChange";

Config::Connect (oss.str (), MakeCallback (&CourseChange));

What we do here is to create a string containing the tracing namespace pathof the event to which we want to connect. First, we have to figure out whichnode it is we want using the GetId method as described earlier. In thecase of the default number of CSMA and wireless nodes, this turns out to benode seven and the tracing namespace path to the mobility model would looklike,

/NodeList/7/$ns3::MobilityModel/CourseChange

Based on the discussion in the tracing section, you may infer that this tracepath references the seventh node in the global NodeList. It specifieswhat is called an aggregated object of type ns3::MobilityModel. Thedollar 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 tracesink by calling Config::Connect and passing this namespace path. Oncethis is done, every course change event on node seven will be hooked into ourtrace sink, which will in turn print out the new position.

If you now run the simulation, you will see the course changes displayed asthey happen.

'build' finished successfully (5.989s)
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10, y = 0
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.3841, y = 0.923277
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.2049, y = 1.90708
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.8136, y = 1.11368
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.8452, y = 2.11318
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.9797, y = 3.10409
At time 2s client sent 1024 bytes to 10.1.2.4 port 9
At time 2.01796s server received 1024 bytes from 10.1.3.3 port 49153
At time 2.01796s server sent 1024 bytes to 10.1.3.3 port 49153
At time 2.03364s client received 1024 bytes from 10.1.2.4 port 9
/NodeList/7/$ns3::MobilityModel/CourseChange x = 11.3273, y = 4.04175
/NodeList/7/$ns3::MobilityModel/CourseChange x = 12.013, y = 4.76955
/NodeList/7/$ns3::MobilityModel/CourseChange x = 12.4317, y = 5.67771
/NodeList/7/$ns3::MobilityModel/CourseChange x = 11.4607, y = 5.91681
/NodeList/7/$ns3::MobilityModel/CourseChange x = 12.0155, y = 6.74878
/NodeList/7/$ns3::MobilityModel/CourseChange x = 13.0076, y = 6.62336
/NodeList/7/$ns3::MobilityModel/CourseChange x = 12.6285, y = 5.698
/NodeList/7/$ns3::MobilityModel/CourseChange x = 13.32, y = 4.97559
/NodeList/7/$ns3::MobilityModel/CourseChange x = 13.1134, y = 3.99715
/NodeList/7/$ns3::MobilityModel/CourseChange x = 13.8359, y = 4.68851
/NodeList/7/$ns3::MobilityModel/CourseChange x = 13.5953, y = 3.71789
/NodeList/7/$ns3::MobilityModel/CourseChange x = 12.7595, y = 4.26688
/NodeList/7/$ns3::MobilityModel/CourseChange x = 11.7629, y = 4.34913
/NodeList/7/$ns3::MobilityModel/CourseChange x = 11.2292, y = 5.19485
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10.2344, y = 5.09394
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.3601, y = 4.60846
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.40025, y = 4.32795
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.14292, y = 4.99761
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.08299, y = 5.99581
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.26068, y = 5.42677
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.35917, y = 6.42191
/NodeList/7/$ns3::MobilityModel/CourseChange x = 7.66805, y = 7.14466
/NodeList/7/$ns3::MobilityModel/CourseChange x = 6.71414, y = 6.84456
/NodeList/7/$ns3::MobilityModel/CourseChange x = 6.42489, y = 7.80181