nav2_controllers
git clone --depth 1 https://github.com/harunkurtdev/ros2-claude-code-template /tmp/nav2_controllers && cp -r /tmp/nav2_controllers/.claude/skills/nav2_controllers ~/.claude/skills/nav2_controllersSKILL.md
# Nav2 Controller Plugins
Source: `~/nav2_ws/src/navigation2/`
## Controller Server
**Package:** `nav2_controller`
**Action:** `FollowPath` (nav2_msgs::action::FollowPath)
**Plugin Base:** `nav2_core::Controller`
Hosts controller plugins, progress checkers, goal checkers, and path handlers. Runs at `controller_frequency` (default 20Hz).
---
## 1. DWB Controller (Dynamic Window Based)
**Package:** `nav2_dwb_controller`
**Plugin:** `dwb_core::DWBLocalPlanner`
**Best for:** General purpose differential-drive robots
### Architecture
`DWBLocalPlanner` → `StandardTrajectoryGenerator` + `TrajectoryCritics`
Samples velocity space, generates trajectory candidates, scores with critics, picks best.
### 13 Critic Plugins
| Critic | Purpose |
|--------|---------|
| `PathDist` | Distance from trajectory to global path |
| `GoalDist` | Distance from trajectory endpoint to goal |
| `PathAlign` | Alignment of trajectory heading with path direction |
| `GoalAlign` | Alignment with goal orientation |
| `BaseObstacle` | Obstacle avoidance using robot center |
| `FootprintObstacle` | Obstacle avoidance using full footprint |
| `ObstacleFootprint` | Alternative footprint obstacle scorer |
| `RotateToGoal` | Penalize non-rotation when near goal |
| `Oscillation` | Penalize oscillating commands |
| `PreferForward` | Prefer forward motion |
| `Twirling` | Penalize unnecessary rotation |
| `MapGrid` | Grid-based cost scoring (base for Path/GoalDist) |
| `StandardTrajectoryGenerator` | Velocity sample generation |
### Key Parameters
```yaml
FollowPath:
plugin: "dwb_core::DWBLocalPlanner"
# Velocity limits
min_vel_x: 0.0
max_vel_x: 0.26
min_vel_y: 0.0
max_vel_y: 0.0
max_vel_theta: 1.0
min_speed_xy: 0.0
max_speed_xy: 0.26
# Acceleration limits
acc_lim_x: 2.5
acc_lim_y: 0.0
acc_lim_theta: 3.2
decel_lim_x: -2.5
decel_lim_y: 0.0
decel_lim_theta: -3.2
# Sampling
vx_samples: 20
vy_samples: 5
vtheta_samples: 20
sim_time: 1.7
linear_granularity: 0.05
angular_granularity: 0.025
# Critics
critics: ["RotateToGoal","Oscillation","BaseObstacle","GoalAlign","PathAlign","PathDist","GoalDist"]
```
---
## 2. MPPI Controller (Model Predictive Path Integral)
**Package:** `nav2_mppi_controller`
**Plugin:** `nav2_mppi_controller::MPPIController`
**Best for:** Complex environments, smooth paths, high-performance
### Architecture
`MPPIController` → `Optimizer` + `CriticManager` + `MotionModel`
Stochastic optimal control: samples thousands of trajectories, scores with critics, selects optimal.
### Motion Models
- `DiffDrive` - Differential drive
- `Omnidirectional` - Holonomic
- `Ackermann` - Car-like
### 11 Critic Plugins
| Critic | Purpose |
|--------|---------|
| `ConstraintCritic` | Enforce kinematic constraints |
| `CostCritic` | Costmap-based scoring |
| `GoalCritic` | Distance to goal |
| `GoalAngleCritic` | Orientation at goal |
| `PathAlignCritic` | Alignment with global path |
| `PathAngleCritic` | Heading angle relative to path |
| `PathFollowCritic` | Distance from path |
| `ObstaclesCritic` | Obstacle avoidance |
| `PreferForwardCritic` | Forward motion preference |
| `TwirlingCritic` | Rotation minimization |
| `VelocityDeadbandCritic` | Avoid deadband velocities |
### Key Parameters
```yaml
FollowPath:
plugin: "nav2_mppi_controller::MPPIController"
time_steps: 56
model_dt: 0.05
batch_size: 2000
ax_max: 3.0
ax_min: -3.0
ay_max: 3.0
az_max: 3.5
vx_std: 0.2
vy_std: 0.2
wz_std: 0.4
vx_max: 0.5
vx_min: -0.35
vy_max: 0.5
wz_max: 1.9
iteration_count: 1
temperature: 0.3
gamma: 0.015
motion_model: "DiffDrive"
prune_distance: 1.7
enforce_path_inversion: false
critics: [...]
# Per-critic weights
PathAlignCritic:
enabled: true
cost_weight: 14.0
threshold_to_consider: 0.5
GoalCritic:
enabled: true
cost_weight: 5.0
threshold_to_consider: 1.4
```
---
## 3. Regulated Pure Pursuit (RPP)
**Package:** `nav2_regulated_pure_pursuit_controller`
**Plugin:** `nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController`
**Best for:** Basic path tracking, low computational cost
### Architecture
`RegulatedPurePursuitController` → `CollisionChecker` + `RegulationFunctions`
Pure pursuit with velocity regulation based on curvature, obstacles, and goal proximity.
### Key Features
- Velocity-scaled or fixed lookahead distance
- Curvature-based speed regulation
- Cost-regulated linear velocity
- Approach velocity scaling near goal
- Collision detection with footprint
- Rotation to path/goal heading
### Key Parameters (30+)
```yaml
FollowPath:
plugin: "nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController"
desired_linear_vel: 0.5
lookahead_dist: 0.6
min_lookahead_dist: 0.3
max_lookahead_dist: 0.9
lookahead_time: 1.5
rotate_to_heading_angular_vel: 1.8
use_velocity_scaled_lookahead_dist: false
min_approach_linear_velocity: 0.05
approach_velocity_scaling_dist: 1.0
use_collision_detection: true
max_allowed_time_to_collision_up_to_carrot: 1.0
use_regulated_linear_velocity_scaling: true
use_cost_regulated_linear_velocity_scaling: false
regulated_linear_scaling_min_radius: 0.9
regulated_linear_scaling_min_speed: 0.25
allow_reversing: false
max_angular_accel: 3.2
rotate_to_heading_min_angle: 0.785
```
---
## 4. Graceful Controller
**Package:** `nav2_graceful_controller`
**Plugin:** `nav2_graceful_controller::GracefulController`
**Best for:** Tight spaces, smooth continuous motions
### Architecture
`GracefulController` → `EgoPolarCoords` + `SmoothControlLaw`
Uses ego-polar coordinate system for mathematically guaranteed smooth convergence.
### Key Parameters
```yaml
FollowPath:
plugin: "nav2_graceful_controller::GracefulController"
# Control law gains
k_phi: 2.0
k_delta: 1.0
beta: 0.4
lambda: 2.0
# Velocity limits
v_linear_min: 0.1
v_linear_max: 0.5
v_angular_max: 1.0
# Behavior
slowdown_radius: 1.5
initial_rotation:Use proactively before opening a PR that adds or changes BehaviorTree.CPP nodes or BehaviorTree.ROS2 wrappers (RosActionNode/RosServiceNode/RosTopicPub/SubNode, TreeExecutionServer). Reviews a diff against BT.CPP v4 conventions — node base-class choice, non-blocking ticks, ports/blackboard typing, factory/plugin registration, XML v4, and the ROS 2 wrapper contract. Returns a punch list with file:line anchors, not a rewrite.
Use when a design decision touches Clean Architecture boundaries in a ROS 2 project — which layer a new behaviour belongs to, whether a port belongs in domain or application, whether a new node should be lifecycle-managed, whether to compose nodes or split packages. Returns an architectural recommendation with trade-offs, not implementation.
Use when a design decision touches the gz-sim ECS — where new state should live, which system phase should write it, how to avoid coupling, whether to add a component vs. a member variable, whether a new system should be split or merged with an existing one. Returns an architectural recommendation with trade-offs, not implementation.
Use proactively before opening any gz-sim PR. Reviews a diff against the project's C++17 style, ECS conventions, plugin registration patterns, CMake structure, test placement, Migration.md / Changelog.md expectations, and pre-commit configuration. Returns a punch list, not a rewrite.
Use proactively before opening a PR that adds or changes a ros2_control controller, broadcaster, or hardware component (incl. URDF <ros2_control> bringup). Reviews a diff against ros2_controllers / ros2_control_demos conventions — controller & hardware lifecycle, command/state interface configuration, real-time safety of update()/read()/write(), generate_parameter_library usage, pluginlib registration, chainable-controller correctness, URDF wiring, and tests. Returns a punch list with file:line anchors, not a rewrite.
Use proactively before opening any ROS 2 / Nav 2 PR. Reviews a diff against this template's Clean Architecture, ROS 2 communication, lifecycle, testing, and Nav 2 plugin conventions. Returns a punch list with file:line anchors, not a rewrite.
Use proactively before opening a PR that touches a VDA 5050 connector / fleet bridge. Reviews a diff against VDA 5050 v3.0.0 protocol compliance (topics, QoS, header rules, base/horizon, action state machine, schema validation) and the template's Clean Architecture for the MQTT↔Nav 2 bridge. Returns a punch list with file:line anchors, not a rewrite.
Build the colcon workspace (optionally a single package) and report the outcome.