Robot does not follow velocity commands

1. Symptoms

• cmd_vel is published and the robot does not move.
• It moves only briefly or jerks.
• It moves in the wrong direction or at the wrong speed.

2. Possible causes

• The controller listens on another topic or namespace, or is not active.
• cmd_vel_timeout expires between messages.
• A velocity smoother or limit clamps the command to zero (deadband, limits).
• Emergency stop, brake or the drive disabled.
• Wrong units or sign conventions.
• The hardware interface is not claimed or the driver is not running.

3. Measurements to collect

• The topic the controller subscribes to and its message rate.
• Controller state and the hardware interfaces list.
• The command at each stage: smoother input and output, controller input, driver input.

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
ros2 topic info /cmd_vel --verbose
ros2 control list_controllers
ros2 control list_hardware_interfaces

5. Step-by-step investigation

1. Check the topic and its subscribers with topic info.
2. Check the controller is active and has its interfaces.
3. Check the timeout against the publisher rate.
4. Check the smoother and limits (deadband, maximum velocities).
5. Check emergency stop and drive enable.
6. Check signs and units with a small command on a lifted robot.

6. Corrective actions

• Remap to the right topic; activate the controller.
• Publish steadily or increase the timeout within safety limits.
• Correct limits and deadbands.
• Release the emergency stop and enable the drive.

7. Validation after the fix

• A small command moves the robot by the expected amount in the expected direction.

References

• diff_drive_controller parameters (ros2_controllers, jazzy branch): diff_drive_controller_parameter.yaml, read 2026-11-06.
• Nav2 velocity smoother README (jazzy): nav2_velocity_smoother, read 2026-11-06.