We assume you have a thorough knowledge of C++ and computer networks. Especially, for understanding Wi-Fi and LTE/4G simulations, we assume you have a basic knowledge of Wi-Fi and LTE technologies. We also recommend you revise basic network socket programming and Unix or Linux operating system commands before using the ns-3 simulator. In this book, ns-3 is set up in the working environment shown in the following table:

There are many network simulation tools available as open source and proprietary solutions. In comparison to ns-2 and other simulation tools, ns-3 offers the following features:

• The primary changes ns-2 users observe with ns-3 is the scripting language. Also, ns-2 support is limited to simple wired and Wi-Fi network simulation only.
• ns-2 programs are written in Object-oriented Tool Command Language (OTcl), whereas ns-3 programs are written in C++ or Python.
• ns-3 is open source software and has excellent support from the ns-3 team.
• ns-3 is designed as a set of modules (internet, Wi-Fi, LTE, etc.) and users can extend existing modules and add new modules.
• ns-3 is designed to be used in the command line as well as visualization mode.
• ns-3 can be easily extended with data analysis and visualization tools.
• ns-3 can be used on Linux, macOS, or Microsoft Windows operating systems.

In this section, you will start with the first hands-on task, which is installing ns-3 successfully. Let’s start by installing all necessary dependencies for ns-3:

1. Install the core dependencies for ns-3 build essentials and compilation packages:

   sudo apt-get update
   sudo apt install build-essential libsqlite3-dev libboost-all-dev libssl-dev git python3-setuptools castxml

2. Install the Python dependencies for ns-3 Python bindings:

   sudo apt install gir1.2-goocanvas-2.0 gir1.2-gtk-3.0 libgirepository1.0-dev python3-dev python3-gi python3-gi-cairo python3-pip python3-pygraphviz python3-pygccxml

3. Install the dependencies for ns-3 features support, such as NetAnimator, gdb, and valgrind:

   sudo apt install g++ pkg-config sqlite3 qt5-default mercurial ipython3 openmpi-bin openmpi-common openmpi-doc libopenmpi-dev autoconf cvs bzr unrar gdb valgrind uncrustify doxygen graphviz imagemagick python3-sphinx dia tcpdump libxml2 libxml2-dev cmake libc6-dev libc6-dev-i386 libclang-6.0-dev llvm-6.0-dev automake

Next, download the latest ns-3 version and follow the steps for installing it:

$ wget -c https://www.nsnam.org/releases/ns-allinone-3.36.tar.bz2

4. Unzip or extract the downloaded file:

   $ tar -xvjf ns-allinone-3.36.tar.bz2

5. Move to the following directory:

   $ cd ns-allinone-3.36/ns-3.36

6. Next, configure the ns-3 modules using the build system. The ns3 command (available in the ns-allinone-3.36/ns-3.36 folder) makes use of a Python wrapper around CMake. It is similar to Waf in earlier ns-3 versions. The following command configures ns-3 modules with all example and test simulation programs:

   $ ./ns3 configure --enable-examples --enable-tests

After running this command, you can verify the list of modules configured in Figure 1.1:

Figure 1.1 – The list of ns-3 modules configured

7. Next, build all the configured ns-3 modules using the following command. This command takes a while to complete:

   $ ./ns3 build

After executing the command, we can observe the list of modules linking successfully, as shown in Figure 1.2:

Figure 1.2 – ns-3 build process

8. Finally, you can check your installation by running all unit test cases provided in ns-3 modules:

   $ ./test.py

After executing this command, all test cases should either pass or be skipped. Then, a successfully installed NS-3.36 simulator is available (refer to Figure 1.3):

Figure 1.3 – ns-3 test cases execution

9. After the successful build of ns-3, you have many example simulation programs ready to execute. Try running a first example simulation with the following command and observe the output:

   $ ./ns3 run first

Now, we are executing an example ns-3 simulation, first.cc. Refer to the execution results in Figure 1.4:

Figure 1.4 – The first.cc simulation execution results

