Section outline

  • Introduction to this Course

    Hello and welcome to the Quickstart ns-3 course!

    This short course is your gateway to the world of network simulation using ns-3. Whether you're a student, a researcher, or a network enthusiast, this course is designed to get you up and running with the fundamentals of ns-3 in the quickest and most efficient way possible.

    Instead of getting lost in complex documentation, we'll take a hands-on approach, guiding you through the essential steps of building, running, and analyzing your first simulation scripts. By the end, you'll have the foundational knowledge and practical skills needed to start creating your own network simulations with confidence.

    This course is a refined version of the article "Learning ns-3 in Step by Step". In addition to that you can run the simulaitons on our iPlayground.

    Get ready to build, simulate, and analyze! Let's get started.

  • Simple P2P Network Simulation

    Let us kickstart our ns-3 learning by directly experimenting with the following ns-3 simulation.

    This script is a classic, simple ns-3 simulation that demonstrates a basic client-server communication using a UDP echo protocol over a point-to-point link. The comments have been added to explain each major step of the process.

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

using namespace ns3;

int main(int argc, char *argv[])
{
    // Sets the logging level
    LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);

    // Create a container to hold our two nodes
    NodeContainer nodes;
    nodes.Create(2);

    // Create a point-to-point channel and configure its attributes
    PointToPointHelper channel;
    channel.SetDeviceAttribute("DataRate", StringValue("5Mbps"));
    channel.SetChannelAttribute("Delay", StringValue("2ms"));

    // Install the channel and devices on our nodes
    NetDeviceContainer netDevices;
    netDevices = channel.Install(nodes);

    // Install the Internet stack (TCP/IP) on our nodes
    InternetStackHelper ipStack;
    ipStack.Install(nodes);

    // Assign IP addresses to the devices
    Ipv4AddressHelper ipAddresses;
    ipAddresses.SetBase("192.168.1.0", "255.255.255.0");

    // Assign the IP addresses and store the interfaces
    Ipv4InterfaceContainer ipinterfaces = ipAddresses.Assign(netDevices);

    // Set up a UDP Echo Server on node 1, listening on port 9
    UdpEchoServerHelper udpEchoServer(9);

    ApplicationContainer serverApps = udpEchoServer.Install(nodes.Get(1));
    serverApps.Start(Seconds(1.0));

    // Set up a UDP Echo Client on node 0
    // It will send packets to the server's IP address (node 1) on port 9
    UdpEchoClientHelper udpEchoClient(ipinterfaces.GetAddress(1), 9);

    ApplicationContainer clientApps = udpEchoClient.Install(nodes.Get(0));
    clientApps.Start(Seconds(2.0));

    // Run the simulation
    Simulator::Run();

    return 0;
}

    Here is a breakdown of what the sections of code does

     

    1. Setup and Topology

    The script begins by setting up the foundational elements of the simulation.

    • Node Creation: NodeContainer nodes; nodes.Create(2); creates two virtual nodes. A NodeContainer is simply a list that holds these nodes, making it easy to manage them.

    • Channel and Device Configuration: A PointToPointHelper is used to create and configure a point-to-point communication channel. The key attributes, DataRate (5 Mbps) and Delay (2 ms), are set for this channel. The Install(nodes) function then creates a virtual network interface card (NIC) on each node and connects them via this channel. The resulting devices are stored in a NetDeviceContainer.

    2. Network Stack and Addressing

    This section transforms the generic nodes into functional network devices.

    • IP Stack Installation: An InternetStackHelper is used to install the full Internet Protocol (IP) stack on both nodes. This gives them the ability to handle protocols like TCP and UDP and to understand IP addressing.

    • IP Address Assignment: An Ipv4AddressHelper assigns IP addresses to the network devices. In this case, it assigns addresses from the 192.168.1.0/24 subnet. The first node gets 192.168.1.1 and the second gets 192.168.1.2, which are stored in an Ipv4InterfaceContainer.

    3. Application Layer

    This is where the actual traffic generation and reception are configured.

    • UDP Echo Server: A UdpEchoServerHelper is used to set up an echo server on the second node (nodes.Get(1)), which listens for packets on port 9.

    • UDP Echo Client: A UdpEchoClientHelper is used to set up a client on the first node (nodes.Get(0)). The client is configured to send traffic to the server's IP address (ipinterfaces.GetAddress(1)) on the correct port.

    • Event Scheduling: The Start() function is called for both the server and client applications. This schedules the server to begin listening at 1 second and the client to start sending traffic at 2 seconds. The staggered start times ensure the server is ready to receive packets before the client starts sending.

    4. Starting the Discrete-event Simulation

    • Running the Simulation: The line Simulator::Run(); is the core command that starts the discrete-event simulation. It processes all the scheduled events (like starting applications, sending packets, etc.) until there are no more events to run.

    5. Enable Logging.

    To enable the logging level of UdpEchoClientApplication to level_info we  need to use the LogComponentEnable() function.

    LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);

    This function call directly sets the logging level for a specific ns-3 component, bypassing the need to use an environment variable.

    • LogComponentEnable: This is the function that controls logging in ns-3.

    • "UdpEchoClientApplication": This is the string name of the component for which you want to enable logging.

    • LOG_LEVEL_INFO: This macro corresponds to the level_info you would set with the environment variable. Other common levels include LOG_LEVEL_DEBUG, LOG_LEVEL_WARN, and LOG_LEVEL_ERROR.

    By placing this line in your code, the log component will be enabled regardless of whether the NS_LOG environment variable is set. This is particularly useful for hardcoding specific debugging settings for a script.

    Activities: 0

  • Visualizing a Network Simulaiton with NetAnim

    The Following is a simple ns-3 simulation that creates a point-to-point link between two nodes, runs a UDP echo client-server application, and generates a visualization file for NetAnim. Follow the comments to understand each step.

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

