Rotation Shim Controller

name: rotation-shim-controller description: 'Configure Nav2 rotation shim controller. Use when the robot needs to rotate in place before following a path, setting angular_dist_threshold.'

RotationShimController

Purpose

The RotationShimController wraps another controller (MPPI, DWB, or RPP) and handles the initial rotation at the start of a new path. When the robot receives a new navigation goal, it often faces a different direction than the path requires. Without RotationShim, the primary controller must simultaneously rotate and translate, which can produce awkward or inefficient motion on differential-drive robots.

RotationShim solves this by:

1. Detecting that the robot's heading is misaligned with the path direction.
2. Commanding an in-place rotation to face the path.
3. Handing off to the primary controller once aligned.

Plugin: nav2_rotation_shim_controller::RotationShimController

When to Use

• Differential-drive robots: Cannot translate laterally. Without RotationShim, the robot may drive sideways or backwards initially.
• Any controller that doesn't handle initial orientation well: RPP has rotate_to_heading, but MPPI and DWB may produce suboptimal initial motion.
• Smooth start behavior: The robot cleanly rotates, then drives forward.

When NOT to Use

• Omni-directional robots: Can translate in any direction; initial rotation is unnecessary.
• Very tight spaces: In-place rotation may be blocked by nearby obstacles. The collision check helps but is not perfect.
• RPP with use_rotate_to_heading: true: RPP already handles this internally; RotationShim would be redundant.

Key Parameters

Parameter Details

angular_dist_threshold: If the angle between the robot's current heading and the direction toward the path point at forward_sampling_distance exceeds this threshold, RotationShim takes over and rotates. If below threshold, the primary controller handles immediately.

Typical values:

• 0.785 rad (~45°): Only rotate for large misalignments. Quick handoff to primary.
• 0.4 rad (~23°): Rotate for moderate misalignments. Smoother starts.
• 1.57 rad (~90°): Only rotate when nearly perpendicular to path.

forward_sampling_distance: Determines which path point to "aim" for during initial rotation. If too small, the target might be at the robot's current position (useless). If too large, the robot rotates toward a distant point that doesn't represent the immediate path direction (e.g., around a corner). Typically 0.5–1.0m.

simulate_ahead_time: During the rotation, RotationShim simulates the robot's footprint at simulate_ahead_time seconds into the future to check for collisions. If the rotation would sweep the robot into an obstacle, it aborts and passes control to the primary controller (which can handle the situation with trajectory optimization).

Configuration Structure

RotationShimController is configured as the FollowPath plugin, and the primary controller is a parameter within it:

controller_server:
  ros__parameters:
    controller_frequency: 20.0
    FollowPath:
      plugin: "nav2_rotation_shim_controller::RotationShimController"
      primary_controller: "nav2_mppi_controller::MPPIController"
      angular_dist_threshold: 0.785
      forward_sampling_distance: 0.5
      rotate_to_heading_angular_vel: 1.8
      max_angular_accel: 3.2
      simulate_ahead_time: 1.0
      # All primary controller params go here as if MPPI were the top-level plugin:
      time_steps: 56
      model_dt: 0.05
      batch_size: 2000
      # ... etc (all MPPI params)

Complete YAML: RotationShim Wrapping MPPI

controller_server:
  ros__parameters:
    controller_frequency: 20.0
    min_x_velocity_threshold: 0.001
    min_theta_velocity_threshold: 0.001
    FollowPath:
      plugin: "nav2_rotation_shim_controller::RotationShimController"
      primary_controller: "nav2_mppi_controller::MPPIController"
      # RotationShim params
      angular_dist_threshold: 0.785
      forward_sampling_distance: 0.5
      rotate_to_heading_angular_vel: 1.8
      max_angular_accel: 3.2
      simulate_ahead_time: 1.0
      # MPPI params (passed through to primary controller)
      time_steps: 56
      model_dt: 0.05
      batch_size: 2000
      iteration_count: 1
      temperature: 0.25
      gamma: 0.015
      motion_model: "DiffDrive"
      visualize: false
      vx_max: 0.5
      vx_min: -0.15
      vy_max: 0.0
      wz_max: 1.9
      ax_max: 3.0
      ax_min: -3.0
      az_max: 3.5
      vx_std: 0.2
      wz_std: 0.4
      prune_distance: 1.5
      transform_tolerance: 0.1
      critics:
        - "ConstraintCritic"
        - "CostCritic"
        - "GoalCritic"
        - "GoalAngleCritic"
        - "PathAlignCritic"
        - "PathFollowCritic"
        - "PathAngleCritic"
        - "PreferForwardCritic"
      # ... critic params as in mppi_controller.md

Behavior During Operation

1. New path received: RotationShim checks heading error against angular_dist_threshold.
2. Error exceeds threshold: RotationShim takes control. Publishes geometry_msgs/msg/TwistStamped with linear.x=0, angular.z=rotate_to_heading_angular_vel (or -rotate_to_heading_angular_vel for the shorter rotation direction).
3. Collision check: Each cycle, simulates the rotation simulate_ahead_time into the future. If collision detected, aborts rotation and passes to primary controller immediately.
4. Heading aligned: Once the heading error drops below angular_dist_threshold, hands off to the primary controller.
5. Primary controller runs: From this point, RotationShim is transparent — the primary controller handles all velocity commands until a new path is received.

Troubleshooting

• Robot rotates but then the primary controller rotates again: The angular_dist_threshold on RotationShim may be too loose (rotates to ~45° but MPPI wants exact alignment). Decrease angular_dist_threshold to match expected primary controller behavior.
• Robot won't rotate in tight spaces: The collision simulation prevents rotation. Decrease simulate_ahead_time or increase the obstacle clearance in the costmap.
• Rotation is too slow: Increase rotate_to_heading_angular_vel (respect motor limits).
• Double rotation with RPP: If using RPP as primary and RPP's use_rotate_to_heading: true, disable one of them. Either disable RPP's rotate-to-heading OR don't use RotationShim.

RotationShim with Different Controllers