Congratulations! We have installed ns-3 successfully and tested a sample simulation. In the next section, we are going to learn how to write an ns-3 simulation program easily using Code::Blocks editor features. Thanks to the entire ns-3 team for providing detailed documentation on their website (https://www.nsnam.org) related to installing ns-3 with all features, tutorials, examples, and designs of various modules. We recommend you to go through the website for more details.

After installing ns-3, the most exciting task is writing the first simulation program. Thanks to ns-3 for providing various tutorials and example programs in various modules. We strongly recommend ns-3 beginners start by copying the example programs and understanding their source code using editors such as Code::Blocks and Visual Studio. This will help users to understand key packages, classes, fields, and member functions used in various programs. Moreover, while writing or editing programs, the IntelliSense features of the editors will help users to learn all the basic and unique features supported by ns-3 classes such as fields, constructors, member functions, attributes, callbacks, and trace sources. Hence, users can write their simulation programs easily and quickly by using the IntelliSense and auto-completion features of the editors. It saves a lot of time for users as they can use classes and all its features without searching the internet, ns-3 documentation, and example programs thoroughly. ns-3 offers support for the following editors, based on operating system: Code::Blocks for Ubuntu and Visual Studio for Windows. In this book, we use the Code::Blocks editor.

Installing and configuring Code::Blocks for ns-3

Let’s start by installing Code::Blocks and creating an ns-3 Code::Blocks project:

$ apt-get install codeblocks

By default, the Code::Blocks editor does not support ns-3 projects. Hence, it is necessary to create a ns-3 Code::Blocks project using the following command from the ns-3 installed directory (ns-allinone3.36/ns-3.36):

$./ns3 configure -G"CodeBlocks - Unix Makefiles" --enable-examples

The preceding command creates an NS3.cbp Code::Blocks project file inside cmake-cache. This is a Code::Blocks project file that can be opened by the IDE. Now, open the Code::Blocks editor. Then, move to File | Open | ns-allinone3.36 | ns-3.36 | cmake-cache and select the NS3.cbp file. It opens the NS3 project, as shown in Figure 1.5:

Figure 1.5 – The ns-3 project opens in the Code::Blocks editor

Next, quickly check the project properties to run a sample first simulation. It opens the window shown in Figure 1.6. In the window, no project settings need to be changed but make sure you check the Build targets tab. Under the selected Build targets options panel, select the Type drop-down menu, then select Console application and click OK.

Figure 1.6 – The Code::Blocks project properties window

Next, execute a first.cc simulation. Go to the Build menu, then Select target. It opens the following window (refer to Figure 1.7). Type scrach_first to run your first simulation. Select the Run button from the editor to execute the first simulation:

Figure 1.7 – The Code::Blocks window to select a target for execution

By clicking on the Run button, it successfully executes the first simulation, as shown in Figure 1.8. It displays output in a new window. This was just a demonstration of how to select a simulation program from the Code::Blocks editor and execute it:

Figure 1.8 – The first.cc simulation execution results

Next, we are going to explore the ns-3 module’s source code using the Code::Blocks editor.

Exploring various ns-3 modules’ source code

Under the Code::Blocks editor Workspace, you can see NS3 project folders (refer to Figure 1.9). Select Sources and traverse to the src folder. Then, you can see the following ns-3 modules list, including antenna, aodv, and applications:

Figure 1.9 – The Code::Blocks editor Workspace

In ns-3, every module implementation follows a hierarchy. For an example, we will explore the lte module and its underlying folders (refer to Figure 1.10):

Figure 1.10 – An ns-3 example module (lte) and its common folders

As we can observe, there are four folder names – examples, helper, model, and test:

• The model folder contains all LTE protocols’, architecture’s, interfaces’, and algorithms’ source code. Developers can explore the model folder and its source files to make changes in LTE core-level source code. For example, developers use lte-enb-mac.cc to change any LTE base station (BS)’s medium access control (MAC) protocol changes.
• The examples folder contains sample LTE simulation programs, which can be used by end users to understand how to write LTE simulations. For example, users can explore lena-x2-handover.cc to understand how to write a mobility scenario in LTE networks.
• The helper folder contains source code useful for setting up simulation programs. To set up LTE network simulation, end users use helper classes of lte-helper.cc and epc-helper.cc. Usually, the helper folder contains all helper classes for setting up network architectures, interfaces, and protocols.
• The test folder contains the source code of various unit test cases for the module. For example, the lte test folder contains all of the various test programs for checking LTE nodes’ behavior, protocols, interfaces, and algorithms.

All ns-3 modules follow the same folder hierarchy. Hence, it is important for developers and users to understand its hierarchy to make any changes.

Next, we’ll see how the Code::Blocks editor is useful for writing ns-3 simulation programs. The Code::Blocks IntelliSense and auto-completion features are also available for ns-3 programs as they are for C++ programs. Let’s open first.cc and see how useful the Code::Blocks editor is for making any changes or writing new lines of code. As we are new to ns-3 programming, it is important to understand and remember various classes’ syntax and semantics. Using a regular editor will not help you in terms of auto code completion and IntelliSense features. As ns-3 is configured as a Code::Blocks project, it is possible to use Code::Blocks editor features to write ns-3 programs like C or C++ programs.

You can use the auto code completion feature by typing the first few characters of an ns-3 class, field, or member function. For example, if you type NodeC, the editor will suggest the NodeContainer class. More importantly, due to the IntelliSense feature, we can view a complete description of any class (refer to Figure 1.11), field, or member function before including it in our code:

Figure 1.11 – Inspect the ns-3 NodeContainer class

For example, while typing NodeC, it opens a class description in a window. We can click Open declaration to see the entire class definition or we can scroll down the window to see its members, fields, iterators, constructors, attributes, and so on. As a beginner, it is difficult to write an ns-3 program from scratch, hence we recommend that you use example programs, understand them, and modify them using Code::Blocks or any ns-3-supported editor.

That’s great. We have learned how to integrate ns-3 as a Code::Blocks project and explored ns-3 modules’ source code structure. In the next section, we will start understanding an ns-3 simulation program’s structure to write simulation programs.

Before writing any simulation program, it is important to understand the ns-3 simulation program structure. By doing so, it is possible to avoid common mistakes and save a lot of time in debugging your simulation issues. Here, we describe how to create the basic and advanced ns-3 simulation program structures, as follows:

1. Import all necessary ns-3 packages.
2. Define the logging component for your program. Your simulation program allows you to include necessary log statements, such as information, warnings, errors, exceptions, assertions, and debug details. While running a simulation, you can enable or disable any of the log statements.
3. Set up a simulation topology and configure it. Before writing your simulation program, it is recommended to draw your simulation network topology:
   1. Create nodes using the ns-3 NodeContainer class. In ns-3, hosts and other network equipment are referred to as nodes, and users can install the necessary protocols to configure them as a specific piece of networking equipment. Identify the type of nodes, such as hosts, routers, switches, access points (APs), and BSs, involved in your topology and create the necessary number of nodes for each type using the ns-3 NodeContainer class.
   2. Connect nodes using suitable communication channels and install the necessary communication protocols to get the NetDevices (network interface cards (NIC)) associated with the nodes. For example, you'll need to collect the necessary wired or wireless/mobile network devices using the ns-3 NetDeviceContainer class.
   3. Install the Transmission Control Protocol (TCP)/Internet Protocol (IP) on nodes using the ns-3 InternetStackHelper class. Hence, we can assign IP addresses and install routing protocols.
   4. Configure IP addresses. We need to identify and create types of network addresses as required by setting suitable network IDs and subnet masks. Then, we can configure the respective IP address to respective NetDevices using the ns-3 NetDeviceContainer class.
   5. Configure routing protocols to interconnect different networks involved in your topology.
4. Next, identify the necessary network applications to install and run on various nodes:
   1. Identify on which nodes you need to install your client or server applications, then configure suitable IP addresses and port numbers for those client and server applications.
   2. Configure client and server application traffic flow characteristics, such as packet size, packet interval, and number of packets.
   3. Install the network applications on the selected nodes.
   4. Configure the start and stop timings of your applications.
5. Install FlowMonitor (an ns-3 class) on all nodes to collect all flow statistics. Although it is not necessary to install a FlowMonitor application on nodes, it is important to analyze your network application’s performance on the simulation topology in terms of flow level throughput, delay, packet loss, and jitter metrics.
6. Configure packet capturing and traces on nodes (this is optional). This helps you to collect a variety of packets exchanged across your simulation topology and possibly to inspect packet details using the wireshark or tcpdump packet analysis tools.
7. Configure the Animation Interface (this is optional). It helps you to view the following simulation execution and results using the NetAnim visualization tool:
   1. Enable various packets exchange among nodes tracking feature.
   2. Enable the routing tables tracking feature.
   3. Enable the counter tables tracking feature.
   4. Enable flow monitor statistics capturing.
8. Configure the stopping time of your simulation using Simulator::Stop(). It is necessary to stop the simulation when you use a flow monitor; otherwise, your simulation never ends.
9. Start running your simulation using Simulator::Run(). This statement starts your simulation execution.
10. Convert the flow monitor results into an XML file to visualize using NetAnim.
11. Clean up your simulation resources using Simulator::Destroy(). It is important to clean up your simulation resources such as memory, devices, and files.

We now understand a typical ns-3 simulation program structure. This common structure is suitable for writing any wired, wireless, or mobile networking topology simulation. With this knowledge, in the next section, we will start writing our first simulation program (pkt_first.cc) by referring to the existing tutorial/first.cc simulation program.

In ns-3 topologies, host or any network equipment are referred to as nodes with unique identifiers. We can view a node as a computing device. Based on our requirements, we can install necessary applications, and wired, wireless, or IP stacks to enable a given node as suitable network equipment or a suitable host or server. Besides this, to connect various nodes, ns-3 offers a variety of wired and wireless channels. In ns-3, nodes and channels are implemented using C++ classes. Usually, ns-3 simulation programs are written in C++ and saved with the .cc extension under the ns-allinone-3.36/ns-3.36/scratch/ folder. You can write an ns-3 program in any text editor or Code::Blocks like any other C++ program. Now, we will discuss our first simulation program (pkt_first.cc) for simulating a simple point-to-point (P2P) network topology.

First simulation implementation activity using ns-3

What do you want to learn and achieve in your first network simulation activity? Let's look at some suggestions:

• This is how to set up the following simple P2P network (shown in comments), which connects two hosts. In ns-3, the P2P module is a P2P data link available for connecting exactly two devices only using a PointToPointHelper channel class:

  // Simple Point to Point Network
  //         192.168.1.0
  // Node 0 --------------  Node 1
  //    point-to-point channel
  // (Speed: 1Gbps, Propagation Delay: 1ms)
  // Install User Datagram Protocol (UDP) Echo Client on Node-0
  // Install UDP Echo Server on Node-1

• Install the UDP echo client and server applications on Node-0 and Node-1 respectively and configure the following UDP echo client application traffic characteristics:
  • MaxPackets: Maximum packets to be sent (e.g., 10).
  • Interval: At what speed the echo client application should send a packet. For example, setting Interval to 0.1 means 10 packets are sent per second.
  • PacketSize: Configure each packet size in terms of bytes (e.g., 1,024).
• Monitor how the UDP echo client and server exchange packets in the network.
• View the actual packets processed at Node-0 and Node-1.
• Generate an animation XML file that can be used with NetAnim later.
• Analyze UDP flow performance in terms of throughput, delay, jitter, and packet loss.

Now, we are going to explain step-by-step instructions for how to solve the preceding simulation activity using an ns-3 program, which will be saved under pkt_first.cc in the ns-allinone-3.36/ns-3.36/scratch/ folder:

1. First, import all necessary ns-3 packages:
   1. core-module for accessing all core features of ns-3, such as simulator activities in terms of handling events, starting and stopping simulation execution, logging, tracing, and attributes.
   2. network-module for accessing network socket features, packet representation, and so on.
   3. internet-module for accessing and installing TCP/IP protocols and applications-module for installing various TCP/UDP applications on nodes.
   4. Next, specific to our simulation, we use point-to-point-module to access and use the P2P channel.
   5. Finally, we use netanim-module to enable animation support and use flow-monitor-module to collect flow-level statistics, such as throughput, delay, jitter, and packet loss:

   #include "ns3/core-module.h"
   #include "ns3/network-module.h"
   #include "ns3/internet-module.h"
   #include "ns3/applications-module.h"
   #include "ns3/point-to-point-module.h"
   #include "ns3/netanim-module.h"
   #include "ns3/flow-monitor-module.h"
   using namespace ns-3

2. In ns-3, the actual simulation execution starts with the main() function. Hence, we need to write our actual code in the main() function. We write the following relevant code in main():
   1. As per the topology diagram given in our simulation activity, we start by first creating two hosts as two nodes using NodeContainer.
   2. Then, we create and configure the P2P channel as per our requirements (1 Gbps speed, 1 ms delay) using PointToPointHelper:

     NodeContainer nodes;
     nodes.Create (2);
    PointToPointHelper pointToPoint;
     pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("1Gbps"));
     pointToPoint.SetChannelAttribute ("Delay", StringValue ("1ms"));

   3. Next, install the P2P protocol on the nodes, which connects them using the P2P channel. As a result, it returns two devices to the NetDeviceContainer devices: the first device is the Node-0 NIC and the second device is the Node-1 NIC:

     NetDeviceContainer devices;
     devices = pointToPoint.Install (nodes);

   4. Now, we install TCP/IP protocols on nodes. Then, we configure the IP addresses for the NetDeviceContainer devices under network ID 192.168.1.0. As a result, Node-0 gets 192.168.1.1 and Node-1 gets 192.168.1.2:

     InternetStackHelper stack;
     stack.Install (nodes);
     Ipv4AddressHelper address;
     address.SetBase ("192.168.1.0", "255.255.255.0");
     Ipv4InterfaceContainer interfaces = address.Assign (devices);

3. Create traffic applications and install them on specific ns-3 nodes:
   1. First, create a UDP echo server application and install it on Node-1. Configure its start and stop timings:

     uint64_t port = 9;
     UdpEchoServerHelper echoServer (port);
     ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
     serverApps.Start (Seconds (1.0));
     serverApps.Stop (Seconds (10.0));

   2. Next, create a UDP echo client application and install it on Node-0. Configure its traffic characteristics, such as the maximum number of packets to be sent, packet-sending interval, and packet size. Then, configure UDP echo client start and stop timings as per the number of packets to be sent:

     UdpEchoClientHelper echoClient (interfaces.GetAddress (1), port);
     echoClient.SetAttribute ("MaxPackets", UintegerValue (10000000));
     echoClient.SetAttribute ("Interval", TimeValue (Seconds (0.001)));
     echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
     ApplicationContainer clientApps = echoClient.Install (nodes.Get (0));
     clientApps.Start (Seconds (2.0));
     clientApps.Stop (Seconds (10.0));

4. Install FlowMonitor on all nodes to collect flow-level statistics. By doing so, at the end of the simulation, we can view and analyze each traffic flow’s throughput, delay, jitter, and packet loss:

     Ptr<FlowMonitor> flowmon;
     FlowMonitorHelper flowmonHelper;
     flowmon = flowmonHelper.InstallAll ();

5. Enable packet capturing on all nodes. In doing so, at the end of the simulation, it is possible to view the pcap files generated using the wireshark or tcpdump tools:

     pointToPoint.EnablePcapAll ("pkt_first");

6. Configure the animation interface. By doing so, after completing the simulation execution, an animation XML file will be generated. The XML file can be viewed using NetAnim and visualizing the simulation execution:

     AnimationInterface anim ("first_animation.xml");
     anim.EnablePacketMetadata (); // Optional

7. Configure the stopping time of your simulation using Simulator::Stop() and set its stop time value to be greater than the client and server applications’ stop timer values:

     Simulator::Stop (Seconds(11.0));

8. Start running your simulation using Simulator::Run():

     Simulator::Run ();

9. Convert the flow monitor results into an XML file to parse and view it at the end of the simulation:

     flowmon->SerializeToXmlFile ("first_flowmetrics.xml", true, true);

10. Clean up your simulation resources using Simulator::Destroy():

      Simulator::Destroy ();

Let’s see the complete first simulation program (pkt_first.cc):

#include "ns3/core-module.h"
#include "ns3/network-module.h"
#include "ns3/internet-module.h"
#include "ns3/point-to-point-module.h"
#include "ns3/applications-module.h"
#include "ns3/netanim-module.h"
#include "ns3/flow-monitor-module.h"
using namespace ns3;
NS_LOG_COMPONENT_DEFINE ("FirstScriptExample");
int
main (int argc, char *argv[])
{
 LogComponentEnable ("UdpEchoClientApplication", LOG_LEVEL_INFO);
  LogComponentEnable ("UdpEchoServerApplication", LOG_LEVEL_INFO);
  NodeContainer nodes;
  nodes.Create (2);
  PointToPointHelper pointToPoint;
  pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("1Gbps"));
  pointToPoint.SetChannelAttribute ("Delay", StringValue ("1ms"));
  NetDeviceContainer devices;
  devices = pointToPoint.Install (nodes);
  InternetStackHelper stack;
  stack.Install (nodes);
  Ipv4AddressHelper address;
  address.SetBase ("192.168.1.0", "255.255.255.0");
  Ipv4InterfaceContainer interfaces = address.Assign (devices);
  uint64_t port = 9;
  UdpEchoServerHelper echoServer (port);
  ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
  serverApps.Start (Seconds (1.0));
  serverApps.Stop (Seconds (10.0));
  UdpEchoClientHelper echoClient (interfaces.GetAddress (1), port);
  echoClient.SetAttribute ("MaxPackets", UintegerValue (10));
  echoClient.SetAttribute ("Interval", TimeValue (Seconds (0.1)));
  echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
  ApplicationContainer clientApps = echoClient.Install (nodes.Get (0));
  clientApps.Start (Seconds (2.0));
  clientApps.Stop (Seconds (10.0));
  Ptr<FlowMonitor> flowmon;
  FlowMonitorHelper flowmonHelper;
  flowmon = flowmonHelper.InstallAll ();
 pointToPoint.EnablePcapAll ("pkt_first");
 AnimationInterface anim ("first_animation.xml");
  anim.EnablePacketMetadata (); // Optional
  Simulator::Stop (Seconds(11.0));
  Simulator::Run ();
  flowmon->SerializeToXmlFile ("first_flowmetrics.xml", true, true);
  Simulator::Destroy ();
}

