nsmiracle/dei80211mr mini-HowTo


  1. Introduction
  2. Requirements
  3. Installation
    1. ns-allinone with patch for dynamic libraries
    2. dei80211mr
    3. nsmiracle

1. Introduction

Here is a very brief tutorial for the installation of the nsmiracle and dei80211mr extensions for the NS simulator.

This tutorial has been written by Nicola Baldo — baldo at dei.unipd.it

2. Requirements

You need the following things:

Back to Index

3. Installation

We will now explain step-by-step the installation process. In this tutorial, we will assume that all downloaded packages have been put in the directory /locale/ns, as shown here below:

baldo@pcsignet08:/locale/ns$ ls -l
total 69820
-rw-r--r--  1 baldo dottor   363882 Apr 23 13:53 dei80211mr-1.0.tar.gz
-rw-r--r--  1 baldo dottor 70466306 Apr 17 19:45 ns-allinone-2.31.tar.gz
-rw-r--r--  1 baldo dottor   558144 Apr 23 13:53 nsmiracle-1.0.tar.gz
-rw-r--r--  1 baldo dottor    19681 Apr 17 19:46 patch-dl-ns-2.31

Furthermore, we assume that the user has write permission on the directory /locale/ns/ — this is needed e.g. to create the directory /locale/ns/lib in which dynamic libraries will be installed.

Of course, your mileage may vary — just adjust the paths to your needs.

Back to Index

3.1 ns-allinone with patch for dynamic libraries

Unpack the ns-allinone package:

baldo@pcsignet08:/locale/ns$ tar xzf ns-allinone-2.31.tar.gz

Apply the patch for dynamic libraries:

baldo@pcsignet08:/locale/ns$ patch -p0 < patch-dl-ns-2.31
patching file ns-allinone-2.31/ns-2.31/common/packet.cc
patching file ns-allinone-2.31/ns-2.31/common/packet.h
patching file ns-allinone-2.31/ns-2.31/common/ptypes2tcl.cc
patching file ns-allinone-2.31/ns-2.31/trace/cmu-trace.cc
patching file ns-allinone-2.31/ns-2.31/trace/cmu-trace.h
patching file ns-allinone-2.31/ns-2.31/tcl/lib/ns-default.tcl
patching file ns-allinone-2.31/ns-2.31/tcl/lib/ns-lib.tcl
patching file ns-allinone-2.31/ns-2.31/Makefile.in

Build NS:

baldo@pcsignet08:/locale/ns$ cd ns-allinone-2.31
baldo@pcsignet08:/locale/ns/ns-allinone-2.31$ ./install

The build process will generate a lot of output and will last something between 5 minutes and half an hour, depending on how fast is your hardware.

If the build process has been successful, you will see the following message:

Ns-allinone package has been installed successfully.
Here are the installation places:
tcl8.4.14:      /locale/ns/ns-allinone-2.31/{bin,include,lib}
tk8.4.14:               /locale/ns/ns-allinone-2.31/{bin,include,lib}
otcl:           /locale/ns/ns-allinone-2.31/otcl-1.13
tclcl:          /locale/ns/ns-allinone-2.31/tclcl-1.19
ns:             /locale/ns/ns-allinone-2.31/ns-2.31/ns
nam:    /locale/ns/ns-allinone-2.31/nam-1.13/nam
xgraph: /locale/ns/ns-allinone-2.31/xgraph-12.1
gt-itm:   /locale/ns/ns-allinone-2.31/itm, edriver, sgb2alt, sgb2ns, sgb2comns, sgb2hierns


Please put /locale/ns/ns-allinone-2.31/bin:/locale/ns/ns-allinone-2.31/tcl8.4.14/unix:/locale/ns/ns-allinone-2.31/tk8.4.14/unix
into your PATH environment; so that you'll be able to run itm/tclsh/wish/xgraph.


(1) You MUST put /locale/ns/ns-allinone-2.31/otcl-1.13, /locale/ns/ns-allinone-2.31/lib,
    into your LD_LIBRARY_PATH environment variable.
    If it complains about X libraries, add path to your X libraries
    If you are using csh, you can set it like:
                setenv LD_LIBRARY_PATH 
    If you are using sh, you can set it like:
                export LD_LIBRARY_PATH=

