You are on page 1of 12

How to Install Castalia

General
Castalia is a simulator for WSN and similar networked embedded systems based on
OMNeT++. Castalia is a modular and extendable simulator. If Castalia was only simulating a
specific behaviour or distributed algorithm for WSN it would be of little use to the WSN
community. Users are expected and assisted to create their own applications and protocols. That
means users can change the code of certain modules or introduce new modules altogether. Since
the users can considerably change the source code and rebuild the simulator many times (as
contrasted to building the simulator once and just execute it) we provide some assistance for this
mode of usage by automating the building process and alleviating the user from the need to
manually edit various Makefiles. Because of Castalias usage mode, the installation is slightly
more complicated than the usual ./config and make commands. There are 3 general steps in
building Castalia: 1) edit configuration files (in standard installation you just edit the directory
path that the source code resides), 2) run the provided script makemake that produces various
Makefiles within the source code directory tree, and finally 3) type make to build Castalia.
Following are detailed instructions about installing OMNeT and Castalia.

Installing OMNeT++
Castalia is based on OMNeT++. Website: http://www.omnetpp.org If you do not have
OMNeT++ in your system, download the source code from the website. The version of OMNeT
we have built and tested Castalia with, is 3.3p1. This is the version we recommend. Version 4.0
has not been tested and reportedly does not work with the current version of Castalia. We
recommend a Linux/Unix system for a smoother installation process although OMNeT++ can be
installed in Windows or in Cygwin under Windows. The instructions given henceforth refer to a
Linux/Unix/Cygwin environment
For Windows instructions or general OMNeT installation troubleshooting refer to
http://www.omnetpp.org/pmwiki/index.php?n=Main.OmnetppInstallation
Decompress the source file by typing
tar -xvzf omnetpp-3.3p1-src.tgz
You will have a directory named omnetpp-3.3p1 where all the source code resides.

In order to build OMNeT you do the following:


Set environment variables by typing (assuming you are using bash as your shell)
export PATH=$PATH:~/omnetpp-3.3p1/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/omnetpp-3.3p1/lib

Also add the above 2 commands at the end of your .bash_profile file.

Then check configure.user to make sure it contains the settings you need:
vi configure.user (or use an editor other that vi)

Suggested changes: If you are planning to change the simulator code then it is a good idea to use
CFLAGS that use the g option (fro example the g wall option) so that OMNeT is built with
debug information. Otherwise you can stay with the current CFLAGS choice (optimized for
speed). Since Castalia does not use any of the graphical user interfaces of OMNeT you do not
have to compile for the GUI stuff (and thus saving yourself from complications that have to do
with Tcl and BLT installation). Find the line NO_TCL=true in the configure.user file
and uncomment it. Alternatively, you can leave the flag as is, so that you can use the generic GUI
tools that OMNeT offers, with. Finally, change the flag WITH_PARSIM to no, because you
might get compilation problems when it is set to yes, and this feature (parallel distributed
simulation) is not really needed. Finally, OMNeT++ must be compiled with dynamic NED
loading enabled, so make sure that WITH_NETBUILDER = yes.
Then the usual GNU-related stuff:
./configure
make

You are now done building OMNeT.


Make sure that OMNeT++ is in the path (to test, try the command "which opp_makemake").
If you opted for setting NO_TCL=true then the building process will stop at the examples (first
example is aloha which will not build as it requires Tcl/Tk). That is fine.

Installing Castalia
Get the source code from http://castalia.npc.nicta.com.au/ .
Assume the file you downloaded is named Castalia-2.1.tgz.gz
Untar and unzip the source code file by issuing the following command:
tar xvzf Castalia-2.1.tgz.gz

A new directory will be created, named Castalia/


Make sure that you have the access rights to execute scripts in Castalia/. Try running the
fix_permissions script. If you cannot, do chmod u+x fix_permissions and then try
again. The script will give you the correct access rights to all other scripts you need to run.
The procedure to build Castalia is the following:
1. Go to the Castalia/config directory and edit the Castalia.config file so that
the line
ROOT=$(HOME)/YOUR_PATH_TO_CASTALIA/
contains the right location of Castalia on your local disk .
Make sure you include a / character at the end of the path.
For example, ROOT=$(HOME)/research/Castalia/ is correct
while

