Project Overview

This repository set provides a ROS 2 underwater vehicle-manipulator system centered on a BlueROV-style floating base and a Reach Alpha manipulator. It is designed to run the same high-level procedures across simulation, mixed hardware/simulation, and hardware-in-the-loop experiments.

The stack is split across two main packages:

  • uvms-simulator provides the exported ROS package ros2_control_blue_reach_5. It contains the launch system, xacro/URDF robot descriptions, ros2_control hardware interfaces, reset/dynamics services, camera drivers, controller-manager configuration, and dependency workspace metadata.

  • uvms-simlab provides the exported ROS package simlab. It contains the interactive RViz runtime, controller implementations, planner action server/client, replay profiles, experiment logging, joystick interfaces, mocap nodes, and perception utilities.

Read the stack as one UVMS project with two cooperating ROS packages: uvms-simulator owns the system description and hardware/simulator interfaces, while uvms-simlab owns the experiment/runtime behavior layered on top of those interfaces.

System Layers

  • Robot description and launch: uvms-simulator defines the UVMS model, hardware/sim selection, controller configuration, and launch-time runtime options.

  • Hardware interfaces: real and simulated manipulator/vehicle interfaces expose the same command/state surfaces through ros2_control.

  • Runtime control: uvms-simlab selects behaviors, controllers, planners, replay profiles, grasper commands, and visualization through RViz and joystick inputs.

  • Experiment infrastructure: command replay, reset/dynamics metadata, replay session logging, rosbag recording, and mocap conversion support repeatable simulator and hardware experiments.

  • Environment/perception: bathymetry/workspace visualization, collision context, camera drivers, and optional RGB-to-pointcloud utilities support planning and operator feedback.

Guide Map

Core Runtime Nodes

  • interactive_controller: RViz interactive markers, controller switching, path planning, waypoint execution, grasper commands, reset management, and command replay orchestration.

  • planner_action_server_node: OMPL-backed path-planning action server used by the interactive controller.

  • bag_recorder: rosbag2 MCAP recording for simulator and hardware sessions.

  • mocap_publisher: OptiTrack/mocap4r2 bridge output conversion and path publishing when mocap is enabled.

  • rgb2cloudpoint_publisher: optional RGB-to-pointcloud perception utility.

  • collision_contact_node, voxelviz_node, and env_obstacles_node: environment visualization and collision/context utilities.

Launch Modes

The main launch file is provided by uvms-simulator. The task:=... argument selects the runtime mode:

ros2 launch ros2_control_blue_reach_5 robot_system_multi_interface.launch.py task:=interactive

Supported launch tasks:

  • interactive: RViz interactive-marker operation with planning, replay, reset manager, grasper commands, overlays, and SimLab runtime nodes.

  • manual: PS4 joystick teleoperation through joystick_controller.

  • joint: custom joint-space command node entry point.

  • direct_thrusters: keyboard PWM channel control through direct_thruster_controller.

The operator guides focus on interactive, manual, and direct_thrusters. The joint task is primarily a developer entry point for custom joint-space command experiments.

Useful launch switches:

  • use_manipulator_hardware:=true: use real Reach Alpha hardware.

  • use_vehicle_hardware:=true: use the vehicle hardware interface.

  • sim_robot_count:=N: spawn N simulated UVMS robots.

  • use_mocap:=true: start OptiTrack/mocap4r2 bridge and mocap visualization nodes. The default is false.

  • record_data:=true: start rosbag2 MCAP recording.

  • gui:=false: run without RViz.

  • launch_camera:=auto|true|false: control the GStreamer camera node.

  • simulate_camera:=true: use a synthetic test-pattern camera.

Command Replay

Command replay profiles live in uvms-simlab/resource/playback_profile. Replay is explicit: select CmdReplay, select a profile, then reset/play from the Cmd Replay menu. Profile details are covered in Command Replay and Experiments.

Controller Modes

The default controller is selected at startup but remains inactive until the user explicitly activates a behavior. Plan & Execute activates the selected feedback controller on demand. CmdReplay remains isolated from planner execution.

Dynamics Provenance

The generated dynamics functions used by the stack come from two companion projects:

  • Floating-KinDyn-Graph: URDF-based fixed- and floating-base serial-manipulator modeling. It generates CasADi graphs for kinematics, Jacobians, Lagrangian dynamics, energy terms, payload/friction effects, identification regressors, and controller utilities.

  • diff_uv: differentiable 6-DOF underwater-vehicle dynamics based on Fossen-style marine craft models, including body/NED/quaternion kinematics, forward and inverse dynamics, hydrodynamic terms, restoring forces, system-identification utilities, EKF utilities, nonlinear PID helpers, and CasADi code generation.

Hardware Versus Simulation

Simulator state reset controls are exposed through Reset Manager and are hidden for the robot_real_ hardware namespace. Replay under robot_real_ uses controller-based settling before playback rather than simulator state reset.

Capability Map

  • Multi-robot simulated UVMS bringup.

  • Real/sim manipulator and vehicle mixing through launch arguments.

  • Shared ros2_control command/state interfaces for simulator and hardware.

  • Simulator reset/release and typed robot dynamics services.

  • Hydrostatic-compensated feedback, computed-torque/inverse-dynamics control, and extensible controller paths.

  • OMPL vehicle planning through an action server.

  • RViz interactive marker target selection.

  • Vehicle waypoint queues and waypoint execution.

  • Whole-body and joint-space control modes.

  • PS4 joystick teleoperation.

  • Direct thruster PWM keyboard testing.

  • Command replay from CSV profiles with reset/dynamics metadata.

  • Optional replay-session CSV logging.

  • Mocap pose/path conversion and visualization when enabled.

  • Camera launch, simulated camera mode, and optional RGB-to-pointcloud support.

  • Bathymetry/workspace visualization and collision context.