cmd_vel (Twist message)

cmd_vel (Twist message) – definition

cmd_vel is the conventional ROS topic name used to send a commanded velocity to a mobile robot base. The message is usually geometry_msgs/msg/Twist in ROS 2 or geometry_msgs/Twist in ROS 1. It represents a velocity command rather than a measured robot velocity, estimated pose, or wheel-level motor command.

A Twist message contains two three-dimensional vectors: linear and angular. For a ground UGV with differential drive, such as Leo Rover, the command normally uses only linear.x for forward or reverse velocity and angular.z for yaw rate. The remaining components should normally be zero because the base cannot translate sideways or rotate around its roll and pitch axes.

In ROS terminology, cmd_vel is a naming convention, not a topic name mandated by the ROS middleware or a ROS Enhancement Proposal. A robot driver, velocity multiplexer, navigation stack, teleoperation node, or safety controller may publish the final command. The base controller subscribes to the topic configured in its ROS interface.

Twist message structure and coordinate conventions

The geometry_msgs/msg/Twist definition consists of two Vector3 fields. ROS uses SI units for these values. When velocity is interpreted in the robot body frame, REP 103 defines the standard coordinate convention used by ROS mobile robots: x points forward, y points left, and z points upward.

Field	Unit	Typical UGV use
`linear.x`	m/s	Forward or reverse translational velocity
`linear.y`	m/s	Normally `0.0` for differential-drive platforms
`linear.z`	m/s	Normally `0.0` for a ground vehicle
`angular.x`, `angular.y`	rad/s	Normally `0.0` for planar driving
`angular.z`	rad/s	Yaw-rate command for turning

For a differential-drive robot, the practical planar command can be written as:

v = linear.x
ω = angular.z

Where v is the requested longitudinal velocity in metres per second and ω is the requested yaw rate in radians per second. The base controller converts these values into left and right wheel velocities using its wheel radius and wheel separation parameters.

How cmd_vel works in ROS 2 navigation

In a typical ROS 2 mobile-robot system, several nodes can produce velocity commands. A teleoperation node may publish manual input, while Nav2 may publish autonomous navigation output. These sources should not publish directly to the same base-controller topic without arbitration.

A common command path contains the following elements:

A teleoperation node, joystick interface, or Nav2 controller generates a Twist.
A velocity multiplexer or safety layer selects, limits, or rejects the command.
A velocity smoother applies acceleration and deceleration limits.
The robot base driver receives the final cmd_vel command.
The base driver or controller converts the command to wheel motion and reports odometry separately.

Nav2 commonly publishes controller output to a configurable velocity topic. Depending on the Nav2 version and controller configuration, this may be cmd_vel or an intermediate topic such as cmd_vel_nav. A deployment should explicitly inspect topic remappings and controller parameters rather than assume a fixed graph.

ros2 topic info /cmd_vel
ros2 topic echo /cmd_vel
ros2 topic hz /cmd_vel

The first command identifies publishers and subscribers. The second verifies field values. The third measures the observed publish rate. ROS does not prescribe a universal cmd_vel frequency. The required rate depends on the base driver, communication path, control loop, and configured command timeout. These values must be taken from the relevant driver documentation and tested on the deployed platform.

cmd_vel on Leo Rover and Raph Rover

Leo Rover is a four-wheel, differential-drive UGV with an onboard Raspberry Pi compute unit and ROS 2 support. Supported ROS 2 distributions depend on the deployed Fictionlab software version. Its locomotion model makes linear.x and angular.z the relevant command fields. A ROS 2 navigation system typically requires additional components before autonomous operation, including localization or SLAM, obstacle sensing, a Nav2 configuration, and safety limits. Leo Rover is not autonomous out of the box.

For Leo Rover, a direct test command can be published from a ROS 2 terminal after confirming the driver topic and namespace in the platform documentation:

ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
"{linear: {x: 0.1, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.2}}"

This command requests simultaneous forward motion and a left turn. It does not guarantee that the robot will move at exactly the requested velocity. Battery state, payload, surface friction, wheel slip, driver limits, and acceleration constraints affect physical motion. Odometry and IMU data should be used to observe the resulting state.

Raph Rover also accepts planar Twist commands, but its Ackermann steering means that angular.z must stay consistent with the achievable turning radius at the commanded linear speed. Its larger payload capability can support additional LiDAR, GNSS/RTK, depth-camera, or compute payloads, but the velocity interface still requires platform-specific limits. Maximum linear speed, maximum yaw rate, acceleration limits, and emergency-stop behavior must be configured according to the installed drivetrain and payload.

Twist versus TwistStamped

geometry_msgs/msg/Twist has no header and therefore no timestamp or frame identifier. For systems that need timing information, ROS 2 also provides geometry_msgs/msg/TwistStamped, which contains a std_msgs/msg/Header and a Twist.

The distinction matters when integrating Nav2, simulation, remote operation, or command filtering. Some nodes subscribe only to Twist; others can be configured for TwistStamped. Message compatibility must be verified at the subscriber interface. A publisher of TwistStamped cannot directly communicate with a subscriber expecting Twist.

Operational limitations and safety controls

A raw cmd_vel command is not a collision-avoidance guarantee. It expresses a requested body velocity. Safe UGV operation requires a separate mechanism to stop or constrain motion when communication is lost, an obstacle is detected, localization is invalid, or an emergency stop is activated.

Before connecting autonomous software to a physical Leo Rover or Raph Rover, validate these controls:

Velocity and acceleration limits in the base driver and navigation controller.
A command timeout that stops the base when command messages cease.
Topic arbitration between teleoperation, autonomy, and safety nodes.
Correct ROS namespace and topic remapping.
Odometry, TF, and sensor timestamps consistent with the ROS clock.

Normative references and documentation

The message definition, unit conventions, and coordinate semantics are specified by ROS documentation and REP 103. Platform-specific topic names and driver behavior must be checked against the deployed Fictionlab software version.

cmd_vel (Twist message)