SUAVE: An Exemplar for Self-Adaptive Underwater Vehicles

This repository contains SUAVE (Self-adaptive Underwater Autonomous Vehicle Exemplar). SUAVE focuses on the scenario of pipeline inspection for a single autonomous underwater vehicle (AUV). The AUV’s mission is to first search for a pipeline on the seabed, then follow and inspect the pipeline.

It clearly separates the system into two subsystems: the managed subsystem and the managing subsystem. The managed subsystem implements the functionalities required by the AUV to perform the pipeline inspection mission, and the managing subsystem implements the adaptation logic. This ensures that this exemplar can be reused with several different managing subsystems, providing that they satisfy the necessary requirements. The usability of the exemplar is showcased with MROS2, the implementation of the self-adaptation framework Metacontrol.

This repository is organized as following:

• The package suave contains the managed subsystem functionalities
• The package suave_monitor contains the monitor nodes
• The package suave_missions contains the AUV’s missions
• The package suave_base provides a reusable base launch (managed system + metrics) for external managing systems
• The package suave_bringup composes missions with the built-in managing subsystems
• The package suave_metrics contains a node used for collecting mission metrics
• The package suave_requirements contains a node that monitors the runtime fulfillment of the SUAVE RELAX requirements
• The package suave_metacontrol contains the metacontrol implementation of the managing subsystem
• The package suave_random contains the implementation of a random managing subsystems
• The package suave_bt contains the behavior tree implementation of the managing subsystem
• The package suave_msgs contains suave’s specific ros msgs
• The folder docker contains the dockerfiles and scripts used to package this repository
• The folder runner contains the bash scripts to run the exemplar

A video of the SUAVE running (click in the image to open the video):

An overview of the system:

The exemplar can either be used with Docker or installed locally. The exemplar can be executed following this instructions.

A paper describing this exemplar was presented at SEAMS 2023 artifact track, you can find it here. And an open access pre-print can be found here.

Navigate the README

• Use SUAVE with Docker
  • Use the headless image
• Install SUAVE locally
• Run SUAVE
• Extending SUAVE and connecting managing subsystems
• Related repository
• Citation
• Acknowledgments

Use SUAVE with Docker

You can pull and run the exemplar as a Docker container using the following command. Keep in mind you need to have Docker installed on your computer and running.

In a terminal on your computer run:

docker run -it --shm-size=512m -p 6901:6901 -e VNC_PW=password --security-opt seccomp=unconfined ghcr.io/kas-lab/suave:main

Optionally you can add the parameter -v <absolute_path_host_compute>:/home/kasm-user/suave/results to save the results into your computer, replace <absolute_path_host_compute> with the absolute path of where you want the data to be saved in your computer, e.g:

docker run -it --shm-size=512m -v $HOME/suave_results:/home/kasm-user/suave/results -p 6901:6901 -e VNC_PW=password --security-opt seccomp=unconfined ghcr.io/kas-lab/suave:main

SEAMS2023: To use the docker image used in the SEAMS2023 paper, replace ghcr.io/kas-lab/suave:main with ghcr.io/kas-lab/suave:seams2023.

Once the container is up and running, you can interface with it through your web browser. The container will be hosted locally at the port specified, in this case 6901. So in your browser, go to http://localhost:6901.

A dialog will request a username and password, these are shown below, with the password being specifiable in the run command.

• User : kasm_user
• Password: password

Now you can proceed to run the exemplar.

Use the headless image

The headless image (ghcr.io/kas-lab/suave-headless:main) is designed for automated experiment campaigns on servers or CI machines where no display is available. It uses a virtual framebuffer (Xvfb) so Gazebo can still run off-screen.

Pull and run an experiment campaign:

docker run -it --shm-size=512m \
  ghcr.io/kas-lab/suave-headless:main \
  ./src/suave/runner/headless_runner.sh false metacontrol time 2

The runner arguments are the same as runner.sh:

1. true or false — whether to show a GUI (use false for headless)
2. metacontrol, random, none, or bt — adaptation manager
3. time or distance — mission type
4. Number of runs (integer)

File truncated at 100 lines see the full file