UNDERSEA: An Exemplar for Engineering Self-Adaptive Unmanned Underwater Vehicles

Simos Gerasimou, Radu Calinescu, Stepan Shevtsov, Danny Weyns

Recent advances in embedded systems and underwater communications raised the autonomy levels in unmanned underwater vehicles (UUVs) from human-driven and scripted to adaptive and self-managing. UUVs can execute longer and more challenging missions, and include functionality that enables adaptation to unexpected oceanic or vehicle changes. As such, they are excellent for exploring, evaluating and comparing new self-adaptation approaches and techniques.

To facilitate research in this domain, we introduce UNDERSEA, a simulated UUV exemplar that other researchers can use to develop and evaluate new self-adaptation solutions. UNDERSEA comes with predefined UUV missions, adaptation scenarios, and a reference controller implementation, all of which can easily be extended or replaced.

A virtual machine running UNDERSEA is available on Google Drive .

Getting Started

Using UNDERSEA Virtual Machine

UNDERSEA is available preinstalled on an easy-to-use virtual machine. Researchers interested to use the exemplar for developing and evaluating new self-adaptation solutions should:
  1. Install Oracle VM VirtualBox from https://www.virtualbox.org
  2. Obtain a copy of the UNDERSEA virtual machine image, available on Google Drive
  3. Follow this set of instructions to import the virtual machine image into VirtualBox
  4. Start the virtual machine
  5. Once the system loads, you should be presented with the Ubuntu home screen
    If you are not loggeed in automatically (or you logged out due to inactivity), use the password undersea to log in.
  6. The exemplar is located on the home screen under the UNDERSEA directory.

Installing UNDERSEA locally

To install UNDERSEA locally, your machine should have the following: subversion, git, maven, g++ (supporting C++11).
Due to limitation in MOOS-IvP, local installation is known to work only in Linux and OSX platforms. In Windows platforms, reseachers can you the UNDERSEA Virtual Machine. Researchers interested to install UNDERSEA locally should:
  1. Using a terminal download MOOS-IvP by executing the following command:
    svn co https://oceanai.mit.edu/svn/moos-ivp-aro/releases/moos-ivp-15.5 moos-ivp
  2. Navigate to moos-ivp directory and follow the README-GNULINUX or README-OS-X guides for installing MOOS-IvP. For example, to install MOOS-IvP on Linux:
    • Install MOOS-IvP dependencies by executing the command:
      sudo apt-get install g++ subversion xterm cmake libfltk1.3-dev freeglut3-dev libpng12-dev libjpeg-dev libxft-dev libxinerama-dev libtiff5-dev
    • Navigate to moos-ivp directory and build MOOS-IvP by executing the commands:
      ./build-moos.sh ./build-ivp.sh
    • Make the system path aware of the MOOS-IvP executables, e.g., by modifying ~/.bashrc
      export PATH=moos-ivp-full-path/bin/:$PATH export PATH=moos-ivp-full-path/ivp/bin/:$PATH
      If the PATH variable has been configured correctly, then running pAntler on a terminal will give some information about MOOS-IvP.
  3. Get the latest UNDERSEA source code by cloning the UNDERSEA GitHub repository:
    git clone https://github.com/gerasimou/UNDERSEA.git
  4. Navigate into UNDERSEA/moos-ivp-UNDERSEA and build UNDERSEA components by executing the command:
    Note: If an exception is raised due the
  5. Make the system path aware of the (MOOS-IvP-based) UNDERSEA executables, e.g., by modifying ~/.bashrc
    export PATH=moos-ivp-UNDERSEA-full-path/bin/:$PATH
If everyting compiled correctly, (MOOS-IvP-based) UNDERSEA executables should be available in system path.
We explain below how researchers can use UNDERSEA to develop new self-adaptation solutions.

Step-by-Step Guide

Workflow of evaluating self-adaptive solutions with UNDERSEA.
Engineering, evaluating and comparing new self-adaptation solutions with UNDERSEA is a five-step process.

Step 1
Download and start the virtual machine that includes the UNDERSEA exemplar as described in the Getting Started section.

Step 2
Implement a new controller by specialising the abstract Java classes of the UUV controller.
1) Start Eclipse by double clicking the Eclipse icon on home screen and navigate to the UUV_Controller project
2) Create a new package giving a representative name (e.g., controllerPMC for a probabilistic model checking approach) and inside this package create new solution-specific MAPE element classes (e.g., MonitorPMC, AnalyserPMC, PlannerPMC and ExecutorPMC) that extend the relevan abstract MAPE classes (i.e., Monitor, Analyser, Planner and Executor).
3) Once you have finished implementing the new controller, navigate to MainController class and instantiate the specialised classes of the controller (see the given examples in MainController).
4) Using a terminal, navigate to the UNDERSEA directory and execute the build-controller.sh script using the command: ./build-controller.sh If there are no compilation errors, UUV_Controller.jar will be available in the build directory.

Step 3
Define a new UUV mission.
1) Create a new mission file that has the structure below. Alternatively, you can copy the default mission.config and make changes to the file.
2) Using a terminal, navigate to the UNDERSEA directory, and execute the build-mission.sh script giving as command line argument the mission file name, i.e., ./build-mission.sh missions/mission.config
Fragment of a mission file specified in the UNDERSEA DSL.
simulation time: how long the simulation will be
time window: delay between successive controller executions
host: communication host between shoreside and UUV
port: communication port between shoreside and UUV (global), and between controlled UUV and controller (UUV block)
name: unique UUV or sensor name (used for assembling the current system state and the new system configuration)
speed:: UUV speed in the form ''MinSpeed : MaxSpeed : Point''
rate: sensor rate
reliability: probability that a reading will be accurate
change event that affects sensor service in the form ''StartTime : EndTime : NewRate''

Step 4
Start the experiment by running the launch.sh script, i.e.,
The UUV simulator console is automatically displayed, presenting mission-related information.
Self-adaptive UUV simulator.

The terminal also presents additional information in the form:
ID Time Action Details
1) 20.171 Requested UUV state
2) 20.171 Received SENSOR1:3.05:30:26:0,SENSOR2:4.07:40:36:-1,SENSOR3:3.05:30:13:0
3) 20.172 New config: SPEED=3.9672905530417966,SENSOR1=0,SENSOR3=1,SENSOR2=0
4) 20.172 Applied? OK

1) The time when the controller invokes the controlled UUV system to extract its current state
2) The time when the controller receives a reply from the controlled system
     The details in Received actions denote for each on-board sensor name:rate:#readings:#accurate readings
3) The new configuration selected by the controller, given in the form SPEED=value,SENSOR_NAME=0/1,...(where 0->off, 1->on)
4) The controlled system acknowledges the receipt of the new configuration.

** In case a problem with the simulation occurs, please execute the clean.sh script with command line argument "-k",i.e., ./clean.sh -kand then run again the launch.sh script.

** While the mission is running, you can execute the memoryMonitor.sh script to analyse the memory consumption of the controller using jvisualvm.

Step 5
When the experiment finishes, a log file with mission-related data (with name log_DATE.csv) and a text file (with name CPU_DATE.txt) with CPU-related data are generated inside the build/log directory.

The analysis of the collected data can provide useful insights regarding the CPU and memory overheads of the controller, and its ability to respond adequately to changes affecting the UUV system.