That’s great. We have completed our first simulation implementation. Let’s evaluate and analyze our first simulation thoroughly in the next section.

First simulation evaluation using ns-3

Let’s run our first simulation program using the following command. As pkt_first.cc is saved in the scratch folder, first move it to the ns-allinone-3.36/ns-3.36 folder and run the following command:

$./ns3 run scratch/pkt_first

After executing the command, let’s observe the simulation results in Figure 1.12:

Figure 1.12 – The pkt_first.cc simulation execution results

After running the pkt_first.cc simulation, the following details need to be observed.

Monitor the simulation execution, including things such as how the two nodes exchange UDP echo requests and reply packets. Since we enabled the log components of the UDP echo server and client applications, it is possible to view the various events generated by the UDP applications used in our simulation. We can observe a few important details, such as at what time the first packet is generated by the client (at 2 seconds), at what time the server receives a packet and when it sends a reply for the packet, and the total number of packets exchanged between the client and server.

Check the list of files generated in Figure 1.13:

Figure 1.13 – The list of files generated at end of the simulation

We can observe a total of four files are generated at the end of the simulation.

The first are PCAP files. As we are interested in viewing packets processed at Node 0 and 1, we enabled packet capturing on those nodes using pointToPoint.EnablePcapAll ("pkt_first"); in our simulation program. It generates two files whose names start with pkt_first followed by Node and its NIC numbers; for example, pkt_first_0_0.pcap corresponds to Node-0 and NIC-0, and pkt_first_1_0.pcap corresponds to Node-1 and NIC-0. We can open these .pcap files using wireshark (refer to Figure 1.14) or the tcpdump tool to view the file contents:

Figure 1.14 – The contents of pkt_first_0_0.pcap

Then we have two XML files. One file is first_animation.xml. This file can be used to visualize the simulation execution using the NetAnim tool. Another XML file is first_flowmetrics.xml. This file is useful for viewing flow statistics such as throughput, delay, jitter, and packet loss.

Let’s validate our simulation results with the ns-3 FlowMonitor using the following parsing commands.

First copy ns-allinone-3.36/ns-3.36/src/flow-monitor/examples/flowmon-parse-results.py to the scratch folder. Execute the following command and observe the following results in Figure 1.15:

python3 scratch/flowmon-parse-results.py first_flowmetrics.xml

In our simulation, the UDP client application sends 10 packets of 1,024 bytes at a rate of one per second (10*1,024*8) to the echo server application. Hence, for both flows, we see the same TX and RX bitrates (93 kbps) in the flow monitor results shown in Figure 1.15. These results match our configured flow rate per second. Similarly, the average delay (1.01 ms) and packet loss (0%) can be verified:

Figure 1.15 – Flow monitor results

You can try changing MaxPackets, Interval, and PacketSize to observe different results.

The following are points to remember and check while implementing simulation programs:

• Check whether you imported all necessary packages.
• A few points to bear in mind while creating a topology are the following:
  • The node index starts at 0.
  • After connecting all nodes using channels, a node can have multiple network devices (or NICs). The NIC index also starts at 0.
  • IP addresses should be assigned to nodes only after installing the necessary protocols and internet stack. From a subnet, the first IP will be assigned to the first node, the second IP assigned to the second node, and so on.
  • Routing protocols should be configured on nodes only after IP address assignment.
