FixTheRobot Explore Robotics / Systems Engineering / Troubleshooting

Troubleshooting · Navigation and control

Robot oscillates near obstacles

Oscillation is a feedback problem somewhere between perception, costmap, controller and actuators. Find the loop that is unstable by measuring commanded versus actual motion.

  • Related modules: 13, 14
  • ROS 2 Jazzy

1. Symptoms

  • The robot swings left and right while following a path, or zig-zags near walls and obstacles.
  • It stops and starts repeatedly in front of an obstacle.
  • Oscillation appears only near obstacles or only at higher speed.

2. Possible causes

  • Costmap gradient too steep or noisy: obstacle cost flickers frame to frame (ghost or flickering obstacles), so the controller keeps changing its mind.
  • Inflation or footprint wrong: the robot appears nearly in collision and is pushed back and forth.
  • Controller gains or look-ahead too aggressive for the robot’s dynamics.
  • Latency in localisation, perception or actuation: the controller reacts to old information.
  • Localisation noise: pose jitter looks like path deviation.
  • Velocity tracking failure: the robot does not execute the commanded velocity (saturation, slip, motor lag).

3. Measurements to collect

  • Commanded versus measured linear and angular velocity (are they tracking?).
  • The local costmap values around the robot over time (do they flicker?).
  • Pose jitter while stationary.
  • End-to-end delay from obstacle appearance to commanded change.
  • The oscillation frequency and amplitude.

4. Diagnostic commands

Commands are not executed by the site’s automated tests (they need a ROS 2 Jazzy installation or the robot).

ros2 topic echo /cmd_vel                                # what the controller commands
ros2 topic echo /odom --field twist.twist              # what the robot did
ros2 topic hz /cmd_vel
ros2 topic hz /local_costmap/costmap
ros2 param get /local_costmap/local_costmap inflation_layer.inflation_radius
ros2 bag record -o osc /cmd_vel /odom /scan /tf /local_costmap/costmap

5. Step-by-step investigation

  1. Does the robot track the command? Plot commanded and measured velocity. If they differ in amplitude or lag, fix velocity tracking first (limits, gains, slip): oscillation in the controller is the wrong place to look.
  2. Does the costmap flicker? View the local costmap in RViz while the robot is still near the obstacle. Flicker means noisy sensor data or clearing/marking settings; compare with the costmap tuning guide.
  3. Is the footprint right? If inflated lethal cells touch the robot at rest near a wall, the footprint or inflation is too large.
  4. Measure the loop delay. Estimate sensing + processing + actuation latency; if the oscillation period is a few times that delay, latency is the cause (reduce gains or reduce delay).
  5. Check localisation jitter with the robot stationary: pose noise of centimetres feeds directly into the path error.
  6. Only then tune the controller: reduce look-ahead sensitivity or gains, or lower the speed limit near obstacles.

6. Corrective actions

  • Make velocity tracking match the command (limits, controller, slip, calibration).
  • Fix flickering obstacles: adjust marking and clearing ranges and sensor frames.
  • Correct the footprint and inflation to the real robot.
  • Reduce end-to-end latency, or reduce controller gain to suit it.
  • Reduce localisation noise or filter the pose used for control.
  • Reduce speed near obstacles.

7. Validation after the fix

  • A repeated pass (at least 20) along the same obstacle shows no sustained oscillation: lateral deviation settles below your limit.
  • Commanded and measured velocity agree within tolerance.
  • The costmap is stable when the scene is static.
  • Behaviour holds at the maximum operating speed.

References

  • The existing lab “Fix the Oscillating Robot” and the Nav2 lessons cover the controller side in a simulator.