Tutorial 5: Joint gains tuning

Tutorial

Maximum torque and velocity are set. Now tune how each joint responds to a new position target. Stiffness and damping form a proportional-derivative (PD) controller: stiffness pulls the joint to its target, and damping resists velocity to reduce oscillation. Use the Gain Tuner to tune these values for the thumb and assess the response with its charts.

Learning Objectives

In this tutorial, you will:

• Tune thumb drive stiffness and damping with the Gain Tuner.

• Run Step Function, Snap to Limits, and Stress tests.

• Interpret underdamped, critically damped, and overdamped joint responses.

• Save the tuned gains to a physics layer.

Prerequisites

• Complete Tutorial 4: Joint drive tuning.

• Open Isaac/Samples/Rigging/Inspire/module_4_end/inspire_hand/inspire_hand.usda.

Understand stiffness and damping

Position control in Isaac Sim uses the following relationship:

Force = (Stiffness × delta_position) + (Damping × delta_velocity)

• Stiffness acts like a spring. Higher stiffness pulls the joint more strongly toward the target.

• Damping acts like a shock absorber. Higher damping reduces oscillation and overshoot.

The ratio of stiffness to damping determines the response to a position step:

Regime	Behavior	Cause
Underdamped	The joint overshoots and oscillates before settling.	Stiffness is high relative to damping.
Critically damped	The joint reaches the target quickly without overshooting.	Stiffness and damping are balanced.
Overdamped	The joint approaches the target slowly without overshooting.	Damping is high relative to stiffness.

If the position chart shows oscillation or overshoot, increase damping or reduce stiffness. If the joint creeps toward the target, increase stiffness or reduce damping. Aim for a near-critically damped response.

Open Gain Tuner

1. Go to Tools > Robotics > Asset Editors > Gain Tuner.

The panel has two tabs, and this tutorial moves between them:

• Gain Settings holds the per-joint gain table, where you edit stiffness and damping, and the Save Target row.

• Test Gains holds Test Gains Settings, the Run Test button, and the result charts.

The Gain Tuner always opens on Gain Settings, so click Test Gains whenever a step calls for a test control.

Note

The module_4_end checkpoint already configures finger-joint stiffness and damping. This tutorial tunes and verifies right_thumb_1_joint and right_thumb_2_joint.

Tuning guidelines

1. Set damping to zero and tune stiffness to observe the initial response.

2. Increase stiffness until the joint converges near the target.

3. Set damping approximately one order of magnitude below stiffness as a starting point.

4. Fine-tune both values for stability, response time, and overshoot.

Run a step-function test

1. On the Gain Settings tab, in the Stiffness / Kp column, set an initial value of 0.001 for right_thumb_1_joint and right_thumb_2_joint. The column header also names the unit the active backend uses: degrees under PhysX and radians under Newton.

2. Click the Test Gains tab and set Test Mode to Step Function. The Gain Tuner opens on Snap to Limits, and the Test Duration (s) field appears only after you switch to Step Function or Sinusoidal.

3. In Test Gains Settings, select Test only for these two thumb joints.

4. Set Step Max to 60 degrees for right_thumb_1_joint and 20 degrees for right_thumb_2_joint. Set Period to 2.0 seconds for both joints and Test Duration (s) to 6.0, so each joint runs three full step cycles and you can see whether its response repeats.

Note

The period has to leave each joint time to arrive and settle. right_thumb_1_joint is capped at 107 degrees per second by its Max Joint Velocity, so a 60 degree step needs roughly 0.6 seconds of travel. At the default 1.0 second period the command reverses before the joint lands, and the response never shows the overshoot the next section asks you to tune out.

5. Click Run Test. The Gain Tuner starts the timeline itself if the simulation is not already playing.

Analyze the results

The Charts section of the Test Gains tab plots each tested joint’s commanded and measured Position, which reveals overshoot, lag, and coupling between joints. An Effort (Nm) chart appears beside it when the active backend reports measured joint forces; the Newton backend does not report them, so under Newton you see the Position chart alone.

1. When the test completes, select right_thumb_1_joint and right_thumb_2_joint in the joint list to the left of the charts. Hold Ctrl and click to select both. Each joint carries a color that matches its chart traces.

Note

Overshoot reads 0.0 % here even though right_thumb_1_joint plainly overshoots. The metric compares only the first and last commanded sample and treats what lies between as a single step, which a repeated square wave defeats: it ends up measuring the descent back to zero rather than the rise past 60 degrees. Read overshoot off the chart rather than out of that field.

