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_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)

To save results to your host machine, mount a volume to /home/ubuntu-user/suave/results:

docker run -it --shm-size=512m \
  -v $HOME/suave_results:/home/ubuntu-user/suave/results \
  ghcr.io/kas-lab/suave-headless:main \
  ./src/suave/runner/headless_runner.sh false metacontrol time 2

NVIDIA GPU support: If your machine has an NVIDIA GPU, install the NVIDIA Container Toolkit and use:

docker run -it --rm --gpus all --runtime=nvidia --shm-size=512m \
  -e NVIDIA_VISIBLE_DEVICES=all -e NVIDIA_DRIVER_CAPABILITIES=all \
  -v $HOME/suave_results:/home/ubuntu-user/suave/results \
  ghcr.io/kas-lab/suave-headless:main \
  ./src/suave/runner/headless_runner.sh false metacontrol time 2

Build Docker images locally

To build the docker images locally, run:

./build_docker_images.sh

The script builds the browser image as suave:dev and the headless runner image as suave-headless:dev from the local checkout.

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

apt install ros-humble-ros-gzharmonic

Install ArduSub

ArduSub is a subproject within ArduPilot for piloting underwater vehicles.

Disclaimer: Problems may occur with different combinations of ArduPilot and MavROS versions. This repo was tested with ArduSub commit 571e8c7 (ArduSub 4.7.0-beta4) and mavros 2.14.0.

cd ~/
git clone https://github.com/ArduPilot/ardupilot.git
cd ardupilot
git checkout 571e8c7bd3793fce1bc5184a2f6586feb8a616e5
git submodule update --init --recursive
Tools/environment_install/install-prereqs-ubuntu.sh -y
. ~/.profile

To test if the installation worked, run:

sim_vehicle.py -v ArduSub -L RATBeach --console --map

ArduPilot SITL should open and a console plus a map should appear.

Install the ArduSub plugin

Install the dependencies:

sudo apt update
sudo apt install libgz-sim8-dev rapidjson-dev
sudo apt install libopencv-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-bad gstreamer1.0-libav gstreamer1.0-gl

export GZ_VERSION=harmonic
sudo bash -c 'wget https://raw.githubusercontent.com/osrf/osrf-rosdep/master/gz/00-gazebo.list -O /etc/ros/rosdep/sources.list.d/00-gazebo.list'
rosdep update
rosdep resolve gz-harmonic
# Navigate to your ROS workspace before the next command.
rosdep install --from-paths src --ignore-src -y

Clone and build the repository:

cd ~/
git clone https://github.com/ArduPilot/ardupilot_gazebo
cd ardupilot_gazebo
git checkout 082a0fe231f6e63bc8d1598f1cba461d9e2ea7f5
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
make -j4

Add the required paths:

Assuming that you have cloned the repository in $HOME/ardupilot_gazebo, run:

echo 'export GZ_SIM_SYSTEM_PLUGIN_PATH=$HOME/ardupilot_gazebo/build:${GZ_SIM_SYSTEM_PLUGIN_PATH}' >> ~/.bashrc
echo 'export GZ_SIM_RESOURCE_PATH=$HOME/ardupilot_gazebo/models:$HOME/ardupilot_gazebo/worlds:${GZ_SIM_RESOURCE_PATH}' >> ~/.bashrc

Now that new environmental variables have been added to your terminal, you need to reload it with

source ~/.bashrc

More info about the plugin can be found in the corresponding repository.

Install the SUAVE workspace

Create the workspace and download the required repositories:

mkdir -p ~/suave_ws/src/
cd ~/suave_ws/

If you want to get the most updated version of the repo:

wget https://raw.githubusercontent.com/kas-lab/suave/main/suave.repos
vcs import src < suave.repos --recursive

For a reproducible release installation, download suave.repos from the matching Git tag instead of main.

SEAMS 2023 artifact: The exact source submitted with the published paper is preserved at commit 9e64688. Because that artifact uses a historical dependency set, the recommended way to reproduce it is the archived ghcr.io/kas-lab/suave:seams2023 container image. Use the main or release-tag instructions above for current development.

Before building the ros_gz package (one of the dependencies), you need to export the gazebo version:

export GZ_VERSION="harmonic"

You can also add this to your ~/.bashrc to make this process easier.

Install Python dependencies:

pip install -r src/suave/requirements.txt

Install the ROS dependencies:

