--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/tutorial/source/conceptual-overview.rst Sun Jan 02 22:57:32 2011 -0800
@@ -0,0 +1,840 @@
+.. include:: replace.txt
+
+
+Conceptual Overview
+-------------------
+
+The first thing we need to do before actually starting to look at or write
+|ns3| code is to explain a few core concepts and abstractions in the
+system. Much of this may appear transparently obvious to some, but we
+recommend taking the time to read through this section just to ensure you
+are starting on a firm foundation.
+
+Key Abstractions
+****************
+
+In this section, we'll review some terms that are commonly used in
+networking, but have a specific meaning in |ns3|.
+
+Node
+++++
+In Internet jargon, a computing device that connects to a network is called
+a *host* or sometimes an *end system*. Because |ns3| is a
+*network* simulator, not specifically an *Internet* simulator, we
+intentionally do not use the term host since it is closely associated with
+the Internet and its protocols. Instead, we use a more generic term also
+used by other simulators that originates in Graph Theory --- the *node*.
+
+In |ns3| the basic computing device abstraction is called the
+node. This abstraction is represented in C++ by the class ``Node``. The
+``Node`` class provides methods for managing the representations of
+computing devices in simulations.
+
+You should think of a ``Node`` as a computer to which you will add
+functionality. One adds things like applications, protocol stacks and
+peripheral cards with their associated drivers to enable the computer to do
+useful work. We use the same basic model in |ns3|.
+
+Application
++++++++++++
+Typically, computer software is divided into two broad classes. *System
+Software* organizes various computer resources such as memory, processor
+cycles, disk, network, etc., according to some computing model. System
+software usually does not use those resources to complete tasks that directly
+benefit a user. A user would typically run an *application* that acquires
+and uses the resources controlled by the system software to accomplish some
+goal.
+
+Often, the line of separation between system and application software is made
+at the privilege level change that happens in operating system traps.
+In |ns3| there is no real concept of operating system and especially
+no concept of privilege levels or system calls. We do, however, have the
+idea of an application. Just as software applications run on computers to
+perform tasks in the "real world," |ns3| applications run on
+|ns3| ``Nodes`` to drive simulations in the simulated world.
+
+In |ns3| the basic abstraction for a user program that generates some
+activity to be simulated is the application. This abstraction is represented
+in C++ by the class ``Application``. The ``Application`` class provides
+methods for managing the representations of our version of user-level
+applications in simulations. Developers are expected to specialize the
+``Application`` class in the object-oriented programming sense to create new
+applications. In this tutorial, we will use specializations of class
+``Application`` called ``UdpEchoClientApplication`` and
+``UdpEchoServerApplication``. As you might expect, these applications
+compose a client/server application set used to generate and echo simulated
+network packets
+
+Channel
++++++++
+
+In the real world, one can connect a computer to a network. Often the media
+over which data flows in these networks are called *channels*. When
+you connect your Ethernet cable to the plug in the wall, you are connecting
+your computer to an Ethernet communication channel. In the simulated world
+of |ns3|, one connects a ``Node`` to an object representing a
+communication channel. Here the basic communication subnetwork abstraction
+is called the channel and is represented in C++ by the class ``Channel``.
+
+The ``Channel`` class provides methods for managing communication
+subnetwork objects and connecting nodes to them. ``Channels`` may also be
+specialized by developers in the object oriented programming sense. A
+``Channel`` specialization may model something as simple as a wire. The
+specialized ``Channel`` can also model things as complicated as a large
+Ethernet switch, or three-dimensional space full of obstructions in the case
+of wireless networks.
+
+We will use specialized versions of the ``Channel`` called
+``CsmaChannel``, ``PointToPointChannel`` and ``WifiChannel`` in this
+tutorial. The ``CsmaChannel``, for example, models a version of a
+communication subnetwork that implements a *carrier sense multiple
+access* communication medium. This gives us Ethernet-like functionality.
+
+Net Device
+++++++++++
+It used to be the case that if you wanted to connect a computers to a network,
+you had to buy a specific kind of network cable and a hardware device called
+(in PC terminology) a *peripheral card* that needed to be installed in
+your computer. If the peripheral card implemented some networking function,
+they were called Network Interface Cards, or *NICs*. Today most
+computers come with the network interface hardware built in and users don't
+see these building blocks.
+
+A NIC will not work without a software driver to control the hardware. In
+Unix (or Linux), a piece of peripheral hardware is classified as a
+*device*. Devices are controlled using *device drivers*, and network
+devices (NICs) are controlled using *network device drivers*
+collectively known as *net devices*. In Unix and Linux you refer
+to these net devices by names such as *eth0*.
+
+In |ns3| the *net device* abstraction covers both the software
+driver and the simulated hardware. A net device is "installed" in a
+``Node`` in order to enable the ``Node`` to communicate with other
+``Nodes`` in the simulation via ``Channels``. Just as in a real
+computer, a ``Node`` may be connected to more than one ``Channel`` via
+multiple ``NetDevices``.
+
+The net device abstraction is represented in C++ by the class ``NetDevice``.
+The ``NetDevice`` class provides methods for managing connections to
+``Node`` and ``Channel`` objects; and may be specialized by developers
+in the object-oriented programming sense. We will use the several specialized
+versions of the ``NetDevice`` called ``CsmaNetDevice``,
+``PointToPointNetDevice``, and ``WifiNetDevice`` in this tutorial.
+Just as an Ethernet NIC is designed to work with an Ethernet network, the
+``CsmaNetDevice`` is designed to work with a ``CsmaChannel``; the
+``PointToPointNetDevice`` is designed to work with a
+``PointToPointChannel`` and a ``WifiNetNevice`` is designed to work with
+a ``WifiChannel``.
+
+Topology Helpers
+++++++++++++++++
+In a real network, you will find host computers with added (or built-in)
+NICs. In |ns3| we would say that you will find ``Nodes`` with
+attached ``NetDevices``. In a large simulated network you will need to
+arrange many connections between ``Nodes``, ``NetDevices`` and
+``Channels``.
+
+Since connecting ``NetDevices`` to ``Nodes``, ``NetDevices``
+to ``Channels``, assigning IP addresses, etc., are such common tasks
+in |ns3|, we provide what we call *topology helpers* to make
+this as easy as possible. For example, it may take many distinct
+|ns3| core operations to create a NetDevice, add a MAC address,
+install that net device on a ``Node``, configure the node's protocol stack,
+and then connect the ``NetDevice`` to a ``Channel``. Even more
+operations would be required to connect multiple devices onto multipoint
+channels and then to connect individual networks together into internetworks.
+We provide topology helper objects that combine those many distinct operations
+into an easy to use model for your convenience.
+
+A First ns-3 Script
+*******************
+If you downloaded the system as was suggested above, you will have a release
+of |ns3| in a directory called ``repos`` under your home
+directory. Change into that release directory, and you should find a
+directory structure something like the following:
+
+::
+
+ AUTHORS doc/ README src/ waf.bat*
+ bindings/ examples/ RELEASE_NOTES utils/ wscript
+ build/ LICENSE samples/ VERSION wutils.py
+ CHANGES.html ns3/ scratch/ waf* wutils.pyc
+
+Change into the ``examples/tutorial`` directory. You should see a file named
+``first.cc`` located there. This is a script that will create a simple
+point-to-point link between two nodes and echo a single packet between the
+nodes. Let's take a look at that script line by line, so go ahead and open
+``first.cc`` in your favorite editor.
+
+Boilerplate
++++++++++++
+The first line in the file is an emacs mode line. This tells emacs about the
+formatting conventions (coding style) we use in our source code.
+
+::
+
+ /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+
+This is always a somewhat controversial subject, so we might as well get it
+out of the way immediately. The |ns3| project, like most large
+projects, has adopted a coding style to which all contributed code must
+adhere. If you want to contribute your code to the project, you will
+eventually have to conform to the |ns3| coding standard as described
+in the file ``doc/codingstd.txt`` or shown on the project web page
+`here
+<http://www.nsnam.org/codingstyle.html>`_.
+
+We recommend that you, well, just get used to the look and feel of |ns3|
+code and adopt this standard whenever you are working with our code. All of
+the development team and contributors have done so with various amounts of
+grumbling. The emacs mode line above makes it easier to get the formatting
+correct if you use the emacs editor.
+
+The |ns3| simulator is licensed using the GNU General Public
+License. You will see the appropriate GNU legalese at the head of every file
+in the |ns3| distribution. Often you will see a copyright notice for
+one of the institutions involved in the |ns3| project above the GPL
+text and an author listed below.
+
+::
+
+ /*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation;
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+Module Includes
++++++++++++++++
+The code proper starts with a number of include statements.
+
+::
+
+ #include "ns3/core-module.h"
+ #include "ns3/simulator-module.h"
+ #include "ns3/node-module.h"
+ #include "ns3/helper-module.h"
+
+To help our high-level script users deal with the large number of include
+files present in the system, we group includes according to relatively large
+modules. We provide a single include file that will recursively load all of
+the include files used in each module. Rather than having to look up exactly
+what header you need, and possibly have to get a number of dependencies right,
+we give you the ability to load a group of files at a large granularity. This
+is not the most efficient approach but it certainly makes writing scripts much
+easier.
+
+Each of the |ns3| include files is placed in a directory called
+``ns3`` (under the build directory) during the build process to help avoid
+include file name collisions. The ``ns3/core-module.h`` file corresponds
+to the ns-3 module you will find in the directory ``src/core`` in your
+downloaded release distribution. If you list this directory you will find a
+large number of header files. When you do a build, Waf will place public
+header files in an ``ns3`` directory under the appropriate
+``build/debug`` or ``build/optimized`` directory depending on your
+configuration. Waf will also automatically generate a module include file to
+load all of the public header files.
+
+Since you are, of course, following this tutorial religiously, you will
+already have done a
+
+::
+
+ ./waf -d debug configure
+
+in order to configure the project to perform debug builds. You will also have
+done a
+
+::
+
+ ./waf
+
+to build the project. So now if you look in the directory
+``../../build/debug/ns3`` you will find the four module include files shown
+above. You can take a look at the contents of these files and find that they
+do include all of the public include files in their respective modules.
+
+Ns3 Namespace
++++++++++++++
+The next line in the ``first.cc`` script is a namespace declaration.
+
+::
+
+ using namespace ns3;
+
+The |ns3| project is implemented in a C++ namespace called
+``ns3``. This groups all |ns3|-related declarations in a scope
+outside the global namespace, which we hope will help with integration with
+other code. The C++ ``using`` statement introduces the |ns3|
+namespace into the current (global) declarative region. This is a fancy way
+of saying that after this declaration, you will not have to type ``ns3::``
+scope resolution operator before all of the |ns3| code in order to use
+it. If you are unfamiliar with namespaces, please consult almost any C++
+tutorial and compare the ``ns3`` namespace and usage here with instances of
+the ``std`` namespace and the ``using namespace std;`` statements you
+will often find in discussions of ``cout`` and streams.
+
+Logging
++++++++
+The next line of the script is the following,
+
+::
+
+ NS_LOG_COMPONENT_DEFINE ("FirstScriptExample");
+
+We will use this statement as a convenient place to talk about our Doxygen
+documentation system. If you look at the project web site,
+`ns-3 project
+<http://www.nsnam.org>`_, you will find a link to "Doxygen
+(ns-3-dev)" in the navigation bar. If you select this link, you will be
+taken to our documentation page for the current development release. There
+is also a link to "Doxygen (stable)" that will take you to the documentation
+for the latest stable release of |ns3|.
+
+Along the left side, you will find a graphical representation of the structure
+of the documentation. A good place to start is the ``NS-3 Modules``
+"book" in the |ns3| navigation tree. If you expand ``Modules``
+you will see a list of |ns3| module documentation. The concept of
+module here ties directly into the module include files discussed above. It
+turns out that the |ns3| logging subsystem is part of the ``core``
+module, so go ahead and expand that documentation node. Now, expand the
+``Debugging`` book and then select the ``Logging`` page.
+
+You should now be looking at the Doxygen documentation for the Logging module.
+In the list of ``#define``s at the top of the page you will see the entry
+for ``NS_LOG_COMPONENT_DEFINE``. Before jumping in, it would probably be
+good to look for the "Detailed Description" of the logging module to get a
+feel for the overall operation. You can either scroll down or select the
+"More..." link under the collaboration diagram to do this.
+
+Once you have a general idea of what is going on, go ahead and take a look at
+the specific ``NS_LOG_COMPONENT_DEFINE`` documentation. I won't duplicate
+the documentation here, but to summarize, this line declares a logging
+component called ``FirstScriptExample`` that allows you to enable and
+disable console message logging by reference to the name.
+
+Main Function
++++++++++++++
+The next lines of the script you will find are,
+
+::
+
+ int
+ main (int argc, char *argv[])
+ {
+
+This is just the declaration of the main function of your program (script).
+Just as in any C++ program, you need to define a main function that will be
+the first function run. There is nothing at all special here. Your
+|ns3| script is just a C++ program.
+
+The next two lines of the script are used to enable two logging components that
+are built into the Echo Client and Echo Server applications:
+
+::
+
+ LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
+ LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);
+
+If you have read over the Logging component documentation you will have seen
+that there are a number of levels of logging verbosity/detail that you can
+enable on each component. These two lines of code enable debug logging at the
+INFO level for echo clients and servers. This will result in the application
+printing out messages as packets are sent and received during the simulation.
+
+Now we will get directly to the business of creating a topology and running
+a simulation. We use the topology helper objects to make this job as
+easy as possible.
+
+Topology Helpers
+++++++++++++++++
+NodeContainer
+~~~~~~~~~~~~~
+The next two lines of code in our script will actually create the
+|ns3| ``Node`` objects that will represent the computers in the
+simulation.
+
+::
+
+ NodeContainer nodes;
+ nodes.Create (2);
+
+Let's find the documentation for the ``NodeContainer`` class before we
+continue. Another way to get into the documentation for a given class is via
+the ``Classes`` tab in the Doxygen pages. If you still have the Doxygen
+handy, just scroll up to the top of the page and select the ``Classes``
+tab. You should see a new set of tabs appear, one of which is
+``Class List``. Under that tab you will see a list of all of the
+|ns3| classes. Scroll down, looking for ``ns3::NodeContainer``.
+When you find the class, go ahead and select it to go to the documentation for
+the class.
+
+You may recall that one of our key abstractions is the ``Node``. This
+represents a computer to which we are going to add things like protocol stacks,
+applications and peripheral cards. The ``NodeContainer`` topology helper
+provides a convenient way to create, manage and access any ``Node`` objects
+that we create in order to run a simulation. The first line above just
+declares a NodeContainer which we call ``nodes``. The second line calls the
+``Create`` method on the ``nodes`` object and asks the container to
+create two nodes. As described in the Doxygen, the container calls down into
+the |ns3| system proper to create two ``Node`` objects and stores
+pointers to those objects internally.
+
+The nodes as they stand in the script do nothing. The next step in
+constructing a topology is to connect our nodes together into a network.
+The simplest form of network we support is a single point-to-point link
+between two nodes. We'll construct one of those links here.
+
+PointToPointHelper
+~~~~~~~~~~~~~~~~~~
+We are constructing a point to point link, and, in a pattern which will become
+quite familiar to you, we use a topology helper object to do the low-level
+work required to put the link together. Recall that two of our key
+abstractions are the ``NetDevice`` and the ``Channel``. In the real
+world, these terms correspond roughly to peripheral cards and network cables.
+Typically these two things are intimately tied together and one cannot expect
+to interchange, for example, Ethernet devices and wireless channels. Our
+Topology Helpers follow this intimate coupling and therefore you will use a
+single ``PointToPointHelper`` to configure and connect |ns3|
+``PointToPointNetDevice`` and ``PointToPointChannel`` objects in this
+script.
+
+The next three lines in the script are,
+
+::
+
+ PointToPointHelper pointToPoint;
+ pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
+ pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
+
+The first line,
+
+::
+
+ PointToPointHelper pointToPoint;
+
+instantiates a ``PointToPointHelper`` object on the stack. From a
+high-level perspective the next line,
+
+::
+
+ pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
+
+tells the ``PointToPointHelper`` object to use the value "5Mbps"
+(five megabits per second) as the "DataRate" when it creates a
+``PointToPointNetDevice`` object.
+
+From a more detailed perspective, the string "DataRate" corresponds
+to what we call an ``Attribute`` of the ``PointToPointNetDevice``.
+If you look at the Doxygen for class ``ns3::PointToPointNetDevice`` and
+find the documentation for the ``GetTypeId`` method, you will find a list
+of ``Attributes`` defined for the device. Among these is the "DataRate"
+``Attribute``. Most user-visible |ns3| objects have similar lists of
+``Attributes``. We use this mechanism to easily configure simulations without
+recompiling as you will see in a following section.
+
+Similar to the "DataRate" on the ``PointToPointNetDevice`` you will find a
+"Delay" ``Attribute`` associated with the ``PointToPointChannel``. The
+final line,
+
+::
+
+ pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
+
+tells the ``PointToPointHelper`` to use the value "2ms" (two milliseconds)
+as the value of the transmission delay of every point to point channel it
+subsequently creates.
+
+NetDeviceContainer
+~~~~~~~~~~~~~~~~~~
+At this point in the script, we have a ``NodeContainer`` that contains
+two nodes. We have a ``PointToPointHelper`` that is primed and ready to
+make ``PointToPointNetDevices`` and wire ``PointToPointChannel`` objects
+between them. Just as we used the ``NodeContainer`` topology helper object
+to create the ``Nodes`` for our simulation, we will ask the
+``PointToPointHelper`` to do the work involved in creating, configuring and
+installing our devices for us. We will need to have a list of all of the
+NetDevice objects that are created, so we use a NetDeviceContainer to hold
+them just as we used a NodeContainer to hold the nodes we created. The
+following two lines of code,
+
+::
+
+ NetDeviceContainer devices;
+ devices = pointToPoint.Install (nodes);
+
+will finish configuring the devices and channel. The first line declares the
+device container mentioned above and the second does the heavy lifting. The
+``Install`` method of the ``PointToPointHelper`` takes a
+``NodeContainer`` as a parameter. Internally, a ``NetDeviceContainer``
+is created. For each node in the ``NodeContainer`` (there must be exactly
+two for a point-to-point link) a ``PointToPointNetDevice`` is created and
+saved in the device container. A ``PointToPointChannel`` is created and
+the two ``PointToPointNetDevices`` are attached. When objects are created
+by the ``PointToPointHelper``, the ``Attributes`` previously set in the
+helper are used to initialize the corresponding ``Attributes`` in the
+created objects.
+
+After executing the ``pointToPoint.Install (nodes)`` call we will have
+two nodes, each with an installed point-to-point net device and a single
+point-to-point channel between them. Both devices will be configured to
+transmit data at five megabits per second over the channel which has a two
+millisecond transmission delay.
+
+InternetStackHelper
+~~~~~~~~~~~~~~~~~~~
+We now have nodes and devices configured, but we don't have any protocol stacks
+installed on our nodes. The next two lines of code will take care of that.
+
+::
+
+ InternetStackHelper stack;
+ stack.Install (nodes);
+
+The ``InternetStackHelper`` is a topology helper that is to internet stacks
+what the ``PointToPointHelper`` is to point-to-point net devices. The
+``Install`` method takes a ``NodeContainer`` as a parameter. When it is
+executed, it will install an Internet Stack (TCP, UDP, IP, etc.) on each of
+the nodes in the node container.
+
+Ipv4AddressHelper
+~~~~~~~~~~~~~~~~~
+Next we need to associate the devices on our nodes with IP addresses. We
+provide a topology helper to manage the allocation of IP addresses. The only
+user-visible API is to set the base IP address and network mask to use when
+performing the actual address allocation (which is done at a lower level
+inside the helper).
+
+The next two lines of code in our example script, ``first.cc``,
+
+::
+
+ Ipv4AddressHelper address;
+ address.SetBase ("10.1.1.0", "255.255.255.0");
+
+declare an address helper object and tell it that it should begin allocating IP
+addresses from the network 10.1.1.0 using the mask 255.255.255.0 to define
+the allocatable bits. By default the addresses allocated will start at one
+and increase monotonically, so the first address allocated from this base will
+be 10.1.1.1, followed by 10.1.1.2, etc. The low level |ns3| system
+actually remembers all of the IP addresses allocated and will generate a
+fatal error if you accidentally cause the same address to be generated twice
+(which is a very hard to debug error, by the way).
+
+The next line of code,
+
+::
+
+ Ipv4InterfaceContainer interfaces = address.Assign (devices);
+
+performs the actual address assignment. In |ns3| we make the
+association between an IP address and a device using an ``Ipv4Interface``
+object. Just as we sometimes need a list of net devices created by a helper
+for future reference we sometimes need a list of ``Ipv4Interface`` objects.
+The ``Ipv4InterfaceContainer`` provides this functionality.
+
+Now we have a point-to-point network built, with stacks installed and IP
+addresses assigned. What we need at this point are applications to generate
+traffic.
+
+Applications
+++++++++++++
+Another one of the core abstractions of the ns-3 system is the
+``Application``. In this script we use two specializations of the core
+|ns3| class ``Application`` called ``UdpEchoServerApplication``
+and ``UdpEchoClientApplication``. Just as we have in our previous
+explanations, we use helper objects to help configure and manage the
+underlying objects. Here, we use ``UdpEchoServerHelper`` and
+``UdpEchoClientHelper`` objects to make our lives easier.
+
+UdpEchoServerHelper
+~~~~~~~~~~~~~~~~~~~
+The following lines of code in our example script, ``first.cc``, are used
+to set up a UDP echo server application on one of the nodes we have previously
+created.
+
+::
+
+ UdpEchoServerHelper echoServer (9);
+
+ ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
+ serverApps.Start (Seconds (1.0));
+ serverApps.Stop (Seconds (10.0));
+
+The first line of code in the above snippet declares the
+``UdpEchoServerHelper``. As usual, this isn't the application itself, it
+is an object used to help us create the actual applications. One of our
+conventions is to place *required* ``Attributes`` in the helper constructor.
+In this case, the helper can't do anything useful unless it is provided with
+a port number that the client also knows about. Rather than just picking one
+and hoping it all works out, we require the port number as a parameter to the
+constructor. The constructor, in turn, simply does a ``SetAttribute``
+with the passed value. If you want, you can set the "Port" ``Attribute``
+to another value later using ``SetAttribute``.
+
+Similar to many other helper objects, the ``UdpEchoServerHelper`` object
+has an ``Install`` method. It is the execution of this method that actually
+causes the underlying echo server application to be instantiated and attached
+to a node. Interestingly, the ``Install`` method takes a
+``NodeContainter`` as a parameter just as the other ``Install`` methods
+we have seen. This is actually what is passed to the method even though it
+doesn't look so in this case. There is a C++ *implicit conversion* at
+work here that takes the result of ``nodes.Get (1)`` (which returns a smart
+pointer to a node object --- ``Ptr<Node>``) and uses that in a constructor
+for an unnamed ``NodeContainer`` that is then passed to ``Install``.
+If you are ever at a loss to find a particular method signature in C++ code
+that compiles and runs just fine, look for these kinds of implicit conversions.
+
+We now see that ``echoServer.Install`` is going to install a
+``UdpEchoServerApplication`` on the node found at index number one of the
+``NodeContainer`` we used to manage our nodes. ``Install`` will return
+a container that holds pointers to all of the applications (one in this case
+since we passed a ``NodeContainer`` containing one node) created by the
+helper.
+
+Applications require a time to "start" generating traffic and may take an
+optional time to "stop". We provide both. These times are set using the
+``ApplicationContainer`` methods ``Start`` and ``Stop``. These
+methods take ``Time`` parameters. In this case, we use an *explicit*
+C++ conversion sequence to take the C++ double 1.0 and convert it to an
+|ns3| ``Time`` object using a ``Seconds`` cast. Be aware that
+the conversion rules may be controlled by the model author, and C++ has its
+own rules, so you can't always just assume that parameters will be happily
+converted for you. The two lines,
+
+::
+
+ serverApps.Start (Seconds (1.0));
+ serverApps.Stop (Seconds (10.0));
+
+will cause the echo server application to ``Start`` (enable itself) at one
+second into the simulation and to ``Stop`` (disable itself) at ten seconds
+into the simulation. By virtue of the fact that we have declared a simulation
+event (the application stop event) to be executed at ten seconds, the simulation
+will last *at least* ten seconds.
+
+UdpEchoClientHelper
+~~~~~~~~~~~~~~~~~~~
+
+The echo client application is set up in a method substantially similar to
+that for the server. There is an underlying ``UdpEchoClientApplication``
+that is managed by an ``UdpEchoClientHelper``.
+
+::
+
+ UdpEchoClientHelper echoClient (interfaces.GetAddress (1), 9);
+ echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
+ echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.)));
+ echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
+
+ ApplicationContainer clientApps = echoClient.Install (nodes.Get (0));
+ clientApps.Start (Seconds (2.0));
+ clientApps.Stop (Seconds (10.0));
+
+For the echo client, however, we need to set five different ``Attributes``.
+The first two ``Attributes`` are set during construction of the
+``UdpEchoClientHelper``. We pass parameters that are used (internally to
+the helper) to set the "RemoteAddress" and "RemotePort" ``Attributes``
+in accordance with our convention to make required ``Attributes`` parameters
+in the helper constructors.
+
+Recall that we used an ``Ipv4InterfaceContainer`` to keep track of the IP
+addresses we assigned to our devices. The zeroth interface in the
+``interfaces`` container is going to correspond to the IP address of the
+zeroth node in the ``nodes`` container. The first interface in the
+``interfaces`` container corresponds to the IP address of the first node
+in the ``nodes`` container. So, in the first line of code (from above), we
+are creating the helper and telling it so set the remote address of the client
+to be the IP address assigned to the node on which the server resides. We
+also tell it to arrange to send packets to port nine.
+
+The "MaxPackets" ``Attribute`` tells the client the maximum number of
+packets we allow it to send during the simulation. The "Interval"
+``Attribute`` tells the client how long to wait between packets, and the
+"PacketSize" ``Attribute`` tells the client how large its packet payloads
+should be. With this particular combination of ``Attributes``, we are
+telling the client to send one 1024-byte packet.
+
+Just as in the case of the echo server, we tell the echo client to ``Start``
+and ``Stop``, but here we start the client one second after the server is
+enabled (at two seconds into the simulation).
+
+Simulator
++++++++++
+What we need to do at this point is to actually run the simulation. This is
+done using the global function ``Simulator::Run``.
+
+::
+
+ Simulator::Run ();
+
+When we previously called the methods,
+
+::
+
+ serverApps.Start (Seconds (1.0));
+ serverApps.Stop (Seconds (10.0));
+ ...
+ clientApps.Start (Seconds (2.0));
+ clientApps.Stop (Seconds (10.0));
+
+we actually scheduled events in the simulator at 1.0 seconds, 2.0 seconds and
+two events at 10.0 seconds. When ``Simulator::Run`` is called, the system
+will begin looking through the list of scheduled events and executing them.
+First it will run the event at 1.0 seconds, which will enable the echo server
+application (this event may, in turn, schedule many other events). Then it
+will run the event scheduled for t=2.0 seconds which will start the echo client
+application. Again, this event may schedule many more events. The start event
+implementation in the echo client application will begin the data transfer phase
+of the simulation by sending a packet to the server.
+
+The act of sending the packet to the server will trigger a chain of events
+that will be automatically scheduled behind the scenes and which will perform
+the mechanics of the packet echo according to the various timing parameters
+that we have set in the script.
+
+Eventually, since we only send one packet (recall the ``MaxPackets``
+``Attribute`` was set to one), the chain of events triggered by
+that single client echo request will taper off and the simulation will go
+idle. Once this happens, the remaining events will be the ``Stop`` events
+for the server and the client. When these events are executed, there are
+no further events to process and ``Simulator::Run`` returns. The simulation
+is then complete.
+
+All that remains is to clean up. This is done by calling the global function
+``Simulator::Destroy``. As the helper functions (or low level
+|ns3| code) executed, they arranged it so that hooks were inserted in
+the simulator to destroy all of the objects that were created. You did not
+have to keep track of any of these objects yourself --- all you had to do
+was to call ``Simulator::Destroy`` and exit. The |ns3| system
+took care of the hard part for you. The remaining lines of our first
+|ns3| script, ``first.cc``, do just that:
+
+::
+
+ Simulator::Destroy ();
+ return 0;
+ }
+
+Building Your Script
+++++++++++++++++++++
+We have made it trivial to build your simple scripts. All you have to do is
+to drop your script into the scratch directory and it will automatically be
+built if you run Waf. Let's try it. Copy ``examples/tutorial/first.cc`` into
+the ``scratch`` directory after changing back into the top level directory.
+
+::
+
+ cd ..
+ cp examples/tutorial/first.cc scratch/myfirst.cc
+
+Now build your first example script using waf:
+
+::
+
+ ./waf
+
+You should see messages reporting that your ``myfirst`` example was built
+successfully.
+
+::
+
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+ [614/708] cxx: scratch/myfirst.cc -> build/debug/scratch/myfirst_3.o
+ [706/708] cxx_link: build/debug/scratch/myfirst_3.o -> build/debug/scratch/myfirst
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+ 'build' finished successfully (2.357s)
+
+You can now run the example (note that if you build your program in the scratch
+directory you must run it out of the scratch directory):
+
+::
+
+ ./waf --run scratch/myfirst
+
+You should see some output:
+
+::
+
+ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+ Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+ 'build' finished successfully (0.418s)
+ Sent 1024 bytes to 10.1.1.2
+ Received 1024 bytes from 10.1.1.1
+ Received 1024 bytes from 10.1.1.2
+
+Here you see that the build system checks to make sure that the file has been
+build and then runs it. You see the logging component on the echo client
+indicate that it has sent one 1024 byte packet to the Echo Server on
+10.1.1.2. You also see the logging component on the echo server say that
+it has received the 1024 bytes from 10.1.1.1. The echo server silently
+echoes the packet and you see the echo client log that it has received its
+packet back from the server.
+
+Ns-3 Source Code
+****************
+
+Now that you have used some of the |ns3| helpers you may want to
+have a look at some of the source code that implements that functionality.
+The most recent code can be browsed on our web server at the following link:
+http://code.nsnam.org/ns-3-dev. There, you will see the Mercurial
+summary page for our |ns3| development tree.
+
+At the top of the page, you will see a number of links,
+
+::
+
+ summary | shortlog | changelog | graph | tags | files
+
+Go ahead and select the ``files`` link. This is what the top-level of
+most of our *repositories* will look:
+
+::
+
+ drwxr-xr-x [up]
+ drwxr-xr-x bindings python files
+ drwxr-xr-x doc files
+ drwxr-xr-x examples files
+ drwxr-xr-x ns3 files
+ drwxr-xr-x samples files
+ drwxr-xr-x scratch files
+ drwxr-xr-x src files
+ drwxr-xr-x utils files
+ -rw-r--r-- 2009-07-01 12:47 +0200 560 .hgignore file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 1886 .hgtags file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 1276 AUTHORS file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 30961 CHANGES.html file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 17987 LICENSE file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 3742 README file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 16171 RELEASE_NOTES file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 6 VERSION file | revisions | annotate
+ -rwxr-xr-x 2009-07-01 12:47 +0200 88110 waf file | revisions | annotate
+ -rwxr-xr-x 2009-07-01 12:47 +0200 28 waf.bat file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 35395 wscript file | revisions | annotate
+ -rw-r--r-- 2009-07-01 12:47 +0200 7673 wutils.py file | revisions | annotate
+
+Our example scripts are in the ``examples`` directory. If you click on ``examples``
+you will see a list of files. One of the files in that directory is ``first.cc``. If
+you click on ``first.cc`` you will find the code you just walked through.
+
+The source code is mainly in the ``src`` directory. You can view source
+code either by clicking on the directory name or by clicking on the ``files``
+link to the right of the directory name. If you click on the ``src``
+directory, you will be taken to the listing of the ``src`` subdirectories. If you
+then click on ``core`` subdirectory, you will find a list of files. The first file
+you will find (as of this writing) is ``abort.h``. If you click on the
+``abort.h`` link, you will be sent to the source file for ``abort.h`` which
+contains useful macros for exiting scripts if abnormal conditions are detected.
+
+The source code for the helpers we have used in this chapter can be found in the
+``src/helper`` directory. Feel free to poke around in the directory tree to
+get a feel for what is there and the style of |ns3| programs.