• It is necessary to confirm on which nodes the client or server applications are installed and check whether the client is configured with the correct server’s socket address (server IP and port number). This helps avoid common mistakes in installing applications.
• Before running a simulation, it is also necessary to check application traffic characteristics such as the packet size, number of packets, packet intervals, and start and stop timings of respective client and server applications. This helps avoid common mistakes when computing flow-level metrics such as throughput, delay, jitter, and packet loss.
• It is good practice to install FlowMonitor in your simulation setup to analyze your simulation results. When using FlowMonitor, the following should be done:
  • It is necessary to use the Simulator::Stop() statement before Simulator::Run() to break infinite events generated by FlowMonitor.
  • After the Simulator:: Run() statement, it is necessary to use SerializeToXmlFile() to view results in the NetAnim visualizer.
• By default, logging, packet capturing, and tracing features are not enabled.
• In cases where users are interested in visualizing simulation results, it is necessary to write all suitable NetAnim statements in the program.
• Set the simulator stop time to a greater value than the client and server applications’ stop timer values.

In this section, we have learned how to write a simulation program using various ns-3 classes, and we also learned about important things to observe during and after a simulation execution. In the next section, we start the most fun and long-awaited ns-3 session using NetAnim.

One of the interesting and very useful features of ns-3 is the support of NetAnim. NetAnim makes executing simulations more interesting. It allows you to visualize the entire simulation execution in a bird’s eye view in terms of inspecting a variety of nodes, their configuration details, placement models, mobility models, and packet flows. Besides visualizing simulation execution using NetAnim, we can do the following interesting activities:

• Monitor and inspect various protocol packets exchanged among network nodes during a traffic flow
• Inspect network node configuration details such as IP, MAC, routing tables, and counters
• View flow-level statistics such as throughput, delay, jitter, and packet loss

In the next section, you will learn how to install and use NetAnim to visualize the simulation execution for monitoring, debugging, and analyzing activities.

How to install and use NetAnim

NetAnim’s Graphical User Interface (GUI) is implemented using Qt, a cross-platform software. In order to install the NetAnim GUI, execute the following commands:

cd ns-allinone-3.36/netanim-3.108
make clean
qmake NetAnim.pro
make

After executing the preceding commands, a NetAnim executable file is going to be created in the same directory. Then, you can open it by typing ./NetAnim. This will open NetAnim’s GUI (refer to Figure 1.16). Inside the NetAnim window, we can observe the following message: Please select an XML trace file using the file load button on the top-left corner:

Figure 1.16 – The ns-3 NetAnim user interface

Follow these steps to visualize your simulation program execution using NetAnim:

