However, for the look I wanted, I wanted to maximize the screen space for the console application to show as much text as possible and worked off the hello world example on the SDK webpage. Essentially, the simple “library” (note: library is used very loosely here) initializes the display, shows the keyboard and supports some simple output using putch and puts functions that I implemented. It can also show a blinking cursor and user input at a prompt. In case someone else can use the code I have made it available. Check back soon to see the source for the telnet portion of the app I made as well or look for it on the App World.

Simple Telnet – Example Application using the conosole library

In order to use the library, you need to make use of the bbutil.c and bbutil.h files that are included in many of the examples provided by RIM. I have provided them here alongside my own code so that it is easier to follow along. I also provide two more files: glconsole.c and glconsole.h. You just need to #include “glconsole.h” in your source in order to use the library. All of the functions available to you are listed in the “glconsole.h” file as well. I will go over the important ones in this article.

First is gl_init(). This function initializes the library, the screen, font etc. This function should be called before using anything else in the library. Similarly, gl_cleanup() is used to free memory and should be called before your app is terminated.

After initialization, you may now use the puts and putch functions to display characters to the screen. gl_putch(char c) takes a single character and displays it onto the screen. It can handle newlines which are represented as ‘\n’ and tabs which are represented as ‘\t’. Backspaces by user input is handled as a ‘\b’ character. This is similar to how people on The osdev.rg website often handle character output in their custom operating systems. I’m not sure how it relates with normal c standards, but I imagine it is similar. Eventually I hope to implement a printf() type of function, but at the moment the putch() and puts() functions serve what I am doing well enough. Note: puts() is the same as putch() but instead takes a (char *) ie) a string. The string should also be null-terminated, or it will just continue until it hits a null character. The characters are automatically scrolled when the bottom of the screen is reached.

The only other really important function is gl_render(). This function is what should be called everytime the screen needs to be refreshed. This is usually in a for loop within your main() function in your app.

It is also possible to resize the screen using the gl_resize() function. By default the screen starts at 80X29 which is the maximum size with no virtualkeyboard showing, at the font size I selected. When the keyboard shows up, it fits 80×14. In some sample code I’ll also show how keyboard input can be handled, how to blink the cursor and how to detect when the keyboard is shown or hidden.

For the rest of this guide, I’ll assume you are using the QNX Momentix IDE available from RIM’s developer website. To start, create a new project by going to File->New Blackberry Tablet OS C/C++ Project. Name it whatever you like, click next. Then choose the C language, and empty Application Project. You can now drag the gl_console.c, glconsole.h, bbutil.c and bbutil.h files into the src folder within the IDE to include them. You will probably want to copy the files and not link them when it asks. Before compiling, there are several libaries which must be linked to the project. You can do this by right clicking your project, going to properties. Then go to C/C++ General->Paths and Symbols->Libraries. Here you can add libraries. Each time you add one, be sure to check “add to all Configurations” so that you don’t need to do this again if you change from a device-debug to device-release build. The following libraries should be included:

• bps
• EGL
• GLESv1_CM
• freetype
• png

Now that all this is setup, it is possible to start you main() function and use the library. If you like you can right click on your src folder and click “new file” and create a main.c file or whatever you like to name it. While this isn’t the typical way you would include a library into a project, this way lets you edit the library source to your liking in case you want to further extend it.

The following example shows a skeleton of what is required to get the code to display some text:

#include <stdlib.h>               /* EXIT_FAILURE */
#include <stddef.h>              /* NULL */
#include <bps/bps.h>           /* BPS_SUCCESS */
#include <bps/screen.h>      /* screen_event_get_event() */
#include <bps/navigator.h>  /* NAVIGATOR_EXIT */
#include "glconsole.h"

void handleScreenEvent(bps_event_t *event);

