Run SUAVE

With 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: BLUEROV Follow

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:

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

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

First make sure you source the suave workspace:

cd ~/suave_ws/
source install/setup.bash

Then run:

Without gui:

ros2 run suave_runner suave_runner \
  --ros-args \
  -p gui:=False \
  -p experiments:='[
    "{\"experiment_launch\": \"ros2 launch suave_bt suave_bt.launch.py\", \
      \"num_runs\": 2, \
      \"adaptation_manager\": \"bt\", \
      \"mission_name\": \"suave\"}"
  ]'

With gui:

ros2 run suave_runner suave_runner \
  --ros-args \
  -p gui:=True \
  -p experiments:='[
    "{\"experiment_launch\": \"ros2 launch suave_bt suave_bt.launch.py\", \
      \"num_runs\": 2, \
      \"adaptation_manager\": \"bt\", \
      \"mission_name\": \"suave\"}"
  ]'

You can also use a launch file with a config file to make it easier to run the experiments:

ros2 launch suave_runner suave_runner.launch.py

To run SUAVE with different managing subsystems, replace the experiment_launch with the proper launch file.

Runner config reference

suave_runner/config/runner_config.yml controls all experiment parameters. The key fields are:

Parameter	Default	Description
`result_path`	`~/suave/results`	Directory where CSV result files are written
`gui`	`false`	Launch Gazebo with a visible window
`experiment_logging`	`false`	Enable verbose logging during experiments
`mission_config_pkg`	`suave_missions`	ROS package containing the mission config
`mission_config_file`	`config/runner_mission_config.yaml`	Path to mission config within that package
`initial_pos_x` / `y`	`-17.0` / `2.5`	AUV spawn position in the Gazebo world
`initial_pos_x_random_interval`	`[0.0, 0.0]`	Random offset range applied to X spawn position each run
`initial_pos_y_random_interval`	`[-0.5, 0.5]`	Random offset range applied to Y spawn position each run
`water_visibility_sec_shift`	`0.0`	Fixed time offset (s) before the water visibility disturbance
`water_visibility_sec_shift_random_interval`	`[0.0, 120.0]`	Random range added on top of the fixed offset
`thruster_events`	`[(1,failure,100), (3,failure,100)]`	List of thruster events: `(id, type, time_s)`
`thruster_events_random_interval`	`[-100.0, 100.0]`	Random offset (s) applied to each thruster event time
`random_interval`	`5`	Number of runs before re-randomising offsets
`experiments`	(see file)	List of experiment definitions (see below)

Each entry in experiments is a JSON string with four fields:

experiments:
  - |
    {
      "experiment_launch": "ros2 launch suave_bt suave_bt.launch.py",
      "num_runs": 10,
      "adaptation_manager": "bt",
      "mission_name": "suave"
    }

Field	Description
`experiment_launch`	Full `ros2 launch` command for the managing subsystem
`num_runs`	Number of times to repeat this experiment
`adaptation_manager`	Label written into result CSV files
`mission_name`	Mission label written into result CSV files

Multiple experiments can be listed and will be run sequentially. See the Metrics Reference for details on output files.

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_missions 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')

'result_filename':
    Filename for the mission measured metrics
    available values: any name
    (default: 'time_constrained_mission_results')

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 the constant distance mission with metacontrol saving to a file called ‘measurement_1’:

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