SUAVE (Self-adaptive Underwater Autonomous Vehicle Exemplar) is a ROS 2 Humble exemplar for self-adaptive robotics. An autonomous underwater vehicle (AUV) searches for a pipeline on the seabed, then follows and inspects it, while its thrusters fail, the water visibility changes, and its battery drains.
SUAVE separates the managed subsystem, which implements the AUV's mission, from the managing subsystem, which implements the adaptation logic. Any managing subsystem that uses SUAVE's ROS 2 interfaces can be plugged in, so different adaptation approaches can be compared on the same missions and metrics.
Documentation: https://kas-lab.github.io/suave/
A video of SUAVE running (click the image to open it):
An overview of the system:
With Docker installed:
git clone https://github.com/kas-lab/suave.git
cd suave
source env.sh
suave docker run
suave runsuave docker run pulls the headless image and starts a container named
suave, and suave run starts an experiment campaign in it. Results are
saved to ~/suave/results on the host. Add --gpu none to suave docker run
on machines without an NVIDIA GPU.
To try SUAVE in a browser-based desktop instead, or to install it without Docker, see Docker and Installation.
| Page | Contents |
|---|---|
| Mission and uncertainties | What the AUV does, the uncertainties it faces, its KPIs and quality requirements |
| Installation | Local installation with Gazebo, ROS 2, ArduSub, and the SUAVE workspace |
| Docker | Headless and browser-based images |
| SUAVE CLI | The suave command for containers, builds, tests, and experiments |
| Run SUAVE | Campaigns, batches, failure diagnosis, and recovery |
| Processing results | Summaries, statistical tests, plots, and LaTeX tables |
| Metrics | Recorded mission metrics and reaction times |
| Architecture | Managed functionalities, monitors, and managing-subsystem interfaces |
| Extending SUAVE | Connecting a new managing subsystem or adding functionality |
| Implementations | Available managing subsystems |
| Troubleshooting | Common problems and dependency versions |
Built into this repository:
- None: no adaptation, a lower-bound baseline.
- Random: adapts at random intervals, a chance baseline.
- Metacontrol: ontology-based reasoning with MROS2.
- Behavior Tree: adaptation logic as a BehaviorTree.CPP tree.
Maintained separately:
See Implementations for details and Extending SUAVE to connect your own.
| Path | Contents |
|---|---|
suave |
Managed subsystem functionalities and simulation launch |
suave_monitor |
Thruster, water visibility, and battery monitors |
suave_missions |
Mission nodes and mission configuration |
suave_base |
Reusable launch of the managed system and metrics, for external managing subsystems |
suave_bringup |
Launch composition of missions with the built-in managing subsystems |
suave_metrics |
Mission metrics collection |
suave_requirements |
Runtime fulfillment of the quality requirements and its plots |
suave_runner |
Experiment runner and statistical analysis |
suave_tools |
Shared helpers for result layout and labels |
suave_cli |
The suave command-line tool |
suave_msgs |
SUAVE messages, services, and actions |
suave_managing |
Built-in managing subsystems: suave_none, suave_random, suave_metacontrol, suave_bt |
docker |
Dockerfiles and image scripts |
docs |
Source of the documentation site |
runner |
Legacy shell runner scripts |
A paper describing SUAVE was presented at the SEAMS 2023 artifact track (IEEE, arXiv pre-print). If you find this repository useful, please consider citing it:
@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}}To reproduce the paper's artifact, see Reproduce the SEAMS 2023 artifact.
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.