Intelligent Wireless Network Group Department of Computer Engineering Faculty of Engineering, Kasetsart University http://iwing.cpe.ku.ac.

th

ns-3 Tutorial (Part IV) Wireless & Tracing System and Visualizing Results
JCSSE 2011's tutorials and workshops Wednesday, 11 May 2011, 9:00 - 16:00

Time Table

09:00 - 10:15 ns-3 Introduction & Installation 10:15 - 10.30 Break 10:30 - 12:00 Hands-On: Point-to-point and CSMA (Ethernet) 12:00 - 13:00 Lunch 13:00 - 14:15 Hands-On: Wireless & Tracing System and Visualizing Results 14:15 - 14:30 Break 14:30 - 15:30 Demonstation: ns-3 protocol stack modification 15:30 - 16:00 Q&A

Outline

Wireless modules overview Tracing with Trace Helpers Creating custom tracers Visualizing and analyzing results Walk-through examples Hands-on exercise

Tracing Overview

ns-3 provides a set of pre-congured trace sources Users provide trace sinks and attach to the trace source Multiple trace sources can connect to a trace sink

ns-3 Tracing Model

Decouple trace sources from trace sinks:

ns-3 Trace Sources

Multiple Levels of Tracing

High-level

Use a helper to hook a predefined trace source to an existing trace sink (e.g., ascii, pcap) Hook an existing trace source to a custom trace sink Add a new trace source and connect it to a special trace sink

Mid-level

Low-level

Trace Helpers

Ascii Trace Helper Pcap Trace Helper

Custom Trace Sink

void DevTxTrace( std::string context, Ptr<const Packet> p, Mac48Address address) { std::cout << " TX to=" << address << " p: " << *p << std::endl; } : Config::Connect( "/NodeList/*/DeviceList/*/Mac/MacTx", MakeCallback(&DevTxTrace));

Path to trace source

Name of trace sink function

Walk-Through Example I (1)

Task: model the network topology below in ns-3 and capture ECHO packets transmitted from N7 to N4
N2 N0 N5 N3 N4 N1

10.1.1.0/24

10.1.2.0/24 ECHO 10.1.3.0/24

N6

N7

We can start from tutorials/third.cc

10

Dissecting third.cc

CommandLine class allows processing of command-line arguments

Supply default values of various attributes and variables

main (int argc, char *argv[]) { 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);

11

Dissecting third.cc

Various Helpers are available to help create wireless channel/physical/mac models

NodeContainer wifiStaNodes; wifiStaNodes.Create (nWifi); NodeContainer wifiApNode = p2pNodes.Get (0); YansWifiChannelHelper channel = YansWifiChannelHelper::Default (); YansWifiPhyHelper phy = YansWifiPhyHelper::Default (); phy.SetChannel (channel.Create ()); WifiHelper wifi = WifiHelper::Default (); wifi.SetRemoteStationManager ("ns3::AarfWifiManager");

12

Dissecting third.cc

WiFi MAC layer

NodeContainer wifiApNode = p2pNodes.Get (0); NqosWifiMacHelper mac = NqosWifiMacHelper::Default (); Ssid ssid = Ssid ("ns-3-ssid"); mac.SetType ("ns3::StaWifiMac", "Ssid", SsidValue (ssid), "ActiveProbing", BooleanValue (false)); NetDeviceContainer staDevices; staDevices = wifi.Install (phy, mac, wifiStaNodes); mac.SetType ("ns3::ApWifiMac", "Ssid", SsidValue (ssid)); NetDeviceContainer apDevices; apDevices = wifi.Install (phy, mac, wifiApNode);

Configure all nodes in wifiStaNodes container to be of type station

Configure first node of point-to-point link to be WiFi AP

13

Dissecting third.cc

All wireless nodes must be associated with mobility MobilityHelper provides a lot of help
(MinX, MinY)
MobilityHelper mobility; mobility.SetPositionAllocator ("ns3::GridPositionAllocator", DeltaY "MinX", DoubleValue (0.0), "MinY", DoubleValue (0.0), 4 "DeltaX", DoubleValue (5.0), "DeltaY", DoubleValue (10.0), "GridWidth", UintegerValue (3), "LayoutType", StringValue ("RowFirst"));

DeltaX

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

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

14

Walk-Through Example I (2)

Create a copy of third.cc into the scratch dir and rename it to pm-ex1.cc
$ cp examples/tutorials/third.cc scratch/pm-ex1.cc