ROOT=$(HOME)/research/Castalia

is not.

2. Go to the Castalia/directory and type the command:


./makemake
Then wait for some time till the script ends and you see the message:
Regenerating nedfiles.lst...
Done

3. Now the appropriate Makefiles have been generated. From the directory Castalia/
type the usual build command:
make
Wait again for sometime until everything is built.
Check the directory Castalia/bin for the generated binary/executable file
CastaliaBin
You have now successfully built Castalia.

Running a Test Simulation


Go to the directory Castalia/Simulations/valuePropagation. It should include
at least two files: omnetpp.ini and runValProp. The latter is a script.
Run the script:
./runValProp
You will see a message informing you where the simulator output is written. The simulation
should be over pretty quickly and then you will see the command line prompt again.
Simulation results (showing remaining node energy among other quantities) are written
in the file Castalia-Primary-Output.txt. Check if this file was created and what are its
contents. If you would like to understand what the application is doing and what the output file
means, read section 3.1 of Castalias User Manual.

At this stage you are ready to use Castalia. The Castalia User Manual is your guide. The
first three chapters are the introductory ones.

The rest of this installation guide is devoted to instructing you on how to build Castalia when you
want to add your own custom modules and also how to use Castalia with the Eclipse IDE. The
latter is not essential for Castalia to work, it just guides you on how to use Eclipse, which is a
powerful and helpful IDE.

Building Castalia with your additional custom source code


Castalia is built for extension. Users are encouraged to do their custom modifications and
add their own modules. But how do you build Castalia once you have modified it? If you just
updated existing source files then the answer is simple: Just type make again from the Castalia
root directory (we assume here that you have built Castalia once following the steps given in the
first part of this Installation Guide. What if though, you have created a whole new module with a
few .cc and .h files and OMNeT .ned and .msg files? Normally, in a simple C/C++ source code
package you would update the Makefile of the project to include the dependencies of your new
files and actions to compile them. But as you have noticed, Castalia automatically produces
several Makefiles based on some configuration files and the script makemake. This automation
makes the building process of Castalia more manageable but also requires some explicit
instructions to the new Castalia user/developer. Heres what you need to do.
First make sure that the files and directory structure follow the module structure. For
example,

place

files

for

new

MAC

module

named

SuperMAC

in

src/Node/Communication/MAC/SuperMAC. You do not have to, but it is good practice


and it would help with our description here. Then follow these steps:

1) Change to directory config/ and modify the file makemake.config (this file is used by
the script makemake and contains information on how to generate Makefile files) like so:
Add to the ALL_WSN_INCLUDES variable, every new directory that either contains an *.h (C++
header) file or it will contain one after the invocation of makemake1. Assume that we have .h
and .msg file in the directory of SuperMAC and one more .h file in a subdirectory called support.
Then we add the following string
-I$(SRCDIR)/Node/Communication/MAC/SuperMAC
-I$(SRCDIR)/Node/Communication/MAC/SuperMAC/support

Update the WSNetwork target by telling it to go to your each new directory you created and
run makemake with some options. The options should include the directories that are needed by
the source files of the added new directory. In our example with the new MAC:

An .h file will be created automatically by opp_makemake (which in turn is called by makemake)


when processing .msg files. So as a general rule: an .msg file will create a corresponding .h file.

cd

$(SRCDIR)/Node/Communication/MAC/SuperMAC

&&

$(MAKEMAKE)

$(OPTS) -n -r -I$(SRCDIR)/Node/Communication/MAC/SuperMAC
-I$(SRCDIR)/Node/Communication/MAC/SuperMAC/support

cd

$(SRCDIR)/Node/Communication/MAC/SuperMAC/support

&&

$(MAKEMAKE) $(OPTS) -n -r
- I$(SRCDIR)/Node/Communication/MAC/SuperMAC/support

2) [optional] You may wish to add dependencies across directories. To do that, create a file with
name makefrag and place it inside the directory where you wish to add the dependencies
among its subdirectories/modules. You can add as many makefrag files as the total number of
the produced Makefile

files by the makemake

script. The opp_makemake

injects/includes the makefrag inside the generated Makefile. Adding makefrag files is a
good way to keep some extra settings inside the Makefile files without loosing it every time
they are regenerated by the makemake script (which uses the opp_makemake tool).

3) [optional] If there are some extra/external libraries/header files that you'd like to include inside
all

the

produced

Makefile

files

then

uncomment

the

two

last

lines

of

config/Castalia.config and modify them as you wish.

4) Now you are ready to rebuild! Go to the root Castalia directory and type make clean to get
rid of the old object files and executables (you do not have to, but it is generally good practice)
and then the usual:
./makemake

and after it finishes

make

Using Eclipse IDE to build/modify/extend Castalia sources


Integrating Castalia into Eclipse is quite simple despite the extensive length of this
section. Working with Eclipse will pay the developer back in the long term, by saving time. The
descriptions that follow are very detailed. Many of the procedural steps will be very trivial for an
advanced user. About half of the information in this chapter is dealing with how you install Java,
Eclipse and the CDT plugin for Eclipse. This information could be omitted from this manual but
for the sake of completeness and for the convenience of the prospective users of Castalia has been
included. Since the information is very similar for Windows and Linux, this section covers both
cases, marking Windows information in blue color fonts.

What is Eclipse(1) ?
Eclipse [http://www.eclipse.org] is an open source platform-independent software
framework for delivering what the project calls "rich-client applications", as opposed to "thin
client" browser-based applications. So far this framework has typically been used to develop
Integrated Development Environments (IDEs), such as the Java IDE called Java Development
Toolkit (JDT) and compiler (ECJ) that comes as part of Eclipse (and which are also used to
develop Eclipse itself). Eclipse is also a community of users, constantly extending the covered
application areas. An example is the recently created Eclipse Modeling Project, covering most
areas of Model Driven Engineering.Eclipse was originally developed by IBM as the successor to
its VisualAge family of tools. Eclipse is now managed by the Eclipse Foundation, an independent
not-for-profit consortium of software industry vendors. Many notable software tool vendors have
embraced Eclipse as a future framework for their IDEs.
(1)

information is based on the wikipedia.org resource

How can I use a Java-based IDE like Eclipse for the C++ based Castalia/Omnet++ ?
One of the most successful Language IDE projects of eclipse is the C/C++ Development Tools
Project (CDT) [website] is working towards providing a fully functional C and C++ Integrated
Development Environment (IDE) for the Eclipse platform.

Why should I use an IDE and why should I specifically use Eclipse [full article]?

An IDE saves you time (if you are making frequent/extensive changes to the code). It
provides easy build, debug, code highlighting, code completion, integration with any C++
compiler and with the Make - GNU build system.

Eclipse is a very active open source project with a huge community to support it. It has
being tested in the market by very large commercial projects that use it. It provides many
open source plug-ins, making development easier and more efficient.

Eclipse works for both Windows and Linux

How to install Eclipse?


A. Instructions for Linux-based systems
 Step 1: Install Java
Go to the download page of Sun Microsystems [Download Java link] and
download the latest JDK (current version is JDK 6). Instead of installing the full
JDK, you can only install the Java Runtime Environment 5.
However, it is always a good thing for a developer, to have the Java(TM) compiler
of Sun Microsystems installed on his/her machine. For that reason, JDK is a better
option.
Don't forget at the end of the installation to modify the PATH (path to JRE or
JDK /bin directory), JAVA_HOME(path to installation directory of JRE or
JDK) and CLASSPATH (add .) environment variables.


Step 2: Install Eclipse 3.2.1 software (It does not include Java 5.0)
 Visit the download page of eclipse.org and get the latest version of Eclipse
IDE SDK.
 Once you download eclipse-SDK-3.2.1-linux-gtk.tar.gz file, move it into the
directory that you wish to install Eclipse.
 Open a new konsole
 Change to the directory that the eclipse tar.gz file resides type the command :
tar -zxvf eclipse-SDK-3.2.1-linux-gtk.tar.gz
 You will then see that a new folder named eclipse has been created. In that
folder you will find the eclipse application/executable. We recommend to
create a shortcut on the desktop to simplify the launching of eclipse. Notice
that Eclipse does not have an installation process. Once you have unzipped
the file you are done.

Step 3: Launch Eclipse


Follow the steps in launching Eclipse [launching link].
The instructions are written for Windows OS but there is no difference for Linux
environments.

Here

is

link

to

an

animated

demonstration

of

the

installation

process:

http://mirror.pacific.net.au/eclipse/technology/phoenix/demos/install-eclipse/install-eclipse.html

Do you face problems installing Eclipse?


At [http://max.berger.name/howto/cdt/ar01s04.jsp] you can find an EXCELLENT detailed guide
with screen shots for installing Eclipse.

How to install the C/C++ Development Tools Project (CDT) on Eclipse?


The following installation directions are the same for both Linux -based and Windows
systems.
4.
5.
6.
7.
8.
9.

Start Eclipse.
Go to Help -> Software Updates -> Find and Install....
Select "Callisto Discovery Site" and click "Finish" button.
A pop-up window opens with title: "Update Sit Mirrors.
Select a mirror that is closer to your location and press "Ok".
A new window pops up with title "Updates". Expand the "Callisto Discovery
Site" node and see what are the components of the subtree under that node.
10. Select (place a check in the check box) the latest version of "Eclipse C/C++
Development Tools" under "C and C++ Development" (3.1.1 at the time of this
writing).
11. Select the "Next" button.
12. The license agreement window pops-up. Read the license carefully and select the
"I accept ...." radio button at the bottom.
13. Click the "Finish" button.
14. It will warn you that the Eclipse CDT is an "unsigned feature". But you can just
ignore that and select "Install All".
15. Wait until files are downloaded and installed on your computer.
16. Restart Eclipse.
17. Check that at the menu "File-->New-->Project" there the 2 new items: C and C++
18. Congratulations! CDT is installed and ready for use.
Here is a link to an animated demonstration of the CDT installation process::
http://mirror.pacific.net.au/eclipse/technology/phoenix/demos/install-cdt/callisto-cdt.html

Do you face problems installing CDT?


At [http://max.berger.name/howto/cdt/cdt.pdf] you can find an excellent detailed guide with
screen shots for installing CDT under both Windows and Linux opersating systems.
Another good one can be found at http://www.cs.umanitoba.ca/~eclipse/7-EclipseCDT.pdf.

Castalia and Eclipse

Using Eclipse to write new code or modify the existing code of Castalia will save you
time and will make your life easier. We use Eclipse with CDT to write code for the simulator and
we owe a big thanks to the community of Eclipse. We assume here that you have installed
Eclipse, the C/C++ Development Tools, and OMNeT++
Now you are ready to create and configure your Castalia project in Eclipse

CREATING A NEW PROJECT


Step 1: Open Eclipse.
If your OS is Linux-based then it is recommended to do the following trick so that you
open Eclipse with access to the bash shell environment.
Delete the default shortcut of Eclipse from your Desktop.
Create a file with name runEclipse.sh somewhere at your home directory with the
following contents:
#!/bin/bash
/PATH_TO_ECLIPSE_MAIN_FOLDER_ON_YOUR_SYSTEM/eclipse
Attention: The path normally will be of the form xxxxxxx/eclipse/eclipse (for example
/Custom-Programs/eclipse/eclipse).
This file is a script that calls the executable of Eclipse under the bash shell. In addition
you have to make sure that this file has execution rights (e.g. you can issue a command
like chmod 755 runEclipse.sh ).
Create a new shortcut to your Desktop pointing to the exact location of runEclipse.sh.
If you are not satisfied with the icon of your shortcut, you can always choose the eclipse
Application Icon in the properties of that file (depending on the X environment that you
use e.g. Gnome/KDE ).
Now, double-click the Shortcut and give Eclipse some time to initialize and start.
Step 2: Choosing a workspace
By default Eclipse asks you whether or not you want to use the default Workspace. It is
on your personal preference the choice of that location. Workspace is nothing more than
a folder that contains some meta-data/settings related to your projects and your system
configuration. It is a good tactic to place all your projects inside a workspace. This is not
however mandatory. You can have the project folders residing at various locations, but
keep in mind that the workspace folder will contain configuration settings and indexes to
them.
Step 3: Create a new C++ Project
Select File --> New --> Project... , Expand the Section C++ and select Standard Make
C++ Project.
Give a project name (e.g. CastaliaSim), leave checked the Use Default location
checkbox and hit Next.
The next window is a multi-tabbed one.

10

Make Builder Tab: If you run under windows you 'll have to unselect the Use default
checkbox in the Build command section and provide the command name of the make
tool that you have installed. For example in MinGW/MSYS you have to use mingw32make. I personally like to select the Stop on first build error option.
C/C++ indexer Tab: It is recommended to disable the indexer (select the No indexer
option) because the system becomes very slow if enabled. Use an indexer if your
machine's hardware is powerful and primarly if your hard disk drive is quite fast
(something like 7200RMP or even better 10.000RMP with SATA2 interface, very small
average seek time <9ms and large cache).
Hit Finish button.
Eclipse will now generate a few things, and then ask you if you want to switch to the
C/C++ Perspective. This is a good idea, so say yes.
You have just created your Castalia project in Eclipse. Congratulations.
Step 4: Moving the Sources of Castalia in the Project's directory.
Change to the root directory of Castalia and Copy ALL the contents (bin, config,
src....etc) directly into the directory that was created by Eclipse for your project.
Step 5:Refresh the file view of Eclipse.
Maximize the window of Eclipse and select on the left of the window the C/C++
Projects tab. Right-click on the the root project-item (e.g. CastaliaSim) and select
Refresh. All the changes that you did at the directory of the project are updated inside
Eclipse.
Step 6: Modify the PATH_TO_PROJECT/config/Castalia.config file
Open
with
an
editor
(or
even
with
Eclipse)
the
PATH_TO_CASTALIA_PROJECT/config/Castalia.config file and change the value of
the ROOT variable to contain the correct path to the copy of Castalia inside the Eclipse
project folder (e.g. ROOT=$(HOME)/Developement/eclipse/Castalia).
Step 7: Create the Make targets
Select on the left of the Eclipse's main window the C/C++ Projects tab. Right-click on
the the root project-item (e.g. CastaliaSim) and select Create Make Target ..... Leave
all the check-boxes selected except if you are a Windows user and so you have to give
mingw32-make in the build command text box. Make 3 targets:
 all: type all at the Target Name and all at the Make Target
 clean: type clean at the Target Name and clean at the Make Target
 clean & all: type clean & all at the Target Name and clean all at the Make
Target.
Your targets are ready. You can see on the right of the main window of Eclipse at the tab
named MakeTargets under your project's name (e.g. under CastaliaSim)the 3 greed
circle images that look like targets. Every time you double click them is like calling the
respective make command, for example if you double-click the all target, is like issuing
the command make all at the root directory of Castalia.
Step 8: Create the makemake script target

11

This step is not necessary. It provides the ability to reproduce the Makefile files of
Castalia from inside Eclipse instead of calling the makemake script from the
Konsole/command prompt. Perform this step if you want to work JUST with eclipse and
to forget the black screen of your terminal.
Follow the same directions as in Step 7 and create a new Target with name makemake
and target name makemake as well. At the build command if you are a Linux user give
PATH_TO_CASTALIA_PROJECT/eclipseMakemake.sh -f and if you are a windows
user give PATH_TO_CASTALIA_PROJECT/eclipseMakemake.bat. Then hit the
Create button.
Create the eclipseMakemake.sh with the following contents:
#!/bin/bash
cd PATH_TO_CASTALIA_PROJECT/
./makemake
Attention: give execution rights to the eclipseMakemake.sh file.
Step 9: Create a Run configuration for Castalia
Follow from the menu bar of Castalia: Run --> Run...
Right-Click on the C/C++ Local Application and select New
Give the name CastaliaTestSimulation and at the C/C++ Application field of the Main
tab select the bin/CastaliaBin executable (the executable CastaliaBin will be created
after you first successfully build the all target). In the Arguments tab select as
working directory the /test folder inside the project of Castalia (hit the Workspace
button and navigate to the test directory).
Generaly we suggest to test and run Castalia from the command prompt, rather from
inside Eclipse.

12

You might also like