Control differential-drive and holonomic-drive robots#
Convert planar body-velocity commands into wheel targets for differential-drive and holonomic-drive robots. This tutorial compares the two kinematic models, applies their named controller output to simulated articulations, and verifies the resulting wheel and body motion.
Learning objectives#
After completing this tutorial, you can:
Choose a drive model from the motion a mobile robot must support.
Express planar motion as a named control-point state.
Configure
DifferentialDriveControllerandHolonomicControllerfrom robot geometry.Map named wheel commands to articulation degrees of freedom (DOFs).
Validate controller output against measured wheel velocities and body motion.
Prerequisites#
Complete Install and run.
Run the commands in this tutorial from the repository root.
Use a graphical desktop for the interactive runs. The tests use offscreen rendering.
Allow the examples to resolve the TurtleBot3 and NVIDIA Kaya assets, or set
ISAACSIM_ASSET_ROOTto another asset root.
Examples used#
Example |
Role in this tutorial |
|---|---|
Maps linear and angular velocity commands to two wheel speeds for a differential-drive base. |
|
Maps body-velocity commands to three wheel speeds for a holonomic-drive base. |
Each example page lists its source directory, requirements, and runner commands.
Choose a drive model#
Both controllers accept a desired planar body velocity and return named wheel velocities. The available motion and required geometry differ:
Model |
Body command |
Required geometry |
|---|---|---|
Differential drive |
Forward speed and yaw rate. |
Left and right wheel names, wheel radius, and wheel base. |
Holonomic drive |
Forward speed, lateral speed, and yaw rate. |
Wheel names, radii, positions, orientations, and roller angles. |
Use differential drive when the base cannot translate sideways. Use holonomic drive when the wheel arrangement supports independent forward, lateral, and yaw motion.
Represent the body command#
The controllers use a named control_point site rather than a controller-specific tuple. This keeps the command
inside the same motion-generation state model used by other robot controllers.
Differential-drive command#
The differential-drive example places forward speed on the control point’s X-axis and yaw rate around its Z-axis:
def _make_setpoint(linear_speed: float, yaw_rate: float) -> mg.RobotState:
"""Build the control-point velocity requested by DifferentialDriveController.
Args:
linear_speed: Requested forward speed in meters per second.
yaw_rate: Requested yaw rate in radians per second.
Returns:
Named control-point velocity state.
"""
return mg.RobotState(
sites=mg.SpatialState.from_name(
spatial_space=["control_point"],
linear_velocities=(
["control_point"],
wp.array([[linear_speed, 0.0, 0.0]], dtype=wp.float32, device="cpu"),
),
angular_velocities=(
["control_point"],
wp.array([[0.0, 0.0, yaw_rate]], dtype=wp.float32, device="cpu"),
),
)
)
A differential-drive base cannot command lateral velocity. For wheel radius \(r\), wheel base \(L\), forward speed \(v\), and yaw rate \(\omega\), its wheel speeds are:
The TurtleBot3 command uses 0.15 m/s and 1.0 rad/s. The positive yaw rate makes the right wheel rotate faster
than the left wheel, which turns the robot left.
Holonomic-drive command#
The holonomic-drive example adds lateral speed on the control point’s Y-axis:
def _make_setpoint() -> mg.RobotState:
"""Build a command with forward speed, lateral speed, and yaw rate.
Returns:
Named control-point velocity state.
"""
site = "control_point"
return mg.RobotState(
sites=mg.SpatialState.from_name(
spatial_space=[site],
linear_velocities=([site], wp.array([[COMMAND[0], COMMAND[1], 0.0]], dtype=wp.float32, device="cpu")),
angular_velocities=([site], wp.array([[0.0, 0.0, COMMAND[2]]], dtype=wp.float32, device="cpu")),
)
)
COMMAND stores (forward speed, lateral speed, yaw rate). The NVIDIA Kaya robot uses
(0.20, 0.10, 0.50), with linear components in meters per second and the angular component in radians per second.
Configure the controllers#
Configure a controller from the geometry of the same robot asset you simulate. Geometry and joint order are part of the controller contract, not interchangeable tuning values.
Configure differential drive#
The differential-drive controller resolves the left and right wheel names within the articulation’s complete joint space:
# Configure the controller from the TurtleBot3 wheel geometry and joint names.
robot = ArticulationEntity(ENGINE, ARTICULATION_PATH)
controller = controllers.DifferentialDriveController(
robot_joint_space=list(robot.dof_names),
left_wheel_joint=LEFT_WHEEL_JOINT,
right_wheel_joint=RIGHT_WHEEL_JOINT,
wheel_radius=WHEEL_RADIUS,
wheel_base=WHEEL_BASE,
max_linear_speed=LINEAR_SPEED,
max_angular_speed=MAX_YAW_RATE,
device="cpu",
)
controller.reset(mg.RobotState(), None, 0.0)
# Convert the desired body velocity into named wheel-velocity targets.
initial_position = robot.get_world_poses()[0].numpy()[0]
setpoint = _make_setpoint(LINEAR_SPEED, YAW_RATE)
desired_state = controller.forward(mg.RobotState(), setpoint, 0.0)
if desired_state is None or desired_state.joints is None or desired_state.joints.velocities is None:
raise RuntimeError("DifferentialDriveController did not produce wheel velocity targets.")
wheel_velocities = desired_state.joints.velocities.numpy()
wheel_velocities_by_name = dict(zip(desired_state.joints.velocity_names, wheel_velocities, strict=True))
expected_names = {LEFT_WHEEL_JOINT, RIGHT_WHEEL_JOINT}
if set(wheel_velocities_by_name) != expected_names:
raise RuntimeError(
f"Unexpected wheel velocity names {sorted(wheel_velocities_by_name)}; expected {sorted(expected_names)}."
)
actual_left = float(wheel_velocities_by_name[LEFT_WHEEL_JOINT])
actual_right = float(wheel_velocities_by_name[RIGHT_WHEEL_JOINT])
wheel_indices = robot.get_dof_indices(desired_state.joints.velocity_names)
wheel_targets = wp.array(wheel_velocities.reshape(1, -1), dtype=wp.float32, device="cpu")
robot.set_dof_velocity_targets(wheel_targets, dof_indices=wheel_indices)
The returned state associates each velocity with a wheel name. The example resolves those names to articulation DOF indices before applying the targets, so it does not assume a fixed asset joint order.
Configure holonomic drive#
The holonomic-drive controller additionally needs each wheel’s position, orientation, radius, and roller angle in
the robot-base frame. Each geometry row must describe the wheel at the same index in WHEEL_JOINTS:
# Controller geometry authored in the versioned NVIDIA Kaya asset below.
WHEEL_RADIUS = 0.04
WHEEL_POSITIONS = [
[-0.09804319, 0.00063677, -0.05050102],
[0.04934748, -0.08452497, -0.05050102],
[0.04952906, 0.08569367, -0.05050102],
]
WHEEL_ORIENTATIONS = [
[-0.00000005, 0.0, 0.0, 1.0],
[0.8660267, 0.0, 0.0, -0.4999977],
[0.86602294, 0.0, 0.0, 0.50000423],
]
MECANUM_ANGLE = 90.0
Create the controller and expand its three named wheel values into the articulation’s complete DOF target row:
# Configure the controller from the NVIDIA Kaya wheel geometry and joint names.
robot = ArticulationEntity(ENGINE, ROBOT_PATH)
controller = controllers.HolonomicController(
robot_joint_space=list(robot.dof_names),
wheel_joint_names=WHEEL_JOINTS,
wheel_radius=WHEEL_RADIUS,
wheel_positions=WHEEL_POSITIONS,
wheel_orientations=WHEEL_ORIENTATIONS,
mecanum_angles=MECANUM_ANGLE,
max_linear_speed=0.6,
max_angular_speed=3.0,
device="cpu",
)
controller.reset(mg.RobotState(), None, 0.0)
# Convert the desired planar body velocity into named wheel-velocity targets.
desired_state = controller.forward(mg.RobotState(), _make_setpoint(), 0.0)
if desired_state is None or desired_state.joints is None or desired_state.joints.velocities is None:
raise RuntimeError("HolonomicController did not produce wheel velocity targets.")
if desired_state.joints.velocity_names != WHEEL_JOINTS:
raise RuntimeError(f"Unexpected wheel command order: {desired_state.joints.velocity_names}")
wheel_velocities = desired_state.joints.velocities.numpy()
wheel_indices = robot.get_dof_indices(desired_state.joints.velocity_names).numpy()
all_dof_targets = np.zeros((1, len(robot.dof_names)), dtype=np.float32)
all_dof_targets[0, wheel_indices] = wheel_velocities
velocity_targets = wp.array(all_dof_targets, dtype=wp.float32, device="cpu")
robot.set_dof_velocity_targets(velocity_targets)
initial_position = robot.get_world_poses()[0].numpy()[0]
The complete row preserves zero targets for non-wheel DOFs. This differs from the differential-drive example, whose physics setter accepts the two resolved wheel indices directly.
Apply and observe the commands#
Both examples follow the same simulation boundary:
Apply controller output through
ArticulationEntity.Advance OvPhysX by a fixed time step through
PhysicsManager.Publish measured transforms to the Foundation stage.
Render the synchronized stage with OVGL.
Publishing after physics advances keeps the rendered robot pose synchronized with measured articulation state. The interactive loops pace fixed physics steps against wall-clock time; the tests run the same bounded physics paths without waiting between frames.
Run the differential-drive example:
source/examples/example.sh run motion_generation.differential_drive
.\source\examples\example.bat run motion_generation.differential_drive
The viewport shows TurtleBot3 following a curved path.
Run the holonomic-drive example:
source/examples/example.sh run motion_generation.holonomic_drive
.\source\examples\example.bat run motion_generation.holonomic_drive
The viewport shows NVIDIA Kaya translating diagonally while rotating. Press Escape to close either viewport.
Verify the workflow#
Run the tests for both examples:
source/examples/example.sh test motion_generation.differential_drive
source/examples/example.sh test motion_generation.holonomic_drive
.\source\examples\example.bat test motion_generation.differential_drive
.\source\examples\example.bat test motion_generation.holonomic_drive
The tests check the controller calculations, compare measured and commanded wheel velocities, require planar displacement, reject unexpected vertical motion where applicable, and confirm that rendered transforms change.
Tradeoffs#
A differential-drive base is mechanically simple, but it must rotate before moving in a lateral direction.
A holonomic-drive base follows arbitrary planar commands, but its controller depends on more asset geometry and accurate wheel ordering.
Both examples issue a constant command. A navigation stack must update commands from localization, planning, and collision-avoidance feedback.
Change LINEAR_SPEED or YAW_RATE in the differential-drive example to drive straight or reverse the turn.
Change COMMAND in the holonomic-drive example to isolate lateral motion or rotation. Run the corresponding test
after each change; its expected result is derived from the example constants.
Next steps#
Continue with Generate manipulator motion from trajectories and targets to compare time-parameterized and feedback-driven motion for an articulated arm.