Installation

Use Docker image

Build the latest LRAUV simulation image:

docker build --target lrauv -t osrf/lrauv:latest -f tools/setup/Dockerfile https://github.com/osrf/lrauv.git#main

You may then run a sample simulation:

docker run --rm -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:ro -e MESA_GL_VERSION_OVERRIDE=3.3 --gpus all osrf/lrauv:latest

or attach to the container and run gz sim manually.

Note: you may have to authorize X access to run the simulation. One easy solution is to run xhost + and xhost - before and after running the container. This will allow any application to access the window manager while the simulation is running. Exercise with care. If in doubt, use containerized workspaces, which rely on a safer mechanism to achieve this.

Note: at the moment, these Docker images require Nvidia graphics. Make sure you have a recent version of Docker and nvidia-docker installed if so required by your Docker version.

Note: If you fall into this error:

fixuid: fixuid should only ever be used on development systems. DO NOT USE IN PRODUCTION
fixuid: runtime UID '1000' already matches container user 'developer' UID
fixuid: runtime GID '1000' already matches container group 'developer' GID
QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-developer'
libGL error: MESA-LOADER: failed to retrieve device information
intel_do_flush_locked failed: Invalid argument

You might need to mount the /dev/dri device as follows:

docker run --rm -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:ro -e MESA_GL_VERSION_OVERRIDE=3.3 --gpus all --device=/dev/dri:/dev/dri osrf/lrauv:latest

Build from source

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

1. Using a local workspace
2. Using a containerized workspace

Using a local workspace

Install prerequisites

Ideally you want to be running Ubuntu Focal or Jammy on an amd64 architecture.

Gazebo Garden

Gazebo is the toolbox of development libraries for simulation that is used to simulate LRAUVs. Gazebo Garden is the version used by the LRAUV simulation and it needs to be installed first.

Instructions on how to compile and install Gazebo Garden from source can be found here.

Alternatively, unstable binary packages for Gazebo Garden can also be installed from the nightly Gazebo repositories. Gazebo nightlies are packages released every night which can be used for different purposes like testing the last feature added to gazebo code. The nightly packages repository is designed to work together with the stable repository, so both need to be added:

sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'
sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-nightly `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-nightly.list'
wget https://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -

After this just update and install the Gazebo Garden metapackage:

sudo apt-get update
sudo apt-get install gz-garden

Colcon

Colcon is the command line tool used to help easily compile and test all the packages in the LRAUV repository.

First, the ROS2 repositories that contain the colcon binary packages need to be enabled:

sudo sh -c 'echo "deb [arch=amd64,arm64] http://repo.ros2.org/ubuntu/main `lsb_release -cs` main" > /etc/apt/sources.list.d/ros2-latest.list'
wget https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc -O - | sudo apt-key add -

Then just update an install the colcon packages:

sudo apt-get update
sudo apt-get install python3-colcon*

Extra dependencies

sudo apt-get install \
    libeigen3-dev \
    libpcl-dev \
    python3-empy \
    python3-numpy

Get the sources and build

mkdir -p lrauv_ws/src
cd lrauv_ws/src
git clone https://github.com/osrf/lrauv.git
cd -
colcon build

Developers may also want to build tests. Note that this will take longer:

colcon build --cmake-args "-DBUILD_TESTING=ON"

You can pass --cmake-args ' -DENABLE_PROFILER=1' to use the profiler. See more on this tutorial

Using a containerized workspace

This is the recommended mechanism for development, as it ensures a consistent environment.

Make sure you have a recent version of Docker and nvidia-docker installed if so required by your Docker version. Then, simply run the following command:

wget https://raw.githubusercontent.com/osrf/lrauv/main/tools/setup/workspace.sh -O - | bash

This invocation will setup a workspace in the current working directory, building the necessary Docker images in the process. Note this may take a while.

Once it's done with the build, run the ./enter script at the workspace root.

./enter

When executed, this script will run the container, mount the workspace into it, and attach the terminal.

Now, you can build the workspace:

export MESA_GL_VERSION_OVERRIDE=3.3
colcon build

To join in a separate terminal, simply ./enter the workspace again.