1. Include the [#include "ns3/netanim-module.h"] header in your simulation program:
   1. Include the following code: AnimationInterface anim ("animation.xml"); before Simulator::Run() in your simulation program.
   2. Execute the program using ./ns3 run scratch/your simulation program. After successful execution, it generates an animation.xml file.
2. Now, you can open the animation.xml trace file using NetAnim to visualize your simulation.

Next, we explore NetAnim's various options for visualizing ns-3 simulations.

How to use the NetAnim GUI (panels and their menus)

In the NetAnim GUI, under the Animator tab, we can see a folder symbol. After clicking on it, select and open the animation.xml file. Then, it displays various nodes involved in your simulation. Now, you are ready to execute the simulation and visualize it using NetAnim by clicking on the play button from the main top panel menu.

The main top panel menu

In the main top panel menu (refer to Figure 1.17), from left to right, you’ll find the following options:

• The Folder option to load the animation XML file.
• The Reload option to restart the simulation.
• The Play button to start the simulation execution. On pressing this button, you can observe the change in the simulation time display, progress bar, packets exchange arrows, placement of nodes, and so on.
• By changing the speed slide bar, we can control the simulation execution speed.
• You can change the Node Size and Lines values to modify the displayed grid size and node sizes. Click on MAC or IP to display nodes’ MAC/IP details:

Figure 1.17 – The NetAnim top panel menu items

The side panel menu

In the side panel menu (refer to Figure 1.18), we can find the following important options:

Figure 1.18 – The NetAnim side panel menu items

• Step through simulation >>: If you want to see simulation execution step by step in simulation time, click the >> button. It allows you to see intermediate events that happened during the simulation execution. Reset the simulation by clicking on R.
• Stop icon: To enable or disable the display of packet exchange arrows.
• Show packet metadata icon (M): By enabling this, we can view packets and their internal details.
• To view nodes and their details clearly, you can use the zoom-in and zoom-out options.
• Show properties tree icon: Clicking on this opens a complete properties description panel for nodes (refer to Figure 1.19):

Figure 1.19 – Showing the complete description of Node-0 in our simulation

• Other icons: There is an option to toggle the display of SYS node IDs and another option to display the X and Y coordinates of the mouse pointer.

Visualizing a network simulation using NetAnim

What do you want to learn and achieve in your first network simulation visualization? Let's look at some suggestions:

• How to set up the following simple carrier-sense multiple access (CSMA) network (as shown in the comments), which connects four hosts. In ns-3, the CSMA module helps you simulate a simple shared bus network or Ethernet IEEE 802.3 and provides only basic functionality:

  // Simple CSMA Network
  //         192.168.1.0
  // Node-0 ---- Node-1----Node-2----Node-3
  //    CSMA Channel
  // (Speed: 5Mbps, Propagation Delay: 6560 nano seconds)
  // Install UDP Echo Client on Node-0
  // Install UDP Echo Server on Node-3

• Install the UDP echo client and server applications on Node-0 and Node-1 respectively and configure the following UDP echo client application traffic characteristics:
  • MaxPackets: A maximum of 1,000 packets to be sent.
  • Interval: The speed at which the echo client application should send packets. For example, setting Interval to 0.1 means 10 packets are sent per second.
  • PacketSize: 1,024 bytes set for each packet.
• We want to monitor how the UDP echo client and server exchange packets in the network.
• Generate an animation XML file that can be used later with NetAnim. We want to visualize routing tables, packet counter values, and flow statistics using NetAnim.
• View flow-level metrics such as throughput, delay, jitter, and packet loss.

Now, we are going to explain step-by-step instructions for writing the simulation program, which will be saved under pkt_first_anim.cc in the ns-allinone-3.36/ns-3.36/scratch/ folder.

In this section, we will simulate a four-node CSMA LAN and visualize its simulation:

1. First, import all necessary ns-3 packages (core, network, internet, applications, and flow-monitor). Besides this, as we want to simulate a CSMA LAN and visualize its execution, the csma and netanim modules are imported:

   #include "ns3/csma-module.h"
   #include "ns3/netanim-module.h"

2. In ns-3, the actual simulation execution starts with the main() function. We write the following relevant code in main():
   1. As per the topology diagram given in our simulation activity, we start with first creating four hosts as four nodes using NodeContainer:

     NodeContainer nodes;
     nodes.Create (4);

   2. Then, we create and configure the CSMA channel as per our requirements (5 Mbps speed, 6,560 ns delay) using CsmaHelper:

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

   3. Next, install the CSMA protocol on the nodes, which connects them using the CSMA channel. As a result, it returns four devices to NetDeviceContainer devices: the first device is the Node-0 NIC, the second device is the Node-1 NIC, and so on:

     NetDeviceContainer devices;
     devices = csma.Install (nodes);

   4. Now, we install TCP/IP on the nodes. Then, we configure the IP addresses for the NetDeviceContainer devices under the 192.168.1.0 network ID. As a result, Node-0 gets 192.168.1.1 and Node-3 gets 192.168.1.4:

     InternetStackHelper stack;
     stack.Install (nodes);
     Ipv4AddressHelper address;
     address.SetBase ("192.168.1.0", "255.255.255.0");
     Ipv4InterfaceContainer interfaces = address.Assign (devices);

3. Create the ns-3 traffic applications and install them as per the simulation topology:
   1. First, create a UDP echo server application and install it on Node-3. Then, configure its start and stop timings:

     uint64_t port = 9;
     UdpEchoServerHelper echoServer (port);
     ApplicationContainer serverApps = echoServer.Install (nodes.Get (3));
     serverApps.Start (Seconds (1.0));
     serverApps.Stop (Seconds (10.0));

   2. Next, create a UDP echo client application and install it on Node-0. Configure its traffic characteristics (MaxPackets=1000, Interval=0.1, and PacketSize=1024), and set start and stop timings based on MaxPackets:

     UdpEchoClientHelper echoClient (interfaces.GetAddress (3), port);
     echoClient.SetAttribute ("MaxPackets", UintegerValue (1000));
     echoClient.SetAttribute ("Interval", TimeValue (Seconds (0.1)));
     echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
     ApplicationContainer clientApps = echoClient.Install (nodes.Get (0));
     clientApps.Start (Seconds (2.0));
     clientApps.Stop (Seconds (10.0));

4. Install FlowMonitor on all nodes to collect flow-level statistics. Hence, at the end of the simulation, we can view each traffic flow’s throughput, delay, jitter, and packet loss:

     Ptr<FlowMonitor> flowmon;
     FlowMonitorHelper flowmonHelper;
     flowmon = flowmonHelper.InstallAll ();

5. Configure the animation interface. At the end of the simulation execution, an animation XML file called first_animation_demo.xml will be generated. The XML file can be viewed using NetAnim to visualize the simulation execution:
   1. We want to name Node-0 as a UDP echo client and Node-3 as a UDP echo server in the visualization:

     AnimationInterface anim ("first_animation_demo.xml");
     anim.UpdateNodeDescription (3, "UDP Echo Server");
     anim.UpdateNodeDescription (0, "UDP Echo Client");

   2. During the simulation execution, we want to visualize the various protocol packets exchanged:

     anim.EnablePacketMetadata ();

   3. At end of the simulation, we want to visualize routing tables configured on various nodes using NetAnim:

     anim.EnableIpv4RouteTracking ("firstanim_routetable.xml", Seconds (0), Seconds (2), Seconds (0.25));

   4. At end of the simulation, we want to visualize various packet counter values of various nodes using NetAnim:

     anim.EnableIpv4L3ProtocolCounters (Seconds (0), Seconds (10));
     anim.EnableQueueCounters (Seconds (0), Seconds (10));
     Simulator::Stop (Seconds(11.0));
     Simulator::Run ();

   5. At end of the simulation, we want to view all flows’ flow statistics, such as throughput, delay, jitter, and packet loss:

     flowmon->SerializeToXmlFile ("firstanim_flowmetrics.xml", true, true);
     Simulator::Destroy ();

Now, you can execute your simulation program using the following command:

$ ./ns3 run scratch/pkt_first_anim

It generates 3 XML files such as first_animation_demo.xml, firstanim_routetable.xml, and firstanim_flowmetrics.xml

Playing your simulation using NetAnim

Now, play your simulation using NetAnim and do the following - After opening NetAnim, open first_animation_demo.xml to visualize the simulation. While playing this simulation using NetAnim, you can see (refer to Figure 1.20) the first exchange of Address Resolution Protocol (ARP) packets to discover the link addresses (MAC) of the nodes, then the actual UDP traffic packet exchange begins among the nodes:

Figure 1.20 – Visualize ARP packets and UDP packets using NetAnim

Important note

If you comment anim.EnablePacketMetadata() in the code or disable the M option from the side panel, you will not see any packets exchanged during the simulation visualization. At the end of the simulation, if you want to see packet exchanges happening between various nodes, you can do it using the Packets tab options. We’ll explore the Packets tab and its options in the following subsection.

Inspecting a variety of traffic packets under the NetAnim Packets tab

Under the Packets tab (refer to Figure 1.21), by using the Show Nodes option and selecting the packet type, it is possible to view various packets exchanged between various nodes:

Figure 1.21 – The NetAnim Packets tab options

For example, we can observe the exchange of ARP packets between Node-0 and Node-3 by doing the following (refer to Figure 1.22). Type 0 : : : 3 in Show Nodes, tick Arp, then click on Submit:

Figure 1.22 – Select the Arp option to view ARP packets exchange

We can observe the following chart (refer to Figure 1.23) showing the exchange of ARP packets between Node-0 and Node-3:

Figure 1.23 – ARP packets exchange between Node-0 and Node-3 shown as a sequence diagram

We can also observe the exchange of ARP packets between Node-0 and Node-3 in a table format (refer to Figure 1.24) in time series rows:

Figure 1.24 – ARP packets exchange shown as a table

Similarly, you can try observing Ethernet, IP, and UDP packet exchanges between various nodes at simulation time. Next, we will explore the Stats tab for visualizing routing tables, various counter values, and flow statistics.

Inspecting simulation statistics under the NetAnim Stats tab

In order to inspect network node configuration details such as IP and MAC, flow-level stats, routing tables, and counters, we can use the Stats tab (refer to Figure 1.25) and its following options:

Figure 1.25 – The NetAnim Stats tab options

The first option is IP-MAC. By default, IP-MAC details (refer to Figure 1.26) can be viewed without any lines of code in your simulation program:

Figure 1.26 – The NetAnim IP-MAC menu window

As we selected the All option, it is displaying all the nodes’ IP and MAC details, as shown in Figure 1.27. You can try selecting a particular node ID:

Figure 1.27 – The ns-3 nodes’ IP and MAC details

We also have the Routing option. To view routing tables, open firstanim_routetable.xml, which was generated by your simulation program. Now, we can view the routing tables of all nodes or individual nodes by clicking on the node numbers displayed on the side panel shown in Figure 1.28:

Figure 1.28 – The NetAnim Routing menu window

We selected the All option to display all nodes’ routing tables, as shown in Figure 1.29:

Figure 1.29 – Our simulation ns-3 nodes’ routing table details

Then, we have the Flow-monitor option. From the Stats tab, select Flow-monitor (refer to Figure 1.30). Next, click the FlowMon file button and open firstanim_flowmetrics.xml, generated by your simulation program:

Figure 1.30 – The NetAnim Flow-monitor window

Now, we can view the flow-level stats of all nodes (refer to Figure 1.31) or individual nodes by clicking on the node numbers displayed on the side panel. We selected the ALL option to show all flows’ statistics:

Figure 1.31 – Our simulation flow-level statistics

We also have the Counter Tables option. We can check the counter value of various nodes by selecting the Counter Tables menu item under the Stats menu list.

After selecting Counter Tables, we can select from the Ipv4 Tx, Ipv4 Rx, Ipv4 Drop, Enqueue, Dequeue, and Queue Drop options next to the FlowMon file option (refer to Figure 1.32):

Figure 1.32 – The NetAnim Counter Tables window

For example, to show IPv4 packet drops on various nodes, you can select the Ipv4 Drop option and view the result (refer to Figure 1.33) in table or chart format by clicking on the show table or show chart button:

Figure 1.33 – Our simulation nodes’ IPv4 packet drop counter table

Well done! After practicing your first hands-on activity, you are ready to explore ns-3's more interesting features.

Congratulations on the successful completion of this chapter. We have just completed this starting session on the ns-3 simulator, which helped you learn how to install ns-3, understand ns-3 code and simulation structures, and write simulation programs using the Code::Blocks editor. We also explored NetAnim thoroughly with its all-important features for visualizing simulation execution results and details. Next, we are going to start another exciting chapter that discusses important features of ns-3, such as logging, debugging, tracing, and how to validate simulation results.