2. If the first thumb joint oscillates and the second struggles to reach its target, return to Gain Settings and set damping to 0.0001 and stiffness to 0.007 for both thumb joints. Click Run Test once more, then come back to Gain Settings: the detail panel below the table reports that run’s results beside the gains that produced them.

3. Back on the Test Gains tab, set Sequence to 1 for both joints so they run in parallel. Set Step Min to 0.0 and Step Max to 15 for right_thumb_2_joint.

4. Click Run Test again, then select both thumb joints in the joint list to compare the response. The added damping removes the ringing, and both joints now climb to their targets and hold them.

Note

Judge this change by the shape of the trace, because neither reported number separates a ringing response from a settled one. Peak Error is measured at the instant the command steps, before the joint has had time to move, so it stays pinned near the step magnitude no matter how well the joint tracks afterward: 59.985 degrees against a 60 degree step in every run above. RMS Error averages over the whole recorded run, including the sequences in which a joint is not being driven, so the two-sequence run records twelve seconds and drives each thumb joint for only half of them, while the parallel run records six and drives both throughout. The gains are identical in the two runs, yet right_thumb_1_joint reports 18.028 degrees in the first and 25.480 in the second, a factor of the square root of two that is the change in averaging window and nothing else. Compare RMS Error only between runs that share the same sequencing.

Validate the tuned hand

Continue adjusting stiffness, damping, and test parameters until the thumb tracks the target with little or no overshoot. Use the following additional Test Mode entries to validate the tuned hand:

• Snap to Limits commands each joint to its lower limit, holds the target, then commands its upper limit. Use it to verify full-range tracking and consistency between limits, gains, and collision geometry.

• Stress drives joints with extreme random commands and reports them in a Stress Test Results table. Run it after the step-function test passes to expose solver instabilities that can occur during aggressive exploration, such as reinforcement learning.

1. In Test Mode, select Snap to Limits, then click Run Test. Choosing this mode replaces the step-function fields with Hold Duration and Tolerance.

2. Read the result before changing anything. The run above diverged rather than failed to track: the upper-limit columns report nan and the Effort chart peaks in the hundreds of thousands of newton metres, which is the hand exploding as the thumb curls into contact. Select PhysicsScene in the Stage panel and set Scene > Time Steps Per Second to 120 to give the solver smaller steps through that contact.

3. Run the Snap to Limits test again. The divergence is gone: efforts stay in the hundredths of a newton metre, and right_thumb_1_joint now passes both limits.

Note

The higher rate addressed the divergence, not the SOME JOINTS BLOCKED verdict that replaced it. BLOCKED reports a joint that stalled short of a commanded limit with its velocity near zero, which points at a self-collision or another physical constraint rather than at its gains, and the ALL GAINS OK beside it is the Gain Tuner saying the drives themselves tracked acceptably. right_thumb_2_joint stops 11.34 degrees short of its upper limit and stays there, so what is left after the rate change is a geometry question rather than a tuning one.

To test the whole hand:

1. Enable Test for every joint.

2. Set Sequence to 1 for every joint.

3. Click Run Test.

Use Physics Inspector to command individual joints through their full range:

1. Go to Tools > Physics > Physics Inspector.

2. Select r_base_link as the Articulation.

3. Set drive target positions and observe the response in the viewport.

Set a nonzero stiffness before commanding a target; otherwise, the joint will not respond.

The Gain Tuner offers more than this tutorial uses: Sinusoidal and dt Sweep test modes, per-backend advanced actuator parameters, and a natural-frequency tuning mode. For those, see Gain Tuner Extension.

Save the tuned gains

Editing a gain changes the stage in memory. Save the tuned values before you close the stage, or the tuning is lost.

1. Click the Gain Settings tab.

2. Check the Save Target row below the joint table. It defaults to the neutral payloads/Physics/physics.usda layer, which is where joint gains belong.

3. Click Save.

For the full set of save targets, including MuJoCo mirroring and Newton actuator writeback, see Save Targets and Backend Mirroring.

Note

Open Isaac/Samples/Rigging/Inspire/module_5_end/inspire_hand/inspire_hand.usda in Gain Tuner to review the final tuned stiffness and damping values.

Summary

This tutorial covered:

• Tuning thumb joint stiffness and damping on the Gain Tuner’s Gain Settings tab.

• Running Step Function, Snap to Limits, and Stress tests from the Test Gains tab to diagnose tracking and stability.

• Testing all joints in parallel, saving the tuned gains to a physics layer, and reviewing the final tuned checkpoint.

Next Steps

Continue to Using the dexterous hand in practice to use the tuned hand in downstream workflows.

Back to Gallery View