(2) You MUST put /locale/ns/ns-allinone-2.31/tcl8.4.14/library into your TCL_LIBRARY environmental
    variable. Otherwise ns/nam will complain during startup.

After these steps, you can now run the ns validation suite with
cd ns-2.31; ./validate

For trouble shooting, please first read ns problems page
http://www.isi.edu/nsnam/ns/ns-problems.html. Also search the ns mailing list archive
for related posts.

The above mentioned update of the environment variables PATH, LD_LIBRARY_PATH and TCL_LIBRARY is needed for the simulator to work. For the common case of bash users, the preferred way of accomplishing this is to edit the ~/.bashrc file. At this point we anticipate that later on we will need to add also /locale/ns/lib to LD_LIBRARY_PATH in order for the NS simulator to find the nsmiracle and dei80211mr libraries (cygwin users will need to add /locale/ns/bin to their PATH for the same purpose). We suggest to perform all this modifications now so that we need to edit ~/.bashrc only once.

A long story short, all you need to do is to add the following at the end of your ~/.bashrc:

export LD_LIBRARY_PATH=/locale/ns/ns-allinone-2.31/otcl-1.13:/locale/ns/ns-allinone-2.31/lib:/locale/ns/lib:$LD_LIBRARY_PATH
export PATH=/locale/ns/ns-allinone-2.31/bin:/locale/ns/ns-allinone-2.31/tcl8.4.14/unix:/locale/ns/ns-allinone-2.31/tk8.4.14/unix:/locale/ns/bin:$PATH
export TCL_LIBRARY=/locale/ns/ns-allinone-2.31/tcl8.4.14/library

Please note that the paths to be added vary according to the NS version you're installing; in all cases, stick to the path suggested by the message appearing at the end of the ns-allinone build. Furthermore, rember to reload ~/.bashrc on all open console sessions, so that the environment variables are updated:

baldo@pcsignet08:/locale/ns$ source ~/.bashrc

Now, check if the ns executable can be found:

baldo@pcsignet08:/locale/ns$ which ns

Finally, we need to test if NS can successfully run simulations. I personally suggest not to run the validate script suggested at the end of the NS build — it is a quite long process, and we can be satisfied with a much simpler test. Just download the ns-simple.tcl script, save it somewhere (e.g., in /locale/ns/) and run it:

baldo@pcsignet08:/locale/ns$ ns ns-simple.tcl
CBR packet size = 1000
CBR interval = 0.0080000000000000002

If your ns installation was successful, the simulation will run correctly in a few seconds, and at the end the Network Animator (NAM) will pop up in a new window showing you a nice animation of what you simulated. If you're not familiar with ns, this is the good time to have a look at the NS by Example web page to understand NS basics.

If you had problems with your ns-2 installation, check out the ns-2 installation problems, bug fixes, and help page.

Back to Index

3.2 dei80211mr

Unpack the dei80211mr package and cd into the newly created directory:

baldo@pcsignet08:/locale/ns$ tar xzf dei80211mr-1.0.tar.gz
baldo@pcsignet08:/locale/ns$ cd dei80211mr-1.0

The build process follows the well-known ./configure; make; make install paradigm found in the vast majority of open source software. However we need to pass some additional parameters to ./configure:

For the test case we're considering, the build process of dei80211mr will then become the following. First we run configure, and we check the last lines of output:

baldo@pcsignet08:/locale/ns/dei80211mr-1.0$ ./configure --with-ns-allinone=/locale/ns/ns-allinone-2.31 --prefix=/locale/ns
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
checking for g++... g++

<a lot of output snipped here>

checking for ns-allinone installation... ok
checking if ns-allinone installation has been patched for dynamic libraries... yes
checking for tcl2c++... /locale/ns/ns-allinone-2.31/tclcl-1.19/tcl2c++
configure: creating ./config.status
config.status: creating Makefile
config.status: creating src/Makefile
config.status: creating src/adt/Makefile
config.status: creating m4/Makefile
config.status: creating samples/Makefile
config.status: executing depfiles commands

please make sure that the last three checks have been succesful — if not, it's likely you have an error either in your NS installation or in the parameters passed to ./configure. Also remember to adapt all paths to your needs, unless you happen to use the same base path of this tutorial (/locale/ns).

You can now compile and install dei80211mr:

baldo@pcsignet08:/locale/ns/dei80211mr-1.0$ make

<a lot of compilation output here>