int main(int argc, char * argv[])
{
  int exit_application = 0;

  if(EXIT_SUCCESS != gl_init())
  {
    fprintf(stderr, "error init\n");
    return 0;
  }

  gl_puts("Hello gl console world!\n");

  for(;;)
  {
    bps_event_t *event = NULL;
    if (bps_get_event(&event, 0) != BPS_SUCCESS)
      return EXIT_FAILURE;

    if (event)
    {
      int domain = bps_event_get_domain(event);

      if (domain == screen_get_domain())
        handleScreenEvent(event);
      else if ((domain == navigator_get_domain()) && (NAVIGATOR_EXIT == bps_event_get_code(event)))
        exit_application = 1;

      if (exit_application)
        break;
    }
    gl_render();
  }

  gl_cleanup();
  return 0;
}

void handleScreenEvent(bps_event_t *event)
{
  /* do normal event handling here, see other bb examples */
}

The key parts are calling gl_init() which initializes the library. Then within the main loop, the gl_render() function should be called which will actually render the text. Finally gl_cleanup() should be called before termination to properly free memory.

In the near future I plan to add some support to handle ansi encoded text (specifically for my telnet application) so that it can display colours and move the cursor around the screen using this standard.

Here are the files:
glconsole.h
glconsole.c

So back to the point of this article, a guide on how to install ns-3.2 on Ubuntu 8.04 Hardy Heron. Ns-3 installation is quite simple since an automatic build tool named waf is used to build the project. Enter the following in the terminal to download, untar and build ns-3.2.

wget http://www.nsnam.org/releases/ns-3.2.tar.bz2
tar -xvf ns-3.2.tar.bz2
./waf -d debug configure

How to start working with NS-3

So from here on out, all you have to do is use the waf tool for compiling and running your ns3 simulations. There are many example scenarios located in the /examples folder. You can run a simulation with any of the scenarios using the waf command. For example if you wanted to run a scenario file named first.cc you would enter the following command:

./waf --run=first

How to display exactly what is going on to the screen (Logging)

Sometimes when making changes and implementing something new, it is helpful to show everything that is happening on the screen. You can achieve this by entering the following at the linux command line:

export 'NS_LOG=*=level_all|prefix_func|prefix_time'

export 'NS_LOG=NqapWifiMac=level_all|prefix_func|prefix_time'

If you have turned on logging, you have likely noticed that ns3 generates so much information that it scrolls by way to fast to be of any use. So you will probably want to output the results to a file. For example if you were running the first.cc file again and you have turned on logging you could do this:

./waf --run=first >& first.txt

Useful Functions

So far I have found these functions make debugging scenarios easier:

static Vector
GetPosition (Ptr<Node> node)
{
  Ptr<MobilityModel> mobility = node->GetObject<MobilityModel> ();
  return mobility->GetPosition ();
}

static Ipv4Address
GetAddress (Ptr<Node> node, uint32_t interface)
{
  Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
  return ipv4->GetAddress(interface);
}

Tips

The following are a few important things I’ve discovered that may save you time when trying to work with ns3 on certain tasks:

• When simulating an ad-hoc or wireless mesh network using OLSR, make sure you set your mobility model before you install the OLSR routing on the nodes. If you do not do this, OLSR may generate link pairs for links which are actually too far away to communicate because before the mobility model is installed on the nodes they are all close enough to communicate.
  
• Also with OLSR, make sure you give OLSR enough time to determine the network topology before you allow the applications to start running on the network. I have read that about 100s of waiting time before starting is enough, however I imagine as the network size grows this may also grow (I have tested with a size of 4×4 and this is enough time – I will adjust this as I play with the numbers as well)

Useful Links

• NS3 Doxygen Documentation
• NS3 Tutorial
• NS3 Manual
• NS3 Wiki

I have found many people already who have had difficulty setting it up so maybe this will be of some help to someone. For this tutorial I am assuming you have installed the most recent version of Ubuntu (8.04). (At the time of writing)

Step 1: Update Ubuntu

Since it has already been a month or so since Hardy Heron has been released its probably best, if you haven’t already done so to update Ubuntu. The easiest way I’ve found is to go to System>>Administration>>Update Manager. Alternatively, you can enter this into the terminal:

sudo apt-get update
sudo apt-get upgrade

Step 2: Download all of the required pieces to make ns2 work

Here is a list of archives required for ns2 to work properly (you can download them by clicking the links or just enter all of the commands in the code sections below for automatic download and untar). I saved each archive to the desktop so I could find each one easily but you could use anywhere you like.

1. tcl 8.4.14
2. tk 8.4.14
3. otcl 1.13
4. tclcl 1.19
5. ns 2.33
6. nam 1.13

Step 2.5: Install Ubuntu Packages

Before installing everything else, I have found that it is helpful to get a few packages from the ubuntu repositories or else it wont build correctly. Grab a cup of coffee it might take a while since kdebase-dev is somewhat large. I’m sure there is a way to do this with fewer packages however I know this works. If anyone figures out exactly which packages are required let me know so I can update this.

Step 3: Install tcl

wget http://www.jasonernst.com/wp-content/uploads/2008/06/tcl8.4.19-src.tar.gz
tar xvf tcl8.4.19-src.tar.gz
cd tcl8.4.19/unix
./configure
make
sudo make install

Step 4: Install tk

cd ..
cd ..
wget http://www.jasonernst.com/wp-content/uploads/2008/06/tk8.4.19-src.tar.gz
tar xvf tk8.4.19-src.tar.gz
cd tk8.4.19/unix
./configure
make
sudo make install

Step 5: Install oTcl

Important Note: The ‘./configure –with-tcl=’ portion of the following two code fragments should point to the source files for tcl. If you have been following the guide by copying and pasting the previous commands what we have here will work just fine. Otherwise you will need to change this to point to the correct location of your tcl source files.

cd ..
cd ..
wget http://www.jasonernst.com/wp-content/uploads/2008/06/otcl-src-1.13.tar.gz
tar xvf otcl-src-1.13.tar.gz
cd otcl-1.13
./configure --with-tcl=../tcl*/
make
sudo make install

Step 6: Install tclcl

cd ..
wget http://www.jasonernst.com/wp-content/uploads/2008/06/tclcl-src-1.19.tar.gz
tar xvf tclcl-src-1.19.tar.gz
cd tclcl-1.19
./configure --with-tcl=../tcl*/
make
sudo make install

Step 7: Install ns2

cd ..
wget http://www.jasonernst.com/wp-content/uploads/2008/06/ns-2.33.tar.gz
tar xvf ns-2.33.tar.gz
cd ns-2.33
./configure
make
sudo make install

You will likely get alot of warnings for deprecated conversions. Just ignore these or if you really are concerned about them visit the nsnam troubleshooting page. If you want to make sure your version of ns-2 is working correctly after the install you can run the validation test from within the ns2 source directory. You can do this by entering:

You should see that the test output agrees with the reference output. Congratulations you have a working version of ns-2 installed.

Step 8: (optional) Install nam

cd ..
wget http://www.jasonernst.com/wp-content/uploads/2008/06/nam-src-1.13.tar.gz
tar xvf nam-src-1.13.tar.gz
cd nam-1.13
./configure
make
sudo make install

Note: if you get this error:

it may be necesary to do this:

You are now ready to start working with ns2 and nam. If you are like me and working on a new protocol or something you will want to start modifying the ns-2 source code and recompile again so you might want to keep that folder handy. The rest of the source can be safely removed as far as i know. Keep in mind after you have modified the source you will want to do another make install so that when you type ns in your terminal the version you just compiled is used.

Getting Started with NS2

These are some quick tips to get you started using ns2 if you are a beginner.

All example files are located in ns/tcl/ex. You can run these scenarios on ns2 using ns filename.tcl The best way to start is probably changing things in these files until you understand what is happening more thoroughly.

The output will usually be a trace file with a similar name: ex) filename.tr. Trace files can usually be viewed with a text-editor program. There are also tools to analyze the trace files and pull stats from them. These may require some tweaking however depending on the format of the trace file. Additionally, a nam output file for visualization may be generated as well. This will usually be named filename.nam. To view the visualization use: nam filename.nam

Useful Links

I thought it might be useful to add a section on useful links here since this article has become quite popular. If you would like to suggest a link feel free to contact me.

• Ns2 Wiki
• Marc Greis’ Tutorial
• NS Manual
• NS for Beginners (pdf)
• Common NS2 Installation Problems
• NS2 Wireless and Mobility Modules
• NS2 Mailing Lists
• NS2.33 Wireless MAC and PHY improvements