source /opt/ros/humble/setup.bash
cd ~/suave_ws/
rosdep install --from-paths src --ignore-src -r -y

Build the project:

cd ~/suave_ws/
colcon build --symlink-install

If you have memory problems while building the package, run the following command instead, it is slower but uses less memory:

colcon build --symlink-install --executor sequential --parallel-workers 1

Install a MAVROS dependency:

wget https://raw.githubusercontent.com/mavlink/mavros/master/mavros/scripts/install_geographiclib_datasets.sh
sudo bash ./install_geographiclib_datasets.sh

Now you can proceed to run the exemplar.

Run SUAVE

Runner

Trying it out!

If you simply want to try out the exemplar, simply enter the following commands in a terminal:

cd ~/suave_ws/src/suave/runner/
./example_run.sh

Within a couple of minutes, some new terminals should open as well as the Gazebo simulator. A default mission is executed of inspecting the pipeline with a time limit. To follow the robot as it progresses along its mission make sure to right click and follow it in the entity tree of Gazebo as shown below:

Please note: It can take a little while for the robot to get moving, it is an issue we are aware of. Once it does get a move on you should see it perform its mission for about 5 minutes.

Full Runner

There are two ways to run a full experiment campaign.

Option 1 — Shell runner (simple, positional arguments):

cd ~/suave_ws/src/suave/runner/
./runner.sh false metacontrol time 2

The script takes 4 positional arguments:

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

Option 2 — ROS 2 runner (config-file driven, recommended for larger campaigns):

cd ~/suave_ws/
source install/setup.bash
ros2 run suave_runner suave_runner \
  --ros-args \
  -p gui:=False \
  -p experiments:='[
    "{\"experiment_launch\": \"ros2 launch suave_bringup mission.launch.py adaptation_manager:=bt\", \
      \"num_runs\": 2, \
      \"adaptation_manager\": \"bt\", \
      \"mission_name\": \"suave\"}"
  ]'

Or using a launch file with a config file:

ros2 launch suave_runner suave_runner_launch.py

To run the BT manager through ROS 2 actions, add use_action_server:=true to the experiment launch command, for example:

ros2 launch suave_bringup mission.launch.py \
  adaptation_manager:=bt use_action_server:=true

Without the runner

Configuring SUAVE: SUAVE has a number of parameters that may be of interest when running experiments with its missions, such as the time limit of a time constrained mission or the frequency of thruster failure. These can be found in the mission_config.yaml file. Note: When you change the mission_config file, you need to rebuild the suave_ws with colcon build --symlink-install

Note: Before starting the simulation or the ros nodes, remember that you have to source SUAVE's workspace. If you are using the dockerized version this is already done for you, therefore sourcing the workspace is not necessary.

Navigate to the workspace and source it:

cd ~/suave_ws/
source install/setup.bash

With SUAVE configured and sourced, start ArduSub, the simulation, and the SUAVE's nodes with the following instructions.

Start ArduSub

Run:

sim_vehicle.py -L RATBeach -v ArduSub --model=JSON --console

Start the simulation

Run:

ros2 launch suave simulation.launch.py x:=-17.0 y:=2.0

Note: It is possible to pass arguments to specify the x and y coordinates of where the UUV spawns, by changing the values. In the above launch command the initial coordinates are set to (-17.0, 2.0).

Start SUAVE's nodes

Run:

ros2 launch suave_bringup mission.launch.py

Mission results: The mission results will be saved in the path specified in the mission_config.yaml file.

Selecting the managing system and mission type: Launching the mission file without launch arguments will start a time-constrained mission without a managing subsystem. To select a different managing subsystem or a different type of mission, the following launch arguments can be used:

'adaptation_manager':
    Managing subsystem to be used
    available values: none/metacontrol/random/bt
    (default: 'none')

'mission_type':
    Mission label written to metrics
    (default: 'time_constrained_mission')

'result_filename':
    Filename for the mission measured metrics
    available values: any name
    (default: empty; the metrics node uses its default filename)

'use_action_server':
    For the BT manager, start managed behaviors through ROS 2 actions
    available values: true/false
    (default: false)

The arguments can be defined by adding the above arguments with the notation <name>:=<value> to the end of the command line.

An example of running with metacontrol and saving to a file called 'measurement_1':

ros2 launch suave_bringup mission.launch.py adaptation_manager:=metacontrol result_filename:=measurement_1

An example of running the BT manager in action-server mode:

ros2 launch suave_bringup mission.launch.py \
  adaptation_manager:=bt use_action_server:=true

Extending SUAVE and connecting managing subsystems

Connecting managing subsystems

SUAVE is designed to allow for different managing subsystems to be used, as long as they adhere to the correct ROS 2 interfaces. SUAVE's ROS2 interfaces are:

1. The /diagnostics topic, which is where monitoring information is published. This topic uses the diagnostic_msgs/DiagnosticArray message type
2. The /task/request and /task/cancel services, which are used to request and cancel tasks, respectively. Both services use the suave_msgs/Task service type
3. Three system_modes services to change SUAVE's LifeCycle nodes mode. These services use the system_modes_msgs/ChangeMode service type:
   1. Service /f_maintain_motion/change_mode to change the Maintain Motion node modes
   2. Service /f_generate_search_path/change_mode to change the Generate Search Path node modes
   3. Service /f_follow_pipeline/change_mode to change the Follow Pipeline node modes

Thus, to connect a different managing subsystem to SUAVE, it must subscribe to /diagnostics to get monitoring information, send adaptation goals (task) requests via /task/request and /task/cancel, and send reconfiguration requests via /f_maintain_motion/change_mode, /f_generate_search_path/change_mode, or /f_follow_pipeline/change_mode.

There are two ways to connect a new managing subsystem:

External package (recommended for standalone managing systems): Add exec_depend on suave_base in your package.xml and include suave_base.launch.py from your launch file. This starts the managed system and metrics without requiring any changes to the suave repository.

Built-in manager (contributed upstream): Create a manager-only launch file, declare the package as a suave_bringup dependency, and include it behind an adaptation_manager condition in mission.launch.py. The manager launch must not start the managed system, mission node, or metrics.

See the Extending SUAVE page for full details and examples.

Extend SUAVE

To extend SUAVE with new functionalities, it is only required to add new LifeCycle nodes that implement the new functionalities (check spiral_search_lc.py for an example), and add its different modes to the system_modes configuration file suave_modes.yaml. Note, that if you create a new configuration file, you should replace the suave_modes.yaml path with the new file path.

Troubleshooting

List of known problems and their solutions. If you find new problems and find a solution for it, please consider contributing to this section.

MAVROS and ArduSub integration problems:

A common problem that occurs over time is that some packages are upgraded in Ubuntu 22.04 and the connection between MAVROS and ArduSub stops working. I don't know how to fix this issue long term, but a workaround is to update MAVROS and/or ArduSub and check if it works again.

Before updating MAVROS and ArduSub upgrade your Ubuntu:

sudo apt update && sudo apt upgrade

Update ArduSub:

Due to ArduSub usage of submodules, it is simpler to remove the whole ArduPilot repository and build it from scratch again.

rm -rf ~/ardupilot

To find the latest version of ArduSub go to the ardupilot repo and look for the newest branch of ArduSub. This repository is tested with ArduSub commit 571e8c7. Follow the install ArduSub instructions with the selected commit or branch.

Update MAVROS: To update MAVROS, change its version in suave.repos to the desired MAVROS version or branch, then pull the workspace repositories:

cd ~/suave_ws/
vcs pull src

Alternatively, update MAVROS manually:

cd ~/suave_ws/src/mavros
git checkout ros2
git pull

Don't forget to rebuild the suave workspace:

cd ~/suave_ws/
colcon build --symlink-install

Related repository

REMARO Summer School Delft 2022 - Underwater robotics hackathon

Citation

If you find this repository useful, please consider citing the SUAVE paper:

@INPROCEEDINGS{10173938,
  author={Silva, Gustavo Rezende and Päßler, Juliane and Zwanepol, Jeroen and Alberts, Elvin and Tarifa, S. Lizeth Tapia and Gerostathopoulos, Ilias and Johnsen, Einar Broch and Corbato, Carlos Hernández},
  booktitle={2023 IEEE/ACM 18th Symposium on Software Engineering for Adaptive and Self-Managing Systems (SEAMS)},
  title={SUAVE: An Exemplar for Self-Adaptive Underwater Vehicles},
  year={2023},
  volume={},
  number={},
  pages={181-187},
  doi={10.1109/SEAMS59076.2023.00031}}

Acknowledgments

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under the Marie Skłodowska-Curie grant agreement No. 956200.

Please visit our website for more information on our project.