Installation and Build

Build the project as a ROS 2 workspace. A complete workspace normally contains:

uvms-simulator: exported ROS package ros2_control_blue_reach_5.
uvms-simlab: exported ROS package simlab.
simlab_msgs: custom planner action definitions.
Dependency repositories from uvms-simulator/dependency_repos.repos.

System Requirements

Ubuntu with ROS 2 Jazzy.
colcon, rosdep, and vcs.
CasADi built from source and available at runtime.
Git LFS for large model/resource files.

Install core apt dependencies:

sudo apt update
sudo apt install git-lfs \
    ros-$ROS_DISTRO-hardware-interface \
    ros-$ROS_DISTRO-xacro \
    ros-$ROS_DISTRO-gpio-controllers \
    ros-$ROS_DISTRO-controller-manager \
    ros-$ROS_DISTRO-joint-state-broadcaster \
    ros-$ROS_DISTRO-joint-state-publisher-gui \
    ros-$ROS_DISTRO-forward-command-controller \
    ros-$ROS_DISTRO-force-torque-sensor-broadcaster \
    ros-$ROS_DISTRO-ros2-control \
    ros-$ROS_DISTRO-mavros \
    ros-$ROS_DISTRO-mavros-msgs \
    ros-$ROS_DISTRO-nav2-msgs \
    ros-$ROS_DISTRO-rviz-imu-plugin \
    ros-$ROS_DISTRO-rviz-2d-overlay-plugins \
    ros-$ROS_DISTRO-rviz-2d-overlay-msgs \
    ros-$ROS_DISTRO-rosbag2 \
    ros-$ROS_DISTRO-plotjuggler-ros \
    ros-$ROS_DISTRO-interactive-markers \
    ros-$ROS_DISTRO-cv-bridge \
    gstreamer1.0-plugins-base \
    libgstreamer1.0-dev \
    libgstreamer-plugins-base1.0-dev

If CasADi is outside the system linker path:

export LD_LIBRARY_PATH=/path/to/casadi/build/lib:$LD_LIBRARY_PATH

Workspace Setup

mkdir -p ~/ros_ws/src
cd ~/ros_ws/src

git clone https://github.com/edxmorgan/uvms-simulator.git
git clone https://github.com/edxmorgan/uvms-simlab.git

vcs import < uvms-simulator/dependency_repos.repos

cd ~/ros_ws
rosdep install --from-paths src --ignore-src -r -y

Python Dependencies

Install Python packages used by SimLab for joystick control, planning, FCL, Ruckig, and optional perception:

python3 -m pip install pyPS4Controller pynput scipy casadi ruckig \
    python-fcl trimesh pycollada

Optional RGB-to-pointcloud support:

python3 -m pip install torch torchvision timm opencv-python

OMPL Python Bindings

The planner server uses OMPL through Python bindings. One working installation route is the Kavraki Lab installer:

wget https://ompl.kavrakilab.org/install-ompl-ubuntu.sh
chmod u+x install-ompl-ubuntu.sh
./install-ompl-ubuntu.sh --python

Build

Build and source the whole workspace:

cd ~/ros_ws
colcon build
source install/setup.bash

For focused development:

colcon build --packages-select ros2_control_blue_reach_5 simlab simlab_msgs
source install/setup.bash

Documentation Build

Install Python docs dependencies:

python3 -m pip install -r src/uvms-simulator/doc/requirements-docs.txt

Build the Sphinx site:

cd ~/ros_ws/src/uvms-simulator/doc
make html

Open:

doc/_build/html/index.html

GitHub Pages Deployment

The repository includes a GitHub Actions workflow for publishing the Sphinx site to GitHub Pages:

.github/workflows/docs-pages.yml

On pushes to main, the workflow builds doc/_build/html and deploys it as the Pages artifact. Pull requests build the docs but do not deploy them.

First Launch Check

After the build succeeds, launch one simulated interactive UVMS:

ros2 launch ros2_control_blue_reach_5 robot_system_multi_interface.launch.py \
    use_manipulator_hardware:=false \
    use_vehicle_hardware:=false \
    sim_robot_count:=1 \
    task:=interactive

For hardware launch flows, see Hardware-in-the-Loop Setup. For first-use runtime steps, see Tutorial.