An Introduction to Using GTSNetS

Thomas Watteyne
CITI Laboratory, INSA Lyon
France Telecom R&D, Grenoble
thomas.watteyne@insa-lyon.fr
July 7, 2006

1
 This document is not written by the ocial GTNetS and GTSNetS team
at Georgia Tec, and does not reect their ideas. In particular, nor the
author, nor the GTNetS and GTSNetS teams are responsible for any
errors, or content lacking in this document. This document is distributed in
the hope that it will be useful, but WITHOUT ANY WARRANTY. All of
part of it can be copied and reused, provided you specify the source of this
document. This document is regurlarly maintained and can be found
somewhere at http://citi.insa-lyon.fr/~twatteyne. Please feel free to
send any comment or request concerning this document to
thomas.watteyne@insa-lyon.fr.
1 Introduction

GTSNetS is an extension of GTNetS. The Georgia Tech Network Simulator

(GTNetS) is an C++ open-source free event-driven simulator developped by
George Riley at Georgia Tech, Atlanta, USA. It enables researchers world-
wide to easily model and simulate computer networks both wired and wire-
less. GTNetS has been developped aiming at scalability (for more details,
see papers published by G. Riley et al.).
GTSNetS has extended GTNetS with wireless sensor network capabili-
ties. It has been developped by George Riley and his students, especially
by El-Moustapha Ould Ahmed Vall. Main contributions are the battery
and mobility models. When added to the scalability, we consider that GT-
SNetS is particularly suited for modeling and simulating large scale energy
constrained and possibly mobile wireless sensor networks.
This document is intended to be used understanding how GTSNetS works
and how it can be used for simulating the reader's own ndings. For easier
understading, we ran the Doxygen tool http://www.stack.nl/~dimitri/
doxygen/; resulting HTML documentation can be found at http://citi.
insa-lyon.fr/~twatteyne/documents/doxy_gtsnets/. This should be used
as a reference together with the GTSNetS sourcecode throughout the reading
of this document.
GTNetS and GTSNetS are hosted at http://www.ece.gatech.edu/research/
labs/MANIACS/GTNetS/. gtnets@mail.ee.gatech.edu is the mailing list, which
has 63 members on 2006/07/07.

2 Installing GTSNetS

Installation instructions can be found at http://citi.insa-lyon.fr/~twatteyne/

documents/install_gtsnets.txt. Please note that the current version on
06/05/04 does not support gcc versions newer than 4.0.1, so an adapted
version of the package can be downloaded at http://citi.insa-lyon.fr/
~twatteyne/documents/watteyne_gtsnets-pub.tar.gz. I have mainly changed
the Makele under de root.

3 Overview of the directory structure

Once installed, you should have the following directory structure and impor-
tant les:

3
 • / make.depend.dbg and make.depend.opt contain the dependencies
created during installation (using the Makefile). lib* are the li-
brairies created during installation. gtnets.el is the Emacs Lisp code
for coding in the Georgia Tech Network Simulator.

• /QTSRC/ this directory is empty

• /mk/ qtcheck.mk and rticheck.mk are les used by the makele to

detect whether qt and rti is installed.

• /SRC/ This directory contains all the source les and the header les
of GTSNetS. It contains the source les for the nodes, communication
protocols, mobility pattern, trac generation, physical link models,
battery models, and the simulator. These basic blocs will be assembled
by the user to form a given simulation scenario.

• /OBJDBG/ and /OBJOPT/ The source les are compiled to object

les and stored in these directories. When executing an object le
compiled using the debugging mode, debugging lines will be printed
on screen. Optimized compilation does not generate those lines

• /EXAMPLES/ in these directories are the real world example les.

They are again C++ source les, which aggregate the elementary bricks
in /SRC to form a real scenario. In fact, source les in /SRC are
compiled to object les in /OBJOPT/ and /OBJDBG, which are in
turn grouped into the libGTNetS-debug.so and libGTNetS-opt.so.
Those two libraries are in turn passed as parameters during compi-
lation of the simulation executable. A given simulation instance is a
given executable which you run as every other executable. Try for ex-
ample testwirelessgrid1-opt, which does nothing but moving nodes
around.

• /DOC/ documentation is generated automatically in LATEX format

from the C++ source code using the tools in the /DOC/utilities/ di-
rectory.

4 Understanding the basic building blocks

In this section, we will look more closely at the most important objects,
the elementary building blocks  in the /SRC/ directory  used to build
an simulation  in the /EXAMPLE directory. We will rst present the

4
TBC

Figure 1: the EXAMPLE le for a simple ooding scenario

simulation environement and then we will follow a down-up approach in

detailing the communication layers.

4.1 Overview of the example: the EXAMPLE le

The example le is presented in Fig. 1.

4.2 The Simulator: simulator.cc

GTSNetS is an event-driven simulator. The job of the simulator is to sched-
ule events at a given instant, advance in simulation time and execute the code
associated to a given event when the event time is reached. The Simulator
handles eventList a list of events and their associated code and schedule
time. The simulator object contains methods for scheduling, removing and
handling events.
The Run method is the key method. RTI refers to Runtime Infrastructure
which is associated to the libsync librairy created during installation, and
which provide distributed simulation capabilities. If used, each Simulator
instance will receive a dierent sysId. The Simulator object also handles
the graphical interface based on QT. As for logging, the Simulator only
provides the duration time of simulation.

4.3 Collecting statistics: trace.cc

There are two ways of getting information from the simulation: on screen and
in a le. Prints on screen are more often used for debugging and execution
tracking purposes. Trace lets you gather information for later performance
analysis in a le. This le can then be processed by tools such as Gnuplot
(http://www.gnuplot.info/).
The Trace object lets you chose what information you want to gather,
and in which le. It also lets you start and stop logging the information
during execution of the simulation.

5
4.4 The node: node.cc, node-sn.cc and node-sink.cc
The Node object is quite general: it can be a host in a wired computer
network, or in our case a wireless sensor node. We will start describing the
generic node, and then the WSN and sink node models. In the source code,
a dierence is made between Ghost nodes and Real nodes. This has to do
with the distributed simulation capability: a node is considered ghost if it
is simulated by another computer. Throughout this document, we will only
consider having one simulating computer (i.e. only "Real" nodes).
We group the main attributes of a Node object:

• Interfaces and Identication. Methods such as AddInterface or SetIPAddr

let you dene the number of interfaces a node has (wired or wireless)
and their addresses (layer 2 or 3).

• Layout. GTSNetS provides a vizualization tool. This does not inu-

ence the simulation of the network, but can largely easen interpretation
of the results. Whereas a node is by default represented by a black
square, methods such as Color or DefaultPixelSize let you change
the nodes appearance dynamically. Nodes of a same cluster can for
example have the same color.

• Position and Movement. A node is assigned a geographic position it

the 2-D simulation area and can move. Movement and position is
particularly important in a wireless application as it directly inences
reachability.

• Protocol Stack. The node is simulated using a layered approach. Meth-

ods such as InsertProto let you assign a given protocol at a given
protocol layer, and bind/unbind protocols.

• Battery and Energy. A battery is attached to each node. The battery is

modeled as a reservoir of Joules with a threshold. Several energy mod-
els can be used. After the battery of a node has reached its threshold,
the node is automatically switched o.

4.5 The battery: battery.cc

A battery, as dened in battery.cc is a reservoir of Joules with a current en-
ergy level and a minimal energy level. With method UpdateRemainingEnergy,
one can update the remaining energy. In case the current energy reaches the
minimal energy, the IsDead attribute of the node is set to Yes.

6
4.6 The mobility model: mobility-random-waypoint.cc
Nodes can be mobile in GTSNetS, this is especially interesting for evaluating
routing protocols in mobile networks. The Mobility object is a generic
object capable of updating the nodes position. It also informs the node if it
is mobile. The RandomWayPoint class inherits from the Mobility class, and
implements the random waypoint mobility model.

4.7 The physical layer: propagation.cc

A node can have a wireless interface. The interface-wireless-sn class
denes such an interface specic to wireless sensors, with a attached energy
models for transmitting, receiving and idle listening.
As for propagation, GTSNetS only implements the Free Space model and
the two way ground reexion models. They are dened in propagation.cc

4.8 The MAC layer: l2proto802.11.cc

All layer two protocols, thus classes, inherit from the L2proto class. This
class dene basic L2 behavior such as interaction with the Link class.
Currently, only one wireless layer 2 protocol has been implemented: IEEE
802.11, in class L2Proto802_11. The class L2Header802_11 denes the base
class containing the types of frames used in IEEE 802.11 (i.e. ACK_frame,
CTS_frame, DATA_frame, RTS_frame).

5 Understanding a simple simulation

Now that we have seen an overview of the basic building blocs provided in
the /SRC directory, we will go into the /EXAMPLE directory and look at
an example le.
We will study the le testwirelessgrid.cc. This simulation puts 500
nodes on a 500mx500m rectangular region. Deployment is done using po-
lar coordinates (as shown in SRC/wireless-grid-polar.cc). The passed
parameters mean that node's distance to the center should have an expo-
nential distribution, i.e. probability of being at a given distance form the
center decreases exponentially when this distance grows.
Once the nodes are positionned, each node is aected a mobility model, in
this case random waypoint. In this mobility model (shown in SRC/mobility-random-waypoint.cc),
the node choses some location with the same exponential distribution and
picks a random duration to get there. It's speed is constant. Once there, the

7
Figure 2: 99 randomly places black nodes and a centered red sink node in a
10mx10m region.

node randomly picks a waiting time, and after that it starts chosing a new
location.
This example is very easy in that it only uses ready-made objects, and
does not involve communication. In the next section, we will build a new
example le and go more into the details of transmitting information over a
wireless channel.

6 Simulating using the basic building blocks

In this, section, instead of just analysing an existing simulation, we will build

our own simulation. Nevertheless, we will only use the existing basic building
blocs, i.e. we will not modify the content of the /SRC directory.
We want to simulate a WSN composed of 100 nodes randomly deployed
inside a 10mx10m area. The sink node will be initialy placed in the middle of
this area and colored red. During simulation, it will be moving and visiting
3 dierent spots. Each other node will send a message to the sink every
second. All nodes are within reach, so node-to-sink communication is done
in one hop. A routing layer is therefore useless, and underlying MAC layer
is IEEE 802.11. Resulting deployment can be seen in Fig. 2.
The resulting code can be found at http://citi.insa-lyon.fr/~twatteyne/
documents/onereportpersecond.cc.
Here are some clues to understand the code:

• we have chosen to dene simulation parameters both as global variables

8
 and variables inside the main function.

• RandLocation is a straighforward function which return a random po-

sition inside a rectangular region. It is alternatively possible to use
ready-made Objects such as WirelessGridPolar, but these objects
hide some information. We thought it was more useful for rm under-
standing to re-code a similar function.

• classes MyEvent and MyTrigger are used to schedule new events dur-
ing simulation. Once again, these classes are dened for rm under-
standing, most examples hide those functions inside ready-made ob-
ject. MyTrigger basically sends a layer 3 packet on the calling nodes
interface, and changes to node's color from blue to green and vice versa.
Note the Schedule(Time("1sec")); line which reschedules itself one
second later. This way, calling node will continuously send packets,
one per second.

• in the trace le, dened at the begining of the main function, we will
gather the trace of all sent packets (on our case only layer 3 packets).

• we have chosen to dierenciate initialization of the sink node and of

normal nodes. All nodes are created using the WirelessLink* wlink
object created above. This object creates a wireless link, running the
IEEE 802.11 protocol and the two way ground reection propagation
model. The constructor's rst parameters denes the number of node
using this link; and the GetNode method is used to get those nodes.

• the sink node is colored red, and is mobile. The AddWaypoint method
denes the locations it will pass through, and the passing instants.
There will be no pause times.

• The normal nodes do not move. Note the (new MyTrigger(n[i]))->Schedule(((double)rand())/((d

line which schedules the rst packet to be sent. (double)rand())/((double)(RAND_MAX)
returns a random value between O and 1, so nodes do not start sending
in an unsynchronized fashion.

• we have dened a variable called print which if set to true makes
the simulator print out the IP addresses of each nodes. This is only
for debugging purposes.

• At the end of the le, we ask the Simulator object to display the
topology or screen.

9
 During execution, the topology on screen shows the sink node moving
and the other 99 nodes changing there colors when sending a packet. In-
side the console, HuH? IPV4 indication with no l4demux object proto
number 0 means that, at the sink, the packets were received, but with no
layer 4 header. This warning can be ignored, but it is useful because it
informs us that the sink has received our packets.

7 Understanding the code by creating our own ap-

plication

In this section, we will further go into detail of how the code works. We will
start by creating a new application, and then look at the interaction between
this application and the lower layers.
The "application" is the entity in GTSNetS which controls the gener-
ation of messages. We want this application to periodically generate a
message in all node which are within a geographical region. Resulting
code can be found at http://citi.insa-lyon.fr/~twatteyne/documents/
application-geo.cc which you will need to install in the /SRC directory.
The corresponding example le can be found at http://citi.insa-lyon.
fr/~twatteyne/documents/geographic.cc. This one goes in the /EXAM-
PLE directory. Once installed, run a make in EXAMPLE/, and a make at
the root.
Some explanation about geographic.cc, thou this is very similar to
onereportpersecond.cc:

• test

8 Simulating with your own blocks

Now that we have understood how to use the basic blocks provided by GT-
SNetS in the SRC/ directory, we will construct our own block. The simulation
we want to run is an extension of the simulation built in the previous section.
The sink node will stay at location 5,5, but the nodes will not be able to
reach is directly. A multihop routing scheme is needed. We will use greedy
geographical forwarding, in which each node sends its data to its neighbor
closest to destination. This simulation is somewhat articial as we consider
each node knows its neighbors and their positions.
TBC

10