What It Means to Drive Wheels with DriveAPI

There are two ways to move a robot:

1. Directly set its position — "Teleport this robot 1 m forward" (kinematic)
2. Apply force to the wheels — Apply torque to wheel joints; friction does the rolling (PhysX)

Both make the robot move forward, but only option 2 produces a verifiable simulation. And what makes option 2 work is DriveAPI.

Wheels Are Joints, and DriveAPI Is Their Motor

A robot's wheels and arm joints are all joints within an articulation (a tree of connected rigid bodies). Attaching DriveAPI to a joint lets you specify a target velocity (or position) plus stiffness and damping — PhysX then computes the required torque automatically.

Rendering diagram…

The key is that DriveAPI behaves like a spring: torque is proportional to the error between current and target velocity (stiffness). If a wheel slips or is blocked, the robot responds realistically — a world apart from kinematic position-forcing.

Two moments from one run. Light bars are the wheel angular velocities handed to DriveAPI as targets; dark bars are the joint velocities actually measured on that tick. While cruising (left) target and measurement nearly coincide, but while decelerating to avoid an obstacle (right) targets of [0.89, 1.00] meet measurements of [1.13, 0.76] — because the wheel is not being forced to a velocity, it is being given torque proportional to the error. The body speed still lands on 0.152 m/s against a commanded 0.156.

One more thing follows from this: what decides the damping value. The same run's setup log reads:

[PhysX V16] ... mass=56.58kg(USD), manifest=50.0kg, scale=1.23, drive=differential
[Isaac] HO_A: P0-3 DriveAPI damping=38760 (mass=56.58kg, factor=0.863)

Damping is derived from mass, and that mass is the 56.58 kg carried inside the USD asset, not the 50.0 kg declared in the manifest. When the two disagree, it is the value inside the asset that drives the wheels — which is frequently the answer to "the spec sheet says 50 kg, so why does it feel so sluggish?"

⚠️ Do not conflate actual_spd and fb_spd in the logs — the former is a mean over the last five seconds of travel, the latter is the instantaneous body speed. Right after a deceleration the former is still high, and reading it alone looks like "the command is being ignored."

• Differential drive: steering from left/right wheel speed difference (most AMRs)
• Ackermann: front-wheel steering angle + rear-wheel drive (car-type vehicles)

Differential-drive wheel-speed splitting is just two lines.

# cmd_vel (forward vx, turn ωz) → left/right wheel angular velocity
def differential_drive(vx, wz, wheel_radius, wheel_base):
    v_left  = (vx - wz * wheel_base / 2) / wheel_radius
    v_right = (vx + wz * wheel_base / 2) / wheel_radius
    return v_left, v_right   # → fed as each wheel's DriveAPI target velocity

From cmd_vel to Wheel Torque

The chain from a navigation stack's cmd_vel (forward velocity vx, angular velocity ωz) to actual wheel rotation looks like this:

Rendering diagram…

💡 DriveAPI stores energy like a spring — If a wheel is blocked and can't reach target velocity, the error torque keeps accumulating and can cause a sudden lurch when the obstacle clears. Commands must be appropriately damped to prevent energy runaway.

⚠️ Hard-coding velocity or torque limits inside system code makes them wrong for every robot. These values belong in each robot's manifest parameters — because a new robot is added with just one manifest.

Why Torque?

Position teleportation is simpler — so why go through torque? Because physical fidelity requires it. Slowing on a ramp when torque is insufficient, spinning out on a slippery floor, sluggish acceleration under a heavy load — all of these emerge naturally from PhysX torque-based physics. That is why policies trained and validated in simulation also work on real hardware (Sim-to-Real).

In a nutshell

📌 Wheels and joints are articulation joints, and DriveAPI (target velocity + stiffness/damping) lets PhysX compute the torque that drives them through friction. Unlike kinematic position-forcing, slopes, slip, and payload effects emerge naturally — this is the foundation of Sim-to-Real transfer.