Edit the source

Change port number from 9 to 7 (standard ECHO port)

UdpEchoServerHelper echoServer (7); : UdpEchoClientHelper echoClient (csmaInterfaces.GetAddress (nCsma), 7);

Change PCAP file prefix to pm-ex1

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

15

Walk-Through Example I (3)

Run the script

$ ./waf --run pm-ex1

Open the pcap files with WireShark

$ ls *.pcap pm-ex1-0-0.pcap pm-ex1-0-1.pcap pm-ex1-1-0.pcap pm-ex1-1-1.pcap $ wireshark pm-ex1-0-0.pcap

16

Walk-Through Example I (4)

Visualize the simulation by adding option --visualize

$ ./waf --run pm-ex1 --visualize

Press F3 to start the simulation

17

Walk-Through Example I (5)

Attributes can be configured and explored before the simulation starts

#include "ns3/gtk-config-store.h"
GtkConfigStore config; config.ConfigureAttributes(); Simulator::Run ();

18

Walk-Through Example I (6)

GtkConfigStore can also be invoked in PyViz using Ipython shell

Ipython must be installed

19

Walk-Through Example II (1)

Task: Using the previous topology, replace ECHO traffic with CBR (Constant Bit Rate) traffic
N2 N0 N3 N4

10.1.1.0/24

N1

N5

10.1.2.0/24 CBR (512 Kbps) 10.1.3.0/24

N6

N7

20

Walk-Through Example II (2)

Create pm-ex2.cc from pm-ex1.cc

$ cp scratch/pm-ex1.cc scratch/pm-ex2.cc

Use OnOffHelper to generate CBR traffic from the client

uint16_t port = 9; OnOffHelper onoff( "ns3::UdpSocketFactory", InetSocketAddress("10.1.2.4", port)); onoff.SetAttribute("OnTime", StringValue("Constant:1")); onoff.SetAttribute("OffTime", StringValue("Constant:0")); onoff.SetAttribute("DataRate", StringValue("512Kbps")); onoff.SetAttribute("PacketSize", StringValue("512"));

Install app on node N7 only

ApplicationContainer apps = onoff.Install(wifiStaNodes.Get(nWifi-1)); apps.Start(Seconds(5.0)); apps.Stop(Seconds(20.0));

21

Walk-Through Example II (3)

Create a packet sink on the server

PacketSinkHelper sink( "ns3::UdpSocketFactory", InetSocketAddress("10.1.2.4", port)); sink.Install(csmaNodes.Get(nCsma));
Install PacketSink on node N4

Set simulation time to 30 seconds

Simulator::Stop(Seconds(25.0));

Don't forget to change the PCAP trace prefix

22

Walk-Through Example III (1)

Task: calculate average throughput from previous scenario Idea:

Connect a custom trace sink to PacketSink's Rx trace source Compute average throughput from first and last packets' timestamps total bytes received

23

Finding Path to Trace Source

How to determine what trace source PacketSink provides?

And how to get to it?

In ns-3 Doxygen, look for ns3::PacketSink (either via Class List or List of Trace Sources)

Look at the documentation for GetTypeId

24

Connecting Trace Source/Sink

We now know that PacketSink object already comes with a trace source, called Rx We need to write a callback function to serve as a trace sink
PacketSink Object Trace Source

Trace Sink Callback Function

25

Callback Signature

Quoted from ns-3 Tutorial:

always try to copy someone else's working code

