5.4) Running Sample Applications

Overview

For the convenience of AERPAW Experimenters, we made available several sample applications for all the processes running in the Experimenter-VM (E-VM). For any experiment the start of an experiment will always be initiated by starting a single script name /root/startexperiment.sh in each of the E-VMs involved in the experiment. Starting the startexperiment.sh is done by the Experimenter when the experiment is in Development mode and by the Operator when the experiment is in Testbed mode. startexperiment.sh is the only script that is started on the E-VM, and, hence, it needs to call all the code that the Experimenter wishes to run when the experiment is started. No other Experimenter code is being called during an experiment.

By default, when the experiment is first instantiated in Development mode, the startexperiment.sh contains three commented lines that call three other scripts, namely ./Radio/startRadio.sh, ./Traffic/startTraffic.sh, and ./Vehicle/startVehicle.sh. These scripts do not exist initially and it is the responsibility of the Experimenter to uncomment these lines and create these three scripts according to what the Experimenter wishes to do in the experiment.

First, not all three scripts (startRadio.sh, startTraffic.sh, and startVehicle.sh) are needed for all experiments. For example, for a fixed node, there is no purpose for vehicle control software. In this case it makes sense to leave the vehicle script commented (the # is used for comments in bash scripts), or by deleting the line. Any text editor can be used for this: by default AERPAW provides vim, emacs, pico, and nano. Furthermore, not all experiments need a traffic script. For example, the channel sounder generates the signal in the GNU Radio transmitter code and has no corresponding traffic generation or termination. In this case, (i.e., if the Experimenter uses a radio software that requires no traffic generation or termination) the ./Traffic/startTraffic.sh should be left commented out (or deleted). This is also the case for cellSearch, which also does not use a traffic process.

AERPAW provides two different methods of setting up the sample experiments: an automatic method and a manual method. Both methods accomplish the same goal: they setup radio, traffic, and vehicle scripts that are called from within the start_experiment.sh script, but they achieve this goal in different ways.

Automatically Setting up the Radio, Traffic, and Vehicle Scripts

AERPAW provides a utility for facilitating setting up the radio, traffic, and vehicle scripts in each of the E-VMs. This utility only sets up a set of scripts in one of the E-VMs, and as such it will have to be run in each of the E-VMs for a complete experiment. The utility experiment setup utility is initiated by calling experiment_setup from the root directory of the E-VM that an Experimenter wants to set up.

The experimenter then chooses the type of script to setup. For example, by choosing 1, the radio setup menu is made available.

Upon selecting a radio script, additional questions may be asked if appropriate (for example, for selecting a cellular radio, the next question is on selecting whether the node will be a base station (eNB) or user equipment (UE).

A similar process is then used for setting up the traffic as well as the vehicle scripts.

Manually Setting up the Radio Script

The radio script (./startRadio.sh) should be placed at /root/Profiles/ProfileScripts/Radio/startRadio.sh. We advise the Experimenter to simply copy one of the existing starting scripts in /root/Profiles/ProfileScripts/Radio/Samples. The choice of the script corresponds to the intended use for that particular node. For example, in an experiment involving an UAV with a portable node that should run an srsUE script the Experimenter would copy the startSRSRAN-SISO-UE.sh script to startRadio.sh in the portable node E-VM as such:

$ cd /root/Profiles/ProfileScripts/Radio

$ cp Samples/startSRSRAN-SISO-UE.sh startRadio.sh

The Experimenter then can edit the startRadio.sh to change it as the Experimenter sees fit. Alternatively, the Experimenter can create a link (ln -s startSRSRAN-SISO-UE.sh startRadio.sh), but copying is encouraged as it preserves the original version of the script that may prove useful to the Experimenter in case of mishaps while editing the startRadio.sh script.

If an UE is selected at the portable node, a base station should be chosen at the other node (as UEs cannot transmit or receive to each other directly). So in the fixed node E-VM:

$ cd /root/Profiles/ProfileScripts/Radio

$ cp Samples/startSRSRAN-SISO-EPCandENB.sh startRadio.sh

Most of the profiles should be chosen in pairs (UE on one side, BS, on the other, or RX on one side, TX on the other). The testbed is flexible enough to allow the users to choose any combinations of scripts that work with each other, for example, an Experimenter may wish to setup a BS at a flying UAV and an UE at a fixed node, or at another UAV.

Manually Setting up the Traffic Script

Setting up the traffic script is similar to the setup for the radio script. The traffic script should be placed at /root/Profiles/ProfileScripts/Traffic/startTraffic.sh. At this time we provide three traffic scripts: one that starts a ping to another destination, as well as a pair of scripts which runs iperf (one as a client and one as a server). For example, if ping is the desired source of traffic, setting up the traffic script:

$ cd /root/Profiles/ProfileScripts/Traffic

$ cp Samples/startPing.sh startTraffic.sh

This establishes a ping initiated at this node. If a second ping is desired from the other node to this one, it can be enabled on the other E-VM using the same procedure as above. The procedure to initiate the ping and change the destination node IP is given on this page.

Setting up the iperf scripts is similar, with the caveat that iperf scripts should be setup in pairs, with a client paired with a corresponding server. The iperf traffic can be initiated with the help of intructions given on the page.

Manually Setting up the Vehicle Script

At this time we only provide the preplanned trajectory script, which directs the UAV or UGV controlled by this portable node along a trajectory defined by a .plan file. Details on creating and editing .plan files are available at this page. The copying process is similar to the other two start scripts:

$ cd /root/Profiles/ProfileScripts/Vehicle

$ cp Samples/startPreplannedTrajectory.sh startVehicle.sh

If a different .plan file (other than the one provided by default, which is a short trip to the middle of our field and back) is desired, please edit the startVehicle.sh script and change the environmental variable $MISSION to the path of your new .plan file.

Debugging Tips

In the current default setup in AERPAW, the vehicle scripts and the radio and traffic generation scripts are relatively independent of each other. The Experimenters may find it easier to setup each set of scripts independently: the vehicle can be tested in the absence of the radio and traffic scripts (which can be commented out at all E-VMs). Likewise, the traffic and radio scripts can be tested independently of the vehicle script by commenting out the startVehicle.sh script.

The script setup suggested above is only a suggestion. The Experimenter has full access to the E-VM container and can organize the experiment software as desired. The only requirement from the AERPAW Operators is that the experiment should be started by running the script /root/startexperiment.sh .

Stopping Experiments

In addition to providing the starting script /root/startexperiment.sh, the AERPAW Operators also provide a script for stopping an experiment. This script is at /root/stopexperiment.sh. When invoked, the stopexperiment.sh script will enumerate all existing screen sessions and exit them.

Page updated

Report abuse