Skip to main content
Tests one or more Kp/Kd pairs on a single joint. Pass several values to --kp or --kd to test every combination in one session. The tool measures tracking error (RMS, max, overshoot, settling time), ranks the candidates, and can save the best one to this robot’s calibration file. You can also run it from the diagnostics dashboard (axol serve).

​
Feed-forward

By default the test applies the same feed-forward as teleop: gravity, friction, inertia (j_eff) and host damping (kd_host). Gains you find here carry over to teleop unchanged.
  • --ff tests with less feed-forward. For example, --ff none runs bare PD, and --ff friction shows the joint without gravity compensation.
  • --host-kd overrides the host damping. The shoulders need host damping, because the motor’s own kd alone leaves them ringing at about 2 Hz.

​
Other joints

During each test the other joints hold their rest pose under impedance control, with gravity fed forward. The tool checks that they stayed put. Each candidate’s report ends with a Holder peak line that shows how far each held joint moved. If a held joint moved more than about 0.5°, the arm was flexing, and part of the measured ringing comes from that joint and not the one under test.

​
Testing in the worst pose

Gains that are stable with the arm hanging at rest can ring under gravity load or with the arm extended. Test the worst case too.
  • --center: run the test at other angles, such as 45 and −45. shoulder_2 may start at 0 but must swing outboard, because the base is inboard. wrist_2 runs with the elbow raised to its midpoint, which keeps the gripper clear of the base.
  • --pose: hold other joints in a pose, for example --pose elbow=90 --pose wrist_1=45. In the dashboard, enter them in one field separated by spaces. Posed joints return to where they were after the test. shoulder_2 may only be posed outboard. wrist_2 may only be posed in its inboard half if the pose also bends the elbow at least 30°.
  • --pose-by-hand: the arm floats in gravity compensation so you can move it by hand. Press Enter to hold the pose, and the tool runs a step test with every candidate. Compare the ring frequency across poses. The pose with the lowest ring frequency has the least damping margin. It needs --mode step and can’t be combined with --center, --pose or --save.

​
Host damping band

At the default Q of 0.8, the damping band reaches an octave either side of its center. With a low center, it reaches into the slow, intentional motion below 1.5 Hz, drags the final approach, and the step never settles. Once you know the ring frequency, set --host-kd-hz to it and use a Q of 2 to 3, so only the ringing is damped.

​
Per-robot calibration

--save writes the best gains to ~/.almond/calibration.json. Every operation on this computer (teleop, data collection, policies) then uses them in place of the built-in defaults. Explicit overrides still take priority, such as --axol.left.elbow.kp 60 or the panel’s Advanced settings. Saved gains apply at full stiffness (stiffness slider at 1, the default), like the defaults they replace. Friction values from tune.friction --save live in the same file.