VANET-Skeleton for ns2

Daniel Jungels Laboratory for computer Communications and Applications (LCA) EPFL December 23, 2005
This document quickly describes how to install ns2, and how to implement a VANET protocol (using a broadcast example protocol as basis).

NS2

First, you have to install the network simulator in your home directory. The simplest way to get started is to use the ns-allinone package. At the moment of this writing, version 2.29 was the most recent one. Because of this, all line-numbers later in this document (given to help you nd the mentioned code parts faster) refer to this version. However, there is always an explanation in what enum, class or function the changes have to be made. In the explanations, I use /home/myuser as home directory, and the simulator will be installed in /home/myuser/ns-allinone-2.29. You can nd ns-allinone at http://www.isi.edu/nsnam/ns/. The downloaded archive les ns-allinone-2.29.tar.gz (from the ns website) and vanetrbc-ns229.tgz (from http://ivc.ep.ch/) are now supposed to be in /home/myuser. I also suppose that you are using Linux (for example the LCA project PCs at EPFL, you can also connect via ssh from a Windows PC to those machines). So, we start by extracting and installing the ns-allinone package: cd /home/myuser tar -xvzf ns-allinone-2.29.tar.gz cd ns-allinone-2.29 ./install This takes a while (both the extraction of the les and the installation). After the installation script has nished successfully, you must edit your shell conguration les (this is also explained at the end of the installation script): I give here the examples for bash and tcsh. For tcsh, add the following lines to /home/myuser/.cshrc: set path = ( ${path} /home/myuser/ns-allinone-2.29/bin \ /home/myuser/ns-allinone-2.29/tcl8.4.11/unix \ /home/myuser/ns-allinone-2.29/tk8.4.11/unix ) set LD_LIBRARY_PATH = ( /home/myuser/ns-allinone-2.29/otcl-1.11 \ /home/myuser/ns-allinone-2.29/lib ) set TCL_LIBRARY = ( /home/myuser/ns-allinone-2.29/tcl8.4.11/library )

For bash, add the following lines to /home/myuser/.bashrc: PATH=${PATH}:/home/myuser/ns-allinone-2.29/bin PATH=${PATH}:/home/myuser/ns-allinone-2.29/tcl8.4.11/unix PATH=${PATH}:/home/myuser/ns-allinone-2.29/tk8.4.11/unix export PATH LD_LIBRARY_PATH=/home/myuser/ns-allinone-2.29/otcl-1.11:${LD_LIBRARY_PATH} LD_LIBRARY_PATH=/home/myuser/ns-allinone-2.29/lib:${LD_LIBRARY_PATH} export LD_LIBRARY_PATH TCL_LIBRARY=/home/myuser/ns-allinone-2.29/tcl8.4.11/library:${TCL_LIBRARY} export TCL_LIBRARY Reload your shell-conguration: for tcsh execute in your terminal source /home/myuser/.cshrc or for bash source /home/myuser/.bashrc or simply logout and login again. Now ns should be installed and ready to use.

Adding the VanetRBC protocol

Now we install an example protocol, that you can use as a basis for your own protocol. Please keep in mind that this protocol (as it is in the archive) does not do anything useful apart from creating channel load, but you can use it to inspire yourself for getting started with your protocol. Extract all the data from the tgz-archive: cd /home/myuser mkdir /home/myuser/ns-allinone-2.29/ns-2.29/vanetrbc tar -xvzf vanetrbc-ns229.tgz -C /home/myuser/ns-allinone-2.29/ns-2.29/vanetrbc To make ns aware of your protocol, edit the following les: In ns-allinone-2.29/ns-2.29/common/packet.h, in the enum packet t (line 170), insert (dont forget the comma at the end) PT_VANETRBC, and in the same le in the class p info (line 266), insert name_[PT_VANETRBC]="VanetRBC"; In ns-allinone-2.29/ns-2.29/tcl/lib/ns-packet.tcl, in the foreach prot loop calling add-packetheader, insert (e.g., line 156) VanetRBC # Vanet protocol (or your comment)

 In ns-allinone-2.29/ns-2.29/tcl/lib/ns-default.tcl, for example at the end of the le, insert these lines (these are example values used to initialize the parameters, but they can always be overriden in your TCL-scripts): Agent/VanetRBC set interval_ 1 Agent/VanetRBC set jitterFactor_ 0.005 Agent/VanetRBC set crypto_delay_ 0

In ns-allinone-2.29/ns-2.29/Makele: in the OBJ CC part, insert (dont forget the backslash at the end) vanetrbc/vanetrbc.o vanetrbc/vanetrbc_rxdatadb.o \

The following changes are not strictly necessary, but probably you want to make them to prevent lots of messages cluttering up your screen (forcing you to search for the messages you actually want to see): In ns-allinone-2.29/ns-2.29/mobile/dumb-agent.cc (line 96), you may comment out the line printf("Recvd brdcast pkt\n");

since in VANET, all packets are broadcast. In ns-allinone-2.29/ns-2.29/mobile/propagation.cc (line 158): printf("%lf: d: %lf, Pr: %e\n", Scheduler::instance().clock(), d, Pr);

