NS2 PROGRAM TUTORIAL FOR WIRED TOPOLOGY

In this section, we are going to develop a Tcl script for ns which simulates a simple topology. You are going to learn how to set up nodes and links, how to send data from one node to another, how to monitor a queue and how to start nam from your simulation script to visualize your simulation.

1. How to start

Now we are going to write a 'template' that you can use for all of the first Tcl scripts. You can write your Tcl scripts in any text editor like joe or emacs. I suggest that you call this first example 'example1.tcl'.

First of all, you need to create a simulator object. This is done with the command

set ns [new Simulator]

Now we open a file for writing that is going to be used for the nam trace data.

set nf [open out.nam w] $ns namtrace-all $nf

The first line opens the file 'out.nam' for writing and gives it the file handle 'nf'. In the second line we tell the simulator object that we created above to write all simulation data that is going to be relevant for nam into this file.

The next step is to add a 'finish' procedure that closes the trace file and starts nam.

proc finish {} { global ns nf $ns flush-trace close $nf exec nam out.nam & exit 0 }

You don't really have to understand all of the above code yet. It will get clearer to you once you see what the code does.

The next line tells the simulator object to execute the 'finish' procedure after 5.0 seconds of simulation time.

$ns at 5.0 "finish"

You probably understand what this line does just by looking at it. ns provides you with a very simple way to schedule events with the 'at' command.

The last line finally starts the simulation.

$ns run

You can actually save the file now and try to run it with 'ns example1.tcl'. You are going to get an error message like 'nam: empty trace file out.nam' though, because until now we haven't defined any objects (nodes, links, etc.) or events. You will have to use the code from this section as starting point in the other sections. 

You can download it from here.

2. Two nodes, one link

In this section we are going to define a very simple topology with two nodes that are connected by a link. The following two lines define the two nodes. (Note: You have to insert the code in this section before the line '$ns run', or even better, before the line '$ns at 5.0 "finish"').

set n0 [$ns node] set n1 [$ns node]

A new node object is created with the command '$ns node'. The above code creates two nodes and assigns them to the handles 'n0' and 'n1'.

The next line connects the two nodes.

$ns duplex-link $n0 $n1 1Mb 10ms DropTail

This line tells the simulator object to connect the nodes n0 and n1 with a duplex link with the bandwidth 1Megabit, a delay of 10ms and a DropTail queue.

Now you can save your file and start the script with 'ns example1.tcl'. nam will be started automatically and you should see an output that resembles the picture below.

You can download the complete example here if it doesn't work for you and you think you might have made a mistake.

3. Sending data

Of course, this example isn't very satisfying yet, since you can only look at the topology, but nothing actually happens, so the next step is to send some data from node n0 to node n1. In ns, data is always being sent from one 'agent' to another. So the next step is to create an agent object that sends data from node n0, and another agent object that receives the data on node n1.

#Create a UDP agent and attach it to node n0 set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 # Create a CBR traffic source and attach it to udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 set packetSize_ 500 $cbr0 set interval_ 0.005 $cbr0 attach-agent $udp0

These lines create a UDP agent and attach it to the node n0, then attach a CBR traffic generator to the UDP agent. CBR stands for 'constant bit rate'. Line 7 and 8 should be self-explaining. The packet Size is being set to 500 bytes and a packet will be sent every 0.005 seconds (i.e. 200 packets per second). 

The next lines create a Null agent which acts as traffic sink and attach it to node n1.

set null0 [new Agent/Null]  $ns attach-agent $n1 $null0

Now the two agents have to be connected with each other.

$ns connect $udp0 $null0

And now we have to tell the CBR agent when to send data and when to stop sending. Note: It's probably best to put the following lines just before the line '$ns at 5.0 "finish"'.

$ns at 0.5 "$cbr0 start" $ns at 4.5 "$cbr0 stop"

This code should be self-explaining again.

Now you can save the file and start the simulation again. When you click on the 'play' button in the nam window, you will see that after 0.5 simulation seconds, node 0 starts sending data packets to node 1. You might want to slow nam down then with the 'Step' slider.