using namespace ns3;

int main(int argc, char *argv[])
{
    // Create a container to hold our two nodes
    NodeContainer nodes;
    nodes.Create(2);

    // Create a point-to-point channel and configure its attributes
    PointToPointHelper channel;
    channel.SetDeviceAttribute("DataRate", StringValue("5Mbps"));
    channel.SetChannelAttribute("Delay", StringValue("2ms"));

    // Install the channel and devices on our nodes
    NetDeviceContainer netDevices;
    netDevices = channel.Install(nodes);

    // Install the Internet stack (TCP/IP) on our nodes
    InternetStackHelper ipStack;
    ipStack.Install(nodes);

    // Assign IP addresses to the devices
    Ipv4AddressHelper ipAddresses;
    ipAddresses.SetBase("192.168.1.0", "255.255.255.0");
    Ipv4InterfaceContainer ipinterfaces = ipAddresses.Assign(netDevices);

    // Set up a UDP Echo Server on node 1, listening on port 9
    UdpEchoServerHelper udpEchoServer(9);
    ApplicationContainer serverApps = udpEchoServer.Install(nodes.Get(1));
    serverApps.Start(Seconds(1.0));

    // Set up a UDP Echo Client on node 0
    UdpEchoClientHelper udpEchoClient(ipinterfaces.GetAddress(1), 9);
    ApplicationContainer clientApps = udpEchoClient.Install(nodes.Get(0));
    clientApps.Start(Seconds(2.0));

    // Set up NetAnim to visualize the simulation
    AnimationInterface anim("SimpleNS3Simulation_NetAnimationOutput.xml");
    anim.SetConstantPosition(nodes.Get(0), 0, 5);
    anim.SetConstantPosition(nodes.Get(1), 10, 5);

    // Run the simulation
    Simulator::Run();
    Simulator::Destroy();
    return 0;
}

    Step-by-Step Explanation

    1. Setup and Topology

    The script first sets up the fundamental elements of the simulation.

    • Header Files: Necessary modules for core functionality, networking, point-to-point links, the internet stack, applications, mobility, and NetAnim are included.

    • Node Creation: A NodeContainer is used to create two virtual nodes, which act as the endpoints of our network.

    • Channel and Device Configuration: A PointToPointHelper sets up a communication channel with a specified DataRate (5 Mbps) and Delay (2 ms) and installs network devices on the nodes

    2. Network Stack and Addressing

    This section transforms the generic nodes into functional network devices.

    • IP Stack Installation: The InternetStackHelper installs the full IP stack on both nodes, enabling them to use IP addresses and handle protocols like TCP and UDP.

    • IP Address Assignment: An Ipv4AddressHelper assigns IP addresses from the 192.168.1.0/24 subnet to the network devices, making them addressable.

    3. Application Layer

    This part configures the actual data traffic for the simulation.

    • UDP Echo Server: A UdpEchoServerHelper sets up an application on the second node to listen for UDP packets on port 9.

    • UDP Echo Client: A UdpEchoClientHelper sets up a client on the first node to send packets to the server's IP address.

    • Event Scheduling: Both applications are scheduled to start at different times. The server starts at 1 second, ensuring it's ready to receive before the client begins sending at 2 seconds.

    4. Mobility and Visualization

    This is a key addition to the basic simulation, allowing for a visual representation of the network.

    • Mobility Helper (Commented): The MobilityHelper section is included in your original code but is redundant and commented out. ConstantPositionMobilityModel is used to set static positions, but the subsequent NetAnim calls override this.

    • AnimationInterface: An AnimationInterface object is created, which will generate an XML file (SimpleNS3Simulation_NetAnimationOutput.xml) containing all the events needed for the NetAnim visualizer.

    • Static Positioning: The SetConstantPosition() function explicitly sets the coordinates for each node on the NetAnim canvas, with Node 0 at (0, 5) and Node 1 at (10, 5).

    5. Start Running the Simulation

    • Running the Simulation: Simulator::Run() starts the simulation, processing all scheduled events.

    • Cleanup: Simulator::Destroy() is a good practice to free up all memory and objects, ensuring a clean exit.

    • Return Value: The return 0; statement indicates a successful program execution.

    Activities: 0