User Code

Introduction

Experiments that have requirements exceeding the capabilities of the script interface utilize the programmatic interface. The control code running on the Emulation Controller is written in Java. Users may write Java classes that are executed by the emulator controller, giving them full access to all the emulator functionality. Using the programmatic interface, experiments with arbitrarily complex behavior can be created.

Configuration

Users may specify one or more user defined classes to be loaded at boot time. Each of these classes must implement the EmulatorUserClass as discussed below. This is usually done by extending SimpleUserClass.

Each class must contain the name of the class, a list of arguments that will be passed to the class, and a url where the user code is located.

Example:

    <UserClassDef>
        <class>
            <name>emuExample.ManualChannels</name>
            <args>nodew1 nodew2 -95.0 -60.0 1.0</args>
            <url>http://localhost/</url>
        </class>
    </UserClassDef>		

EmulatorUserClass

All user code loaded at boot time must implement the EmulatorUserClass interface. This interface defines a single method - start() - which accepts a reference to the Emulator object and a list of arguments that were passed in fromt he configuration file.

Typically, however, users do not directly implement EmulatorUserClass, but inherit from SimpleUserClass.

SimpleUserClass

SimpleUserClass is an abstract class that provides convient functionality for user code. Users extend this class by defining a start() method that accepts a list of arguments from the configuration file. SimpleUserClass then provides members for commonly needed Emulator objects such as the EmuWorld, SignalEnvironment, the DaemonCommunicator, the EmuNodes.

Internally, SimpleUserClass contains a start() method called by the emulator. This method populates the aforementioned objects, and calls the user-defined start() method.

Writing User Classes

User classes have access to internal emulator data structures. These are detailed in the API documentation. A high-level overview is provided in the software documentation. The examples directory provides a few examples illustrating typical use.

Restrictions on path Model

Currently, users are not allowed to change pathloss parameters during the experiment, as the fading table is pre-computed based on the initial parameters. Efforts are being made to make it possible to provide more realistic channel models.