I suggest that now you start some experiments with nam and the Tcl script. You can click on any packet in the nam window to monitor it, and you can also click directly on the link to get some graphs with statistics. I also suggest that you try to change the 'packetsize_' and 'interval_' parameters in the Tcl script to see what happens. 

You can download the full example here.

4. The topology

As always, the first step is to define the topology. You should create a file 'example2.tcl', using the code from section 1 as a template. As I said before, this code will always be similar. You will always have to create a simulator object, you will always have to start the simulation with the same command, and if you want to run nam automatically, you will always have to open a trace file, initialize it, and define a procedure which closes it and starts nam.

Now insert the following lines into the code to create four nodes.

set n0 [$ns node] set n1 [$ns node] set n2 [$ns node] set n3 [$ns node]

The following piece of Tcl code creates three duplex links between the nodes.

$ns duplex-link $n0 $n2 1Mb 10ms DropTail $ns duplex-link $n1 $n2 1Mb 10ms DropTail $ns duplex-link $n3 $n2 1Mb 10ms DropTail

You can save and start the script now. You might notice that the topology looks a bit awkward in nam. You can hit the 're-layout' button to make it look better, but it would be nice to have some more control over the layout. Add the next three lines to your Tcl script and start it again.

$ns duplex-link-op $n0 $n2 orient right-down $ns duplex-link-op $n1 $n2 orient right-up $ns duplex-link-op $n2 $n3 orient right

You will probably understand what this code does when you look at the topology in the nam window now. It should look like the picture below.

Note that the autolayout related parts of nam are gone, since now you have taken the layout into your own hands. The options for the orientation of a link are right, left, up, down and combinations of these orientations. You can experiment with these settings later, but for now please leave the topology the way it is.

5. The events

Now we create two UDP agents with CBR traffic sources and attach them to the nodes n0 and n1. Then we create a Null agent and attach it to node n3.

#Create a UDP agent and attach it to node n0 set udp0 [new Agent/UDP] $ns attach-agent $n0 $udp0 # Create a CBR traffic source and attach it to udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 set packetSize_ 500 $cbr0 set interval_ 0.005 $cbr0 attach-agent $udp0 #Create a UDP agent and attach it to node n1 set udp1 [new Agent/UDP] $ns attach-agent $n1 $udp1 # Create a CBR traffic source and attach it to udp1 set cbr1 [new Application/Traffic/CBR] $cbr1 set packetSize_ 500 $cbr1 set interval_ 0.005 $cbr1 attach-agent $udp1 set null0 [new Agent/Null] $ns attach-agent $n3 $null0

The two CBR agents have to be connected to the Null agent.

$ns connect $udp0 $null0 $ns connect $udp1 $null0

We want the first CBR agent to start sending at 0.5 seconds and to stop at 4.5 seconds while the second CBR agent starts at 1.0 seconds and stops at 4.0 seconds.

$ns at 0.5 "$cbr0 start" $ns at 1.0 "$cbr1 start" $ns at 4.0 "$cbr1 stop" $ns at 4.5 "$cbr0 stop"

When you start the script now with 'ns example2.tcl', you will notice that there is more traffic on the links from n0 to n2 and n1 to n2 than the link from n2 to n3 can carry. A simple calculation confirms this: We are sending 200 packets per second on each of the first two links and the packet size is 500 bytes. This results in a bandwidth of 0.8 megabits per second for the links from n0 to n2 and from n1 to n2. That's a total bandwidth of 1.6Mb/s, but the link between n2 and n3 only has a capacity of 1Mb/s, so obviously some packets are being discarded. But which ones? Both flows are black, so the only way to find out what is happening to the packets is to monitor them in nam by clicking on them. In the next two sections I'm going to show you how to distinguish between different flows and how to see what is actually going on in the queue at the link from n2 to n3.

6. Marking flows

Add the following two lines to your CBR agent definitions.

$udp0 set class_ 1 $udp1 set class_ 2

The parameter 'fid_' stands for 'flow id'.

Now add the following piece of code to your Tcl script, preferably at the beginning after the simulator object has been created, since this is a part of the simulator setup.

$ns color 1 Blue $ns color 2 Red

This code allows you to set different colors for each flow id.

Now you can start the script again and one flow should be blue, while the other one is red. Watch the link from node n2 to n3 for a while, and you will notice that after some time the distribution between blue and red packets isn't too fair anymore (at least that's the way it is on my system). In the next section I'll show you how you can look inside this link's queue to find out what is going on there.

7. Monitoring a queue

You only have to add the following line to your code to monitor the queue for the link from n2 to n3.

$ns duplex-link-op $n2 $n3 queuePos 0.5

Start ns again and you will see a picture similar to the one below after a few moments.

You can see the packets in the queue now, and after a while you can even see how the packets are being dropped, though (at least on my system, I guess it might be different in later or earlier releases) only blue packets are being dropped. But you can't really expect too much 'fairness' from a simple DropTail queue. So let's try to improve the queueing by using a SFQ (stochastic fair queueing) queue for the link from n2 to n3. Change the link definition for the link between n2 and n3 to the following line.

$ns duplex-link $n3 $n2 1Mb 10ms SFQ

The queueing should be 'fair' now. The same amount of blue and red packets should be dropped.

You can download the full example here.

8. Creating a larger topology

I suggest you call the Tcl script for this example 'example3.tcl'. You can already insert  template from section 1 into the file.

As always, the topology has to be created first, though this time we take a different approach which you will find more comfortable when you want to create larger topologies. The following code creates seven nodes and stores them in the array n().

for {set i 0} {$i < 7} {incr i} { set n($i) [$ns node] }

You have certainly seen 'for' loops in other programming languages before, and I am sure you understand the structure at once. Note that arrays, just like other variables in Tcl, don't have to be declared first.

Now we're going to connect the nodes to create a circular topology. The following piece of code might look a bit more complicated at first.

for {set i 0} {$i < 7} {incr i} { $ns duplex-link $n($i) $n([expr ($i+1)%7]) 1Mb 10ms DropTail }

This 'for' loop connects all nodes with the next node in the array with the exception of the last node, which is being connected with the first node. To accomplish that, I used the '%' (modulo) operator.

When you run the script now, the topology might look a bit strange in nam at first, but after you hit the 're-layout' button it should look like the picture below.

9. Link failure

The next step is to send some data from node n(0) to node n(3).

#Create a UDP agent and attach it to node n(0) set udp0 [new Agent/UDP] $ns attach-agent $n(0) $udp0 # Create a CBR traffic source and attach it to udp0 set cbr0 [new Application/Traffic/CBR] $cbr0 set packetSize_ 500 $cbr0 set interval_ 0.005 $cbr0 attach-agent $udp0 set null0 [new Agent/Null] $ns attach-agent $n(3) $null0 $ns connect $udp0 $null0 $ns at 0.5 "$cbr0 start" $ns at 4.5 "$cbr0 stop"

The code above should look familiar to you by now. The only difference to the last sections is that now we have to use the node array elements.

If you start the script, you will see that the traffic takes the shortest path from node 0 to node 3 through nodes 1 and 2, as could be expected. Now we add another interesting feature. We let the link between node 1 and 2 (which is being used by the traffic) go down for a second.

$ns rtmodel-at 1.0 down $n(1) $n(2) $ns rtmodel-at 2.0 up $n(1) $n(2)

It is probably not too hard to understand these two lines. Now you can start the script again and you will see that between the seconds 1.0 and 2.0 the link will be down, and all data that is sent from node 0 is lost.

Now I will show you how to use dynamic routing to solve that 'problem'. Add the following line at the beginning of your Tcl script, after the simulator object has been created.

$ns rtproto DV

Start the simulation again, and you will see how at first a lot of small packets run through the network. If you slow nam down enough to click on one of them, you will see that they are 'rtProtoDV' packets which are being used to exchange routing information between the nodes. When the link goes down again at 1.0 seconds, the routing will be updated and the traffic will be re-routed through the nodes 6, 5 and 4.

You can download the full example here.