prox_mpc_demo

Runnable demonstrations of the ProxMPC stack, from a standalone closed-loop simulation of the prox_mpc_core engine to a full Nav2 + Gazebo bring-up of the prox_mpc_controller plugin.

Table of Contents

• Overview
• Prerequisites
• Three ways to run
  • Standalone simulation
  • Interactive Nav2 (kinematic plant, no Gazebo)
  • Nav2 + Gazebo Harmonic simulation
• Project Structure
• License

Overview

This package is where the ProxMPC stack becomes something you can launch. It provides the standalone prox_mpc_simulation executable and two launch files: one closes the control loop on the engine with no external simulator, and one runs the controller plugin inside a live Nav2 stack against Gazebo Harmonic. The standalone path needs only the core; the Nav2 path is the real-behaviour gate for the plugin.

Prerequisites

• Operating system: Ubuntu 24.04 (Noble).
• ROS 2 distribution: Jazzy.
• Build system: ament_cmake.
• Standalone simulation: prox_mpc_core, prox_mpc_msgs, and this package only. prox_mpc_msgs is an unconditional build dependency: the standalone node publishes prox_mpc_msgs/SolverDiagnostics.
• Nav2 + Gazebo bring-up: additionally Nav2, ros_gz, and the canonical nav2_minimal_tb3_sim scenario, plus prox_mpc_controller (and, for the predictive mode, prox_mpc_obstacle_tracker).

ROS dependencies are declared in package.xml and resolved by rosdep install. Third-party assets are attributed in THIRD_PARTY_LICENSES.md.

Three ways to run

Standalone simulation

A self-contained, closed-loop driver for the engine with no external simulator: it drives a bundled kinematic model toward a goal, publishes the command and predicted path, broadcasts the pose, and logs the solve time. Use it to run, visualize, and profile the controller without Nav2. See doc/simulation.md for the full parameter and interface reference.

colcon build --symlink-install --packages-select prox_mpc_msgs prox_mpc_core prox_mpc_demo
source install/setup.bash

Select the model with the model launch argument (bicycle or unicycle) and add rviz:=true to visualize the robot:

# default: bicycle model, no RViz
ros2 launch prox_mpc_demo simulation.launch.py

# unicycle model with RViz
ros2 launch prox_mpc_demo simulation.launch.py model:=unicycle rviz:=true

Interactive Nav2 (kinematic plant, no Gazebo)

Drive a kinematic model under a full Nav2 stack - global planner, the ProxMPC controller_server, and costmaps - and send goals by clicking Nav2 Goal in the RViz toolbar, with no Gazebo. The model’s body (the R2D2 unicycle or the blue bicycle) moves to each clicked goal. This launch lives in prox_mpc_benchmark, which owns the kinematic plant and the Nav2 base config:

colcon build --symlink-install --packages-select \
  prox_mpc_msgs prox_mpc_core prox_mpc_controller prox_mpc_benchmark prox_mpc_demo
source install/setup.bash

# unicycle (R2D2 body) - default
ros2 launch prox_mpc_benchmark interactive.launch.py

# bicycle (blue bike body)
ros2 launch prox_mpc_benchmark interactive.launch.py model:=bicycle

Nav2 + Gazebo Harmonic simulation

The real-behaviour gate for the controller plugin: it runs the plugin inside a live controller_server driving a TurtleBot3 waffle under a full Nav2 stack, with an opt-in predictive obstacle-avoidance mode. See doc/nav2-simulation.md for the scenarios, configuration rationale, and verified results.

```bash colcon build –symlink-install
–packages-select prox_mpc_msgs prox_mpc_core prox_mpc_controller prox_mpc_demo

File truncated at 100 lines see the full file

Changelog for package prox_mpc_demo

2.0.0 (2026-09-13)

• The local costmap tracks unknown space, so cells the sensor has not swept are marked NO_INFORMATION instead of being published as free.
• Nav2 parameter files follow the controller's changed defaults.
• The Nav2 parameter files set allow_reversing: true, so the demo shows the robot backing up to adjust and then pursuing the path forward. Reverse used to read as a shuffle near the goal; that was the reference collapsing to a stub ahead of the robot's own projection inside the goal tolerance, not reverse itself, and the controller now pins the reference to the goal pose there and turns on the spot for the last of the heading. Measured over cmd_vel_nav, reverse-enabled now completes every demo scenario faster than forward-only (27.8 s vs 38.6 s, 12.2 s vs 19.8 s, 9.5 s vs 21.7 s) with no Failed to make progress events against two for forward-only.
• The predictive Nav2 parameter file sets obstacle_yield_band_m: 0.5, so the robot waits for a crossing mover rather than racing it: it passed behind 6/10 against 1/10 on dynamic_circle with no collisions, and was no worse with two movers. Not set in the non-predictive file, which runs no tracker.
• Contributors: Simone Contorno

1.0.0 (2026-07-28)

• Initial release: self-contained closed-loop NMPC simulation node (bicycle / unicycle) with solve-time benchmarking, plus the Nav2 + Gazebo Harmonic bringup that exercises the controller plugin and the obstacle tracker.
• config/nav2_prox_mpc_predictive.yaml ships the benchmark's validated single-/sparse-obstacle preset (w_weight 1000, costmap_cost_threshold 253, cbf_gamma 1.0, max_obstacles 4, prediction_uncertainty_growth 0.05, max_dynamic_obstacles 2), so the demo's predictive path matches the benchmark's measured behavior.
• Contributors: Simone Contorno