Install POSIM from source

These instructions target Ubuntu 26.04, ROS 2 Lyrical, and Gazebo Jetty. For macOS, use the POSIM Docker Guide; this page does not describe a native macOS installation.

This procedure builds development main, not the published Docker candidate. It was reviewed against the installation scripts, but has not been rerun on a clean Ubuntu host during this documentation update. For the previously tested container route, use POSIM Docker Guide.

1. Check out the source

mkdir -p ~/posim_ws/src
git clone --branch main <https://github.com/IOES-Lab/POSIM.git> ~/posim_ws/src/dave
cd ~/posim_ws
git -C src/dave rev-parse HEAD

Keep the checkout directory named dave: the repository manifest uses this key so that dependency import can skip the source you already checked out.

2. Install the platform dependencies

Review src/dave/extras/ros-lyrical-gz-jetty-install.sh, then run it on the target Ubuntu machine:

ROS_DISTRO=lyrical DAVE_EXTRAS_DIR="$PWD/src/dave/extras" \
  bash src/dave/extras/ros-lyrical-gz-jetty-install.sh

This helper performs an apt system upgrade, installs ROS/Gazebo and the ArduSub/MAVROS dependencies, and adds environment setup to the user's shell configuration. Read it before running, and use a fresh Bash shell rather than one already sourced for another ROS distribution. Do not run this Ubuntu apt installer on macOS or execute a remote script directly through sudo. The explicit DAVE_EXTRAS_DIR selects the helper files from the same checkout. It is a retained compatibility variable.

3. Import companion repositories and build

In a Bash terminal:

cd ~/posim_ws
source /opt/ros/lyrical/setup.bash
source "$HOME/.ros_ardusub_env/env"
vcs import src --shallow --skip-existing \
  --input src/dave/extras/repos/posim.lyrical.repos
rosdep update --rosdistro lyrical
rosdep install --rosdistro lyrical --from-paths src --ignore-src -r -y
colcon build --merge-install --executor sequential --symlink-install
source install/setup.bash

The manifest tracks the companion dockwater and rocker repositories on their main branches. For a repeatable experiment, save the resolved revisions:

vcs export src --exact > resolved.repos

CUDA sonar targets are conditional on a CUDA toolkit. Installing the rest of the workspace without CUDA does not enable those sonar targets. WGPU is not part of the initial POSIM import.

4. Run a first scene

Terminal A — your sourced native Bash shell: choose one of the launches below. Stop it before trying another.

ros2 launch dave_demos dave_world.launch.py world_name:=dave_ocean_waves

For a server-only world: