# LRAUV Gazebo simulation support

## Installation

### Use Docker image

Follow the [instructions](https://github.com/osrf/lrauv/wiki/Installation) on how to install the LRAUV Gazebo simulation using Docker images.

Then, build the latest MBARI-specific LRAUV Gazebo simulation image:

```sh
docker build --target lrauv-gz-sim -t mbari/lrauv-gz-sim:latest -f Tools/gz/Dockerfile git@bitbucket.org:mbari/lrauv-application.git
```

By default, this image will bring-up a complete, single-vehicle simulation session for debugging:

```sh
xhost +local:
docker run --rm -e DISPLAY -e MESA_GL_VERSION_OVERRIDE=3.3 -v /tmp/.X11-unix:/tmp/.X11-unix:ro --gpus all -it mbari/lrauv-gz-sim:latest
```

You may also run integration tests:

```sh
xhost +local:
docker run --rm -e DISPLAY -e MESA_GL_VERSION_OVERRIDE=3.3 -v /tmp/.X11-unix:/tmp/.X11-unix:ro --gpus all -it mbari/lrauv-gz-sim:latest /bin/bash
cd src/lrauv-application && for executable in ./bin/LRAUV_*Test; do executable; done  # once inside the container
```

**Note**: at the moment, these Docker images require Nvidia graphics. Make sure you have a recent version of [Docker](https://docs.docker.com/) and [nvidia-docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker) installed if so required by your Docker version.

**Note**: make sure NVidia drivers are installed and NVidia PRIME graphics multiplexing is disabled.

#### Uploading to Dockerhub

You may push the `mbari/lrauv-gz-sim:latest` image to Dockerhub ie. a public Docker images repository, as it does not contain any MBARI proprietary source code.

Make sure you have permissions to push to [MBARI's DockerHub organization](https://hub.docker.com/u/mbari). Then:

```sh
docker push mbari/lrauv-gz-sim:latest
```

### Build from source

There are two ways to build the LRAUV Gazebo simulation support from source:

1. Using local workspaces
1. Using a containerized workspace

#### Using local workspaces

Follow the [instructions](https://github.com/osrf/lrauv/wiki/Installation) on how to install the LRAUV Gazebo simulation from source in a local workspace.

Then follow the instructions on how to build MBARI's `lrauv-application` from source.

Finally, build the LRAUV Gazebo simulation support for MBARI's `lrauv-application`:

```sh
export LRAUV_WS=path/to/lrauv_ws
. $LRAUV_WS/install/setup.sh
cd path/to/lrauv-application
make clean && make gazebo
```

You may also want to create per-vehicle run folders to simplify multi-vehicle simulations:

```sh
cd path/to/lrauv-application/..
./lrauv-application/Tools/gz/make_vehicles_folder ./vehicles ./lrauv-application
```

#### Using a containerized workspace

Follow the [instructions](https://github.com/osrf/lrauv/wiki/Installation) on how to install the LRAUV Gazebo simulation using Docker images. In particular, we will need an `osrf/lrauv:latest` image or similar bearing Gazebo and LRAUV simulation installations.

Then, setup a containerized workspace within MBARI's `lrauv-application` directory (or in a parent directory, which is useful when modifying upstream dependencies):

```sh
cd path/to/lrauv-application
./Tools/gz/workspace.sh
```

This setup process will extend the `osrf/lrauv:latest` image to include all build dependencies for MBARI's `lrauv-application`. Once the setup process is complete, an `enter` script will have been created. When executed, this script will start the container, mounting the parent directory (ie. the workspace directory) within, and attach the current terminal to it. You may leave `exit` this environment at any time. Changes applied to any file or subdirectory within the workspace directory will persist.

Now you can proceed to build the LRAUV Gazebo simulation support for MBARI's `lrauv-application`:

```sh
./enter
make clean && make gazebo # once inside the container
```

## Usage

If building from source using local workspaces, source all upstream workspaces:

```sh
. path/to/gz_ws/install/setup.bash # Only if Gazebo was built from source
. path/to/lrauv_ws/install/setup.bash
```

This needs to be done for each terminal. This is not necessary when using Docker containers, as it is taken care of automatically.

Using two terminals (or `tmux` panes, included in all Docker containers):

1. Launch a LRAUV Gazebo simulation, for example:
  
  ```sh
  gz sim tethys_at_portuguese_ledge.sdf
  ```

  For verbose debug output, add `--verbose 4` to the command.
  Unpause the simulation from the Gazebo GUI, or start the simulation right away by adding `-r` to the command.

2. Run MBARI's LRAUV controller, for example:
  
  ```sh
  cd path/to/lrauv-application
  bin/LRAUV
  ```

  You may try a circle test:
  
  ```sh
  maintain control horizontalcontrol.rudderangleaction -0.2 radian
  maintain control SpeedControl.propOmegaAction 300 rpm
  ```

  Or a mission:
  
  ```sh
  run RegressionTests/GazeboTests/testDepthVBS.xml
  ```

Check each repository for the latest set of instructions to run LRAUV simulations!