baldo@pcsignet08:/locale/ns/dei80211mr-1.0$ make install

<more output here... we report only the following message:>

Libraries have been installed in:

If you ever happen to want to link against installed libraries
in a given directory, LIBDIR, you must either use libtool, and
specify the full pathname of the library, or use the `-LLIBDIR'
flag during linking and do at least one of the following:
   - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
     during execution
   - add LIBDIR to the `LD_RUN_PATH' environment variable
     during linking
   - use the `-Wl,--rpath -Wl,LIBDIR' linker flag
   - have your system administrator add LIBDIR to `/etc/ld.so.conf'

See any operating system documentation about shared libraries for
more information, such as the ld(1) and ld.so(8) manual pages.

The above reported message is just a warning: if you already added /locale/ns/lib to the LD_LIBRARY_PATH environment variable in your ~/.bashrc, as we suggested in section 3.1, then no further action is needed.

The installation of the dei80211mr library is now completed. You can run a sample simulation script to check if everything is OK:

baldo@pcsignet08:/locale/ns/dei80211mr-1.0$ cd samples
baldo@pcsignet08:/locale/ns/dei80211mr-1.0/samples$ ns adhoc_tcp.tcl
num_nodes is set 8
 node 0 is at   X =  4.0954   Y =  1.9806
 node 1 is at   X =  8.6853   Y =  5.6842
 node 2 is at   X =  6.4658   Y =  9.0669
 node 3 is at   X =  1.5670   Y =  0.6503
 node 4 is at   X =  1.0323   Y =  3.3795
 node 5 is at   X =  7.1602   Y =  0.3843
 node 6 is at   X =  6.8063   Y =  8.6544
 node 7 is at   X =  8.3480   Y =  5.7466
printing stats
 TCP throughput node 0 --> node 4 : 1224800.0 bps
 TCP throughput node 1 --> node 5 : 26400.0 bps
 TCP throughput node 2 --> node 6 : 1258400.0 bps
 TCP throughput node 3 --> node 7 : 991200.0 bps 

statsfile: /tmp/stats_4_10_Mode6Mb_10s.pcsignet08.log

Tracefile: /tmp/trace_4_10_Mode6Mb_10s.pcsignet08.tr

If you encounter some problems while building the dei80211mr library, you can refer to the nsmiracle-users mailing list.

Back to Index

3.3 nsmiracle

Unpack the nsmiracle package and cd into the newly created directory:

baldo@pcsignet08:/locale/ns$ tar xzf nsmiracle-1.0.tar.gz
baldo@pcsignet08:/locale/ns$ cd nsmiracle-1.0

As we did for the dei80211mr package, we need to pass some additional parameters to ./configure:

To summarize, the build process is almost identical to that of the dei80211mr package, with the only addition of the --with-dei80211mr switch. The commands to be executed are reported below:

baldo@pcsignet08:/locale/ns/nsmiracle-1.0$ ./configure --with-ns-allinone=/locale/ns/ns-allinone-2.31 --prefix=/locale/ns --disable-static --with-dei80211mr=/locale/ns/dei80211mr-1.0
baldo@pcsignet08:/locale/ns/nsmiracle-1.0$ make
baldo@pcsignet08:/locale/ns/nsmiracle-1.0$ make install

The same suggestions provided for the dei80211mr build process apply here — we summarize them here, somebody might have forgotten them ;-) If everything was OK, you will be able to run the provided sample simulation scripts, e.g.:

baldo@pcsignet08:/locale/ns/nsmiracle-1.0$ cd samples
baldo@pcsignet08:/locale/ns/nsmiracle-1.0/samples$ ns link_with_errors_cbr.tcl
Packet Error Ratio  :   0.050000
Throughput          :   68360.897567
Tracefile     : /tmp/link_with_errors_cbr.tcl.tr
baldo@pcsignet08:/locale/ns/nsmiracle-1.0/samples$ ns dei80211mr_infrastruct_plus_wired_voip.tcl
num_nodes is set 5

Tracefile     : /tmp/voip_wlan_infrastruct_wired.tr
Results file  : /tmp/stats_dei80211mr_infrastruct_plus_wired_voip.tcl_4_6Mbps.pcsensori03.log

Again, if you encounter some problems while building the nsmiracle library, you can refer to the nsmiracle-users mailing list.

Back to Index