CmdVel

The most common message type in mobile robotics. Sends a velocity command with forward speed (linear) and turning rate (angular) to a differential drive, holonomic base, or any mobile platform.

When to Use

Use CmdVel whenever you need to command robot motion. This is the standard interface between planners/controllers and drive systems. Every mobile robot recipe uses this type.

ROS2 Equivalent

geometry_msgs/Twist (2D subset) — HORUS uses a dedicated 2D type for the common case. For full 3D velocity, use Twist.

Rust Example

use horus::prelude::*;

// Command: drive forward at 0.5 m/s, turn left at 0.3 rad/s
let cmd = CmdVel { linear: 0.5, angular: 0.3, timestamp_ns: 0 };

let topic: Topic<CmdVel> = Topic::new("cmd_vel")?;
topic.send(cmd);

// SAFETY: always send zero velocity on shutdown
topic.send(CmdVel { linear: 0.0, angular: 0.0, timestamp_ns: 0 });

Python Example

import horus

cmd = horus.CmdVel(linear=0.5, angular=0.3)
topic = horus.Topic(horus.CmdVel)
topic.send(cmd)

Fields

FieldTypeUnitDescription
timestamp_nsu64nsTimestamp (nanoseconds since epoch)
linearf32m/sForward velocity (positive = forward, negative = backward)
angularf32rad/sTurning rate (positive = counter-clockwise, negative = clockwise)

Safety Notes

  • Always send zero on shutdown — implement shutdown() to send CmdVel { linear: 0.0, angular: 0.0, .. }. Prevents runaway if the controller crashes.
  • Clamp values — enforce maximum speed/turn rate before sending to hardware.
  • Pair with E-stop — the Emergency Stop recipe overrides cmd_vel when triggered.

Differential Drive Kinematics

Convert CmdVel to left/right wheel speeds:

let left  = (cmd.linear - cmd.angular * wheel_base / 2.0) / wheel_radius;
let right = (cmd.linear + cmd.angular * wheel_base / 2.0) / wheel_radius;

See the Differential Drive recipe for a complete example.