$ find examples/ -name "*.cc" -exec grep -H PacketSink/Rx {} \; examples/csma/csma-ping.cc: Config::ConnectWithoutContext ("/NodeList/3/ApplicationList/0/$ns3::PacketSink/Rx", examples/csma/csma-packet-socket.cc: Config::Connect ("/NodeList/*/ApplicationList/*/$ns3::PacketSink/Rx", examples/csma/csma-raw-ip-socket.cc: Config::ConnectWithoutContext ("/NodeList/3/ApplicationList/0/$ns3::PacketSink/Rx", : :

Opening examples/csma/csma-ping.cc reveals

Config::ConnectWithoutContext ("/NodeList/3/ApplicationList/0/$ns3::PacketSink/Rx", MakeCallback (&SinkRx));

Then look at definition of SinkRx function:

static void SinkRx (Ptr<const Packet> p, const Address &ad) { //std::cout << *p << std::endl; }

26

Callback Signature

If no example can be found, look at ns-3 source code!

$ find . -name "*.h" -exec grep -H TracedCallback {} \; : ./src/applications/udp-echo/udp-echo-client.h: TracedCallback<Ptr<const Packet> > m_txTrace; ./src/applications/v4ping/v4ping.h: TracedCallback<Time> m_traceRtt; ./src/applications/packet-sink/packet-sink.h: TracedCallback<Ptr<const Packet>, const Address &> m_rxTrace; ./src/mobility/mobility-model.h: TracedCallback<Ptr<const MobilityModel> > m_courseChangeTrace; ./src/routing/olsr/model/olsr-routing-protocol.h: TracedCallback <const PacketHeader &, :

Either way, we now know that our callback's signature should be:
void Callback(Ptr<const Packet>, const Address &)

Note: An additional std::string parameter is required if connection is made with context

27

Walk-Through Example III (2)

Create pm-ex3.cc from pm-ex2.cc

$ cp scratch/pm-ex2.cc scratch/pm-ex3.cc

Prepare trace sink callback and necessary statistical variables

double firstRxTime = -1.0, lastRxTime; uint32_t bytesTotal = 0; void SinkRxTrace(Ptr<const Packet> pkt, const Address &addr) { if (firstRxTime < 0) firstRxTime = Simulator::Now().GetSeconds(); lastRxTime = Simulator::Now().GetSeconds(); bytesTotal += pkt->GetSize(); }

28

Walk-Through Example III (3)

Connect trace source with trace sink

Config::ConnectWithoutContext( "/NodeList/*/ApplicationList/*/$ns3::PacketSink/Rx", MakeCallback(&SinkRxTrace));

Produce statistical report at the end of the script

cout << "Avg throughput = " << bytesTotal*8/(lastRxTime-firstRxTime)/1024 << " kbits/sec" << endl;

Run the simulation script

29

Walk-Through Example IV (1)

Task: study impact of number of clients on average throughput Experiment setup

2-14 mobile clients UDP CBR stream

512 Kbps per client Packet size: 512 bytes

30

Walk-Through Example IV (2)

Create pm-ex4.cc from pm-ex3.cc

$ cp scratch/pm-ex3.cc scratch/pm-ex4.cc

Modify the source so that OnOff application is installed on all WiFi stations

Change the line: to

ApplicationContainer apps = onoff.Install(wifiStaNodes.Get(nWifi-1));

ApplicationContainer apps = onoff.Install(wifiStaNodes);

31

Walk-Through Example IV (3)

Report the number of WiFi stations in addition to the average throughput

cout << << << << "Num clients = " << nWifi << " " "Avg throughput = " bytesTotal*8/(lastRxTime-firstRxTime)/1024 " kbits/sec" << endl;

Try running the script with various values specified for nWifi argument suppress stderr
messages

$ waf --run Num clients $ waf --run Num clients

"pm-ex4 = 1 Avg "pm-ex4 = 2 Avg

--nWifi=1" throughput --nWifi=2" throughput

2> /dev/null = 512.96 kbits/sec 2> /dev/null = 1025.54 kbits/sec

32

Walk-Through Example IV (4)

Create a shell-script, named run-all.sh, that runs the simulation with different values for nWifi
#!/bin/bash for ((i=2; i<=14; i += 2)); do waf --run "pm-ex4 --nWifi=$i" done

Run the shell-script and redirect all stdout messages to a file

$ bash run-all.sh > results.dat

33

Walk-Through Example IV (5)

Visualize results with gnuplot

$ gnuplot gnuplot> plot 'results.dat' using 4:8 with lines

34

Walk-Through Example IV (6)

Create a script, genplot.gnuplot, for generating a plot as a PNG file Also

Change x-axis to load, Polish the plot: turn on grid, turn off legend
#!/usr/bin/gnuplot set terminal png set output 'graph.png' set xrange [0:] set yrange [0:] set xlabel 'Load (kb/s)' set ylabel 'Average Throughput (kb/s)' set grid plot 'results.dat' using ($4*512):8 with lines notitle

35

Walk-Through Example IV (7)

Run the plotting script

$ gnuplot genplot.gnuplot

36

Running Multiple Replications

Publication-quality results should be obtained from many replications in each scenario

Use --RngRun=<run-number> to change random sequence

$ waf --run "pm-ex4 --nWifi=10 --RngRun=3"

37

Hands-on Exercise

Study impact of number of mobile stations to packet delivery ratio

38