Welcome! This is Jemula802++

Setup the tools

Jemula can be built and run ether through the Eclipse IDE or using Apache Ant in the command line. In both cases the following is required:

• Java JDK
• Google Earth for the visualization.

Eclipse

• Install Eclipse if not already installed.
• Start Eclipse.
• Right click in the Package Explorer and select Import...
• Add the two cloned projects (Jemula and Jemula802).

Create a run configuration in Eclipse

In order to run code in Eclipse you have to create a run configuration following these steps:

• Select Run Configurations... from the green play-button menu.
• Choose Java Application on the left and create a new entry using the top new-entry-icon.
• Name the new run configuration and use Jemula802 as project and JE802Starter as main class.
• The application takes on argument, the path to the scenario file you want to simulate:
• Go to the arguments tab of the run configuration.
• Add the path to the scenario file to the Programm arguments box. (e.g. scenarios/examples/4stations.xml)
• Use the Apply button to save the configuration and then the Run button to run the application for the first time.
• See the Console tab in the bottom for any errors.

Terminal

Instead of Eclipse, Jemula802++ and Jemula++ can be handled through a terminal.

Clone Jemula and Jemula802:

#!java
git clone git@bitbucket.org:lfield/jemula.git
git clone git@bitbucket.org:lfield/jemula802.git

Compile Jemula and Jemula802:

#!java
./jemula802/resources/compile_Jemula_and_Jemula802.sh

Run a scenario XML file (e.g. ./jemula802/scenarios/examples/4stations.xml):

Note that the Mobile Computing Class, during which this tool is used, another set of files is recommended as start:

#!java
./jemula802/resources/run_jemula802.sh <path to XML scenario file>

Apache Ant

• Install Apache Ant if not already installed.

The Ant build also builds Jemula++ which Jemula802++ depends on. To do so, the Ant build file assumes a folder structure where the Jemula++ and Jemula802++ project directories are located in the same directory, i.e.:

<some_path>/Jemula
<some_path>/Jemula802

An alternative path to the Jemula project can be provided as an argument in the following way:

ant -Djemula=<path_to_Jemula>

ant -Dscenario=<path_to_scenario> 

The following Ant targets are available:

• clean: Deletes bin/ and dist/ directories
• compile_Jemula802: Compile the Jemula802++ source
• jar_Jemula802: Create the distribution jar
• run: Run the simulation
• test: Run the unit tests

How to use the GUI

If the GUI is enabled in the scenario file (showGui attribute in the JE802Control tag) a Java frame will pop up and show the ongoing simulation. You can use the mouse and the following keys to navigate:

• Use the mouse wheel to scroll left and right or < and Y.
• Use left click to zoom in and right click to zoom out or I/+ and O/-.
• F switches through different visualization of the packets.
• B toggles backoff visualization.
• N toggles NAV visualization.
• C switches through all available channels.

Additional information is shown in the packets if zoomed to a certain level.

Simulation results and visualization

Result files

The simulation will create a folder where it stores all the result files. The folder can be specified in the scenario file (Path2Results attribute in the JE802Control/JE802StatEval tag). The following result files are generated:

• overall throughput, offer and delay (total_.m & total_.csv)
• throughput, offer and delay per access category (_ACx.m & _ACx.csv)
• throughput, offer and delay per link and access category
• power consumption (overall and per station)
• retransmission rates (only for TCP traffic)

The *.m file are formatted as a matrix an can directly be read into Matlab. They also contain a key for the different columns.

The *.csv files contain a header line with the column names and are formatted using comma (,) as delimiter.

The delay output files (for both .m and .csv) contain a space-separated histogram in the last field in each line.

n.b. Overalls and averages are always accumulated.

Google Earth visualization

The simulation also generates a Google Earth file (*.kml) for visualization of the results. If enabled in the scenario file (generateGEarth attribute in the JE802Control/JE802Animation tag), it can also be found in the result folder after the simulation has completed. The different parts of the visualization can be enabled using the check-boxes on the left. Hit the play button in the top left corner of the map. If it plays to fast, you can adjust the speed in the settings of the play bar.