[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 Building a Bus Network Topology

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

The 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 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 examples directory. This script builds on the first.cc script and adds a CSMA network to the point-to-point simulation we've already considered. Go ahead and open examples/second.cc in your favorite editor. You will have already seen enough 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 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 thee "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

The actual code begins by loading module include files just as was done in the first.cc example. 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.

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

The main program begins by enabling the UdpEchoClientApplication and UdpEchoServerApplication logging components at INFO level so we can see some output when we run the example. This should be entirely familiar to you so far.

  int
  main (int argc, char *argv[])
  {
    LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
    LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);

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.

  uint32_t nCsma = 3;
  CommandLine cmd;
  cmd.AddValue ("nCsma", "Number of \"extra\" CSMA nodes/devices", nCsma);
  cmd.Parse (argc,argv);

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

  NodeContainer p2pNodes;
  p2pNodes.Create (2);

Next, we delare another NodeContainer to hold the nodes that will be part of the bus (CSMA) network. First, we just instantiate the container object 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 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.

The next bit of code should be quite familiar by now. We instantiate a 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.

  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 the point-to-point net devices and we 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 CsmaHelper works just like a PointToPointHelper, but it creates and connects CSMA devices and channels.

  CsmaHelper csma;

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

Just as we created a NetDeviceContainer to hold the devices created by the PointToPointHelper we create a NetDeviceContainer to hold the devices created by our CsmaHelper. We call the Install method of the CsmaHelper to install the devices into the nodes of the csmaNodes NodeContainer.

We now have our nodes, devices and channels created, but we have no protocol stacks present. Just as in the first.cc script, we will use the InternetStackHelper 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 and added it to the csmaNodes container. Thus we only need to install the stacks on the remaining p2pNodes node, and all of the nodes in the csmaNodes container to cover all of the nodes in the simulation.

Just as in the first.cc example script, we are going to use the 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.

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

  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 is going to be fundamentally similar to the applications section of 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 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 SetAttribute method if desired, but we require it to be provided to the 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 the nodes 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 of the 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 csmaNodes container. By induction, if we create nCsma "extra" nodes the last one will be at index nCsma. You see this exhibited in the Get of the first line of code.

The client application is set up exactly as we did in the first.cc example script. Again, we provide required attributes to the 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.

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

Since we have actually built an internetwork here, we need some form of internetwork routing. 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:

  GlobalRouteManager::PopulateRoutingTables ();

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.

    PointToPointHelper::EnablePcapAll ("second");
    CsmaHelper::EnablePcapAll ("second");
  
    Simulator::Run ();
    Simulator::Destroy ();
    return 0;
  }

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

  cp examples/second.cc scratch/
  ./waf
  ./waf --run scratch/second

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

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

Recall that the first message, 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, Received 1024 bytes from 10.1.1.1, 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, 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:

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

Let's take a moment to look at the naming of these files. They all have the same form, <name>-<node>-<device>.pcap. For example, the first file in the listing is 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 second-1-0.pcap and 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.

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

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:

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

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.

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

As you can see, the link type is now "Ethernet." Something new has appeared, though. The bus network needs 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,

  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

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,

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

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:

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

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 first.cc example. Try setting the number of "extra" devices to four:

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

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 scratch/second.cc and add that code enabling us to be more specific. The file we provided used the EnablePcapAll methods of the helpers to enable pcap on all devices. We now want to use the more specific method, EnablePcap, which takes a node number and device number as parameters. Go ahead and replace the EnablePcapAll calls with the calls below.

  PointToPointHelper::EnablePcap ("second", p2pNodes.Get (0)->GetId (), 0);
  CsmaHelper::EnablePcap ("second", csmaNodes.Get (nCsma)->GetId (), 0);

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 nCsma + 1. This approach can become annoyingly difficult in larger simulations.

An alternate way, which we use here, is to realize that the NodeContainers contain pointers to ns-3 Node Objects. The Node Object has a method called 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 Node and locate that method, which is further down in the 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 Node documentation by looking through at the "Classes" tab and scrolling down the "Class List" until you find ns3::Node. Select ns3::Node and you will be taken to the documentation for the Node class. If you now scroll down to the GetId method and select it, you will be taken to the detailed documentation for the method. Using the 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 nCsma to 100, you will see the following output:

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

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,

  ~/repos/ns-3-dev > ls *.pcap
  second-0-0.pcap  second-101-0.pcap
  ~/repos/ns-3-dev >

you will see that we have, in fact, only created two trace files. The trace file second-0-0.pcap is the "leftmost" point-to-point device which is the echo packet source. The file second-101-0.pcap corresponds to the rightmost CSMA device which is where the echo server resides.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated on September, 23 2008 using texi2html 1.76.