Skip to main content

Tuning parameters

The Tuning tab lists the parameters that the running controller declares itself. Switch controllers and the list changes with it. Per-joint parameters are grouped under one name, such as kp[0]–kp[5], and each row shows its allowed range on the right.

A gain has two names: kp[0] and kp.j0 are the same gain.

  • On screen it is always kp[0]. Hover over the name to see the ROS parameter name (kp.j0).
  • Exported files (CSV, JSON) and ros2 param use the ROS parameter name.

The Tuning tab. The kp[0] row has 150 applied and shows "live 150". The kp[1] row has 5000 entered and shows "5000 exceeds max 1000". The other rows show a value, an Apply button and the range 0 – 1000.

Applying a value​

  1. Enter a number. If it differs from the value the controller is using, the field is highlighted and Apply turns on.
  2. Press Apply. On/off parameters apply as soon as you flip the switch.
  3. Read the result on the line under the row.
ResultMeaning
applyingSent, waiting for the reply
✓ live 150The controller took it, and the value read back matches what you sent. Clears after 4 seconds
⚠ live 0.01The controller took it, but the value read back differs from what you sent. Stays on screen
applied · unverifiedThe controller acknowledged it, but Lab could not read it back within 4 seconds. Clears after 4 seconds
✕ reasonRefused or failed. The reason is the controller's own message (such as exceeds max), a communication error, or no reply within 4 seconds

After ✕, Lab reads the value back once.

The read-back findsThen
The controller's value has changedThe field takes that value
The value is unchangedYour entry stays, so you can Apply again
The request timed out, but the value you sent arrived lateThe mark turns to ✓
The controller refused the valueIt stays ✕, even if the controller already had that value

When tuning is locked​

MessageMeaning
Tuning requires TRAJECTORY or BRAKED modeThe robot is in another mode, such as FREEDRIVE. Switch modes (What each mode allows)
Protective stop · tuning lockedA Protective Stop is active. See Protective Stop and Recover
Tuning managed by WIM — locked in this build.This build locks the built-in controller. Plugin controllers you build yourself are never locked

In TRAJECTORY, Apply can still fail with ✕ even when none of these messages shows. The robot driver checks the joint brakes again before it applies a value.

✕ reasonMeaning
… one or more joint brakes are engaged. …A joint brake is engaged. Release all brakes and apply again
… a joint brake is still moving …A joint brake is still engaging or releasing. Apply again when it has finished

In BRAKED, tuning applies even with the brakes engaged.

Good to know​

Write down the original values before you change them

Applied values stay in the controller. Disconnecting does not undo them; only restarting the stack returns the controller to its starting values. There is no save or load and no reset-to-default button.

  • When you reconnect, the result marks clear and the fields refill with the values the controller reported when it started. Values applied since then are not shown, so the fields can differ from what the controller is actually using.
  • A recorded run stores the gains the controller was using. Which values count is described under Gains.