For the beginning, this printf may be useful because you can see where your simulation is right now (time), and what distances are used in your scenario (i.e., if your transmission range is dened correctly). However, after some time they become annoying. So maybe leave them for now, but you may comment out this printf later. Finally, you can recompile ns, with the new protocol: cd /home/myuser/ns-allinone-2.29/ns-2.29/ make clean make The make clean is necessary because you have changed some header-les, but not the .cc les (therefore, make does not notice that you changed the .h). The example RBC protocol should be ready to run. You can execute a test script (containing also the necessary parameters for 802.11a) with cd /home/myuser/ns-allinone-2.29/ns-2.29/vanetrbc ns vntest.tcl If at the end of the simulation you get an error message saying that nam could not be executed, please read Section 4.4. 3

Adding your protocol

You can now take the RBC-protocol as a basis for your VANET protocol. There are lots of comments in the source les, have a look at them! You may also want to rename the entire stu, simply check for RBC (or rbc) and change them to your own protocol name (in the .cc and .h les in the vanetrbc directory, and in all places that you changed in the previous section). Please note that if you make a copy of the VanetRBC protocol in a dierent directory, and want both to co-exist (your protocol and VanetRBC ), you must rename the structures of the packet headers in your new protocol, so that no packet headers of the two protocols share the same name. While developing (debugging) your protocol, it is not necessary to redo the make clean every time you recompile the code. If you change a header le of your protocol (but not a general le of the rest of the ns-core), a touch *.cc in the directory containing your protocol is sucient. To recompile ns with your updated protocol, simply execute make in the ns-allinone-2.29/ns-2.29/ directory.

4
4.1

Hints for implementing your VANET protocol

Tracelog

The tracelog le can be used in dierent ways, depending on your preferences. One example is to simply use it as replacement for the standart output (stdout), so dumping normal human readable text to it. Another way (which is especially interesting when regularly dumping some parameters to the le) is to put all necessary information on one line (with spaces as separator), and put a special keyword in front of it. Like this, it becomes possible to parse the le (for example with awk ) in exactly the same way as the normal traceles. In the awk-lters, you simply choose the parameters you need, and you ignore the rest. The advantage of using this special tracele for such protocol-related status dumps (instead of the normal tracele) becomes clear when running simulations with a high number of nodes: parsing several times (with dierent awk-lters) a tracele of 1 Mbyte is faster than parsing several times a le of 1 or 2 Gbyte.

4.2

Performance issues

If you need to regularly (e.g., every 100 ms) dump some statistics (or values of some variables) to the tracelog le, for example for evaluating them afterwards with awk, it is very inecient to schedule a function in the TCL-script with this period (i.e., create a for-loop that schedules all these events). When the period becomes small (and thus the number of events increases), the time it takes TCL to sort the event list becomes extremely high. In this case, it is better to move this to the C++ part: in the same way as the timer for sending regularly messages, implement a timer for dumping the statistics. If you only want to dump some statistics at the end of your simulation, it is of course enough to put a function that dumps the necessary data, and to call it once or a few times from the TCL script (without timer).

4.3

Comment on the data included in the archive

Please also note, that the scenario included in the skeleton is a very reduced example! It only uses 50 nodes (which for some simulations may not be enough), and has only mobility information for 80 seconds (which is probably not enough for real simulations, because of the low speed of the vehicles in this scenario). You may use this for your rst tests, but afterwards it is probably

a good idea to generate some more relevant scenarios. For your information, this example has been generated with the Rice Mobility generator, using the West university place data le as input.

4.4

Compilation of nam failed

In some cases (with specic versions of gcc) the compilation of nam may fail (you may notice this for example, when trying to execute nam, and there is no executable le in the bin directory. If this happens to you, try to recompile nam, cd /home/myuser/ns-allinone-2.29/nam-1.11/ make and check if the error message comes from the agent.h le. If this is the case, open the le agent.h and replace NULL by 0 at the declaration of ndClosestCornertoPoint (line 73). Restart compilation (make). After a successful compilation, add a symbolic link to the bin directory (to be able to call nam from everywhere, since bin is in the path): ln -s /home/myuser/ns-allinone-2.29/nam-1.11/nam /home/myuser/ns-allinone-2.29/bin/nam

4.5

More documentation

The ns Manual contains a lot of details, you may have a look at it if you run into trouble. http://www.isi.edu/nsnam/ns/ns-documentation.html You may also go through Marc Greis ns tutorial. It quickly explains the basics of ns2. http://www.isi.edu/nsnam/ns/tutorial/ If you are new to TCL, this tutorial explains quite well the basics: http://www.tcl.tk/man/tcl8.5/tutorial/tcltutorial.html The MASIMUM project has created a document (also a sort of tutorial) on how to implement a routing protocol in ns2: Implementing a New Manet Unicast Routing Protocol in ns2. Even though this is unicast, it also may give you some hints for implementing your protocol. http://masimum.dif.um.es/ Realistic Mobility Modelling for Mobile Ad Hoc Networks: the previously mentioned mobility generator from Rice. http://www.cs.rice.edu/amsaha/Research/MobilityModel/ The homepage of the EPFL Vehicular Networks Security project: http://ivc.ep.ch/