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_metrics contains the a node used for collecting mission metrics
• 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
• 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.

Build Docker images locally

To build the docker images locally, run:

./build_docker_images.sh

Install SUAVE locally

To install the exemplar locally, you have to install Gazebo Harmonic, install ROS2 Humble, install ArduSub, install the ArduSub plugin, and finally install the SUAVE workspace.

Install Gazebo Harmonic

Follow the official instructions for installing Gazebo Harmonic.

Install ROS2 Humble

Follow the official instructions for installing ROS2 Humble.

Install ROS_GZ

```Bash apt install ros-humble-ros-gzharmonic

File truncated at 100 lines see the full file