tune.motion

Replays a reference motion through the same controller teleop uses, and scores tracking accuracy and smoothness for each joint. The gains, feed-forward and damping come from the same config as teleop and the SDK: your panel settings on top of the calibration. The motion is the same on every run, so you can change one gain with --gain, replay, and compare the numbers. The diagnostics dashboard shows the runs as charts, side by side. Every run is saved, with each joint’s full time series and scores, under ~/.almond/diagnostics/tuning/.

Safety

The arm moves to the motion’s start and back to rest on planned paths that avoid collisions.
A contact watchdog stops playback if a joint keeps pushing harder than the plan expects (--torque-threshold).
Before playback the tool checks that the arm reached the start pose. If a joint is more than about 3° off, the tool names it, skips playback and returns the arm to rest.
A tracking guard stops playback if a joint leaves its path, oscillates or vibrates. See Tracking guard.

If an --a4 joint fails the start check, its stored planner acceleration is probably neither 0 nor 60000. Read it with scripts/fw_gains.py --id <id>. Any value in between makes the joint barely move (see tune.a4).

Flag	Description
`--motion NAME`	Saved motion name (`axol motion.list`) or a path to a motion `.npz` file (required)
`--arms both\|left\|right`	Which arms to bring up and drive (default: `both`). The other arm’s bus is left alone, so an unpowered arm or a single-arm bench doesn’t block the run.
`--gain [SIDE.]JOINT.FIELD=VALUE`	Override one gain for this run, for example `left.elbow.kd=4.5`. Repeatable, and without a side it applies to both arms (see Gain fields).
`--stiffness S`	Stiffness-slider position, 0 to 1, for both arms (default: the panel’s, 1.0 unless you changed it). At 1.0, gain overrides apply as given.
`--defaults`	Ignore the panel settings and run the calibrated defaults
`--repeat N`	Replay the motion N times in one session (default: 1; 0 runs until Ctrl-C). Each pass is scored and saved as its own run, and a one-line summary per pass closes the session.
`--hold SIDE.JOINT[=DEG]`	Hold a joint still at the motion’s start angle or at the given angle (repeatable). Only the move to the start is checked for collisions, so watch the first pass.
`--label TEXT`	Note stored on the run
`--torque-threshold NM`	Contact watchdog threshold (default: 8.0; 0 turns it off)
`--no-save-run`	Don’t save the run
`--no-imu`	Skip the wrist IMU. By default each pass gets an `imu` shake score (see below).
`--no-gripper`	Run on an Axol without grippers. The panel’s `axol.has_gripper` setting already covers a robot set up that way.
`--record PREFIX`	Record the session like teleop’s `--teleop.record`: measured joints to `PREFIX_meas.npz` and the realtime core’s trace to `PREFIX_rt.npz`

axol tune.motion --motion reach-and-place                             # baseline run
axol tune.motion --motion reach-and-place --gain left.elbow.kd=4.5    # A/B a gain
axol tune.motion --motion reach-and-place --controller position        # firmware position loops, 400 Hz
axol tune.motion --motion reach-and-place --gain shoulder_3.kd_host=8 --label "s3 damp"
axol tune.motion --motion reach-and-place --noise network             # raw noise, no filters
axol tune.motion --motion reach-and-place --noise network --filter    # same noise, stack on
axol tune.motion --motion reach-and-place --ik                        # IK solver in the loop

Gain fields

--gain accepts these fields:

Impedance and damping: kp, kd, kd_host, kd_host_hz, kd_host_q, j_eff
Friction compensation: stiction_gain, stiction_load_gain, stiction_err_deg, dither_nm, dither_hz, stribeck_gain, stribeck_dfs, stribeck_load_gain, stribeck_vs, stribeck_pole, and the friction model as friction.fc, friction.k, friction.fv, friction.fo, friction.fl
Firmware position loop: firmware.position_kp, firmware.position_ki, firmware.position_kd, firmware.speed_kp, firmware.speed_ki, firmware.profile_acc
MyActuator 0xA4 planner: firmware.planner_accel (0 or 60000), firmware.cap_track (1 or more, for example 1.2) and firmware.planner_lead_ms
Torque feed-forward: firmware.tf_rated_current_a, in amps, for MyActuator a4 joints on V4.4 firmware
Gravity model: mass (kg) and com.x, com.y, com.z (m, in the link’s URDF frame), to try a gravity correction before you calibrate it

Firmware gains are written to the motor’s ROM when the joint enables, so they stay in the motor after the run. The next run without the override sets the planner back to 0.

Noise, filters and IK

Flag	Description
`--noise MODE`	Add noise to the motion where it would enter on the robot: `network`, `ik`, `combined` or `none` (default). See `tune.filter`.
`--filter`	Pass the stream through teleop’s filters before sending it. This is the hardware version of `tune.filter`.
`--ik`	Re-solve each waypoint through the IK solver, as teleop does, and drive the arms with the solver’s output. Solve times and the difference from the reference are saved on the run.
`--seed N`	Noise seed. The same seed gives the same noisy stream (default: 0).

With any of these, the run is still scored against the clean motion. The saved run also stores the stream that was sent, so the dashboard can overlay the clean, sent and measured positions for each joint. --ik solves the whole motion before playback starts, so slow solves don’t change the playback timing.

Controllers and rates

Flag	Description
`--controller impedance\|position`	`impedance` (default) runs the production controller at 240 Hz. `position` runs every joint on its motor’s position loop at 400 Hz, which is stiff and has no host feed-forward.
`--a4 SIDE.JOINT`	Run one MyActuator joint on its firmware position loop (0xA4), for example `right.shoulder_1`, while the rest stay on impedance. The joint has no compliance and its torque reads as NaN.
`--loop-hz HZ`	Realtime-core tick rate (default: 240 for impedance, 400 for `position`, 480 when `--a4` joints are mixed in). With any joint on impedance, only 240 or 480 is accepted.
`--impedance-hz 240\|480`	Command rate of the MyActuator impedance joints (default: 240). The gains were tuned at 240, and the Damiao wrists stay at 240.
`--fast-impedance SIDE.JOINT`	Run one impedance joint at 480 Hz while the others stay at 240 Hz. Repeatable.
`--enc2 SIDE.JOINT`	Record a MyActuator joint’s output-side encoder in the core trace (`enc2_p` and `enc2_t` in `PREFIX_rt.npz`). Implies `--record`.

Learning and pre-compensation

Flag	Description
`--learn N`	Learn a correction over N passes, in place of `--repeat`. See below.
`--learn-imu`	With `--learn`: learn from the tool’s vertical deviation as the wrist IMU measures it, which includes flex the joint encoders can’t see. Needs one driven arm and its wrist camera.
`--learn-gain G`	Step size of each update (default: 0.7). 0.9 converges faster when passes repeat closely.
`--learn-band LO HI`	Band the learning corrects, Hz (default: `0.7 8`)
`--learn-max-deg D`	Largest offset per joint, degrees (default: 1.5)
`--learn-joint SIDE.JOINT`	Learn only these joints. Repeatable (default: every driven joint that moves at least 1° and isn’t held).
`--correction RUN_ID`	Replay with the offset a `--learn` pass saved, without learning, to check that it holds up
`--invert`	Pre-compensate the motion with each joint’s tracking model from `tune.tf`, so lag and resonance cancel. Joints without a model stream unchanged.
`--notch HZ`	Notch the streamed motion at `HZ` with teleop’s command notch (`VRTeleopConfig.command_notch_hz`), for shake the joint loops can’t damp. Repeatable.
`--notch-q Q`	Quality factor of those notches (default: 2.0). Bandwidth is `HZ` divided by Q.

With --learn, pass 1 runs uncorrected. After each pass, each joint gets a position offset that cancels its tracking error in --learn-band. A pass that comes out worse goes back to the best offset at half the gain. A learned offset belongs to the motion it was learned on. It shows how much each joint needed, which is the most a feed-forward model could achieve.

Tracking guard

By default the guard watches every driven joint’s tracking error and stops playback when a joint:

Trips when	Flag	Default
Leaves its path by more than the limit, plus 0.1 s of the commanded speed	`--guard-dev-deg`	10°
Oscillates: 1.5–15 Hz error RMS above the limit	`--guard-osc-deg`	1.5°
Vibrates: >15 Hz error RMS above the limit	`--guard-vib-deg`	0.15°

When the guard trips, the run’s gain overrides go back to the base config, the arm holds still for 1.5 s, then returns to rest. The moves to and from the motion get twice the limits. If the return trips twice, the arm stays powered and holds its last command. Trips are saved with the run, and the command exits with status 3. For slow creep motions, tighten the limits, for example --guard-dev-deg 4 --guard-osc-deg 1. Pass --no-guard to turn the guard off.

Research flags

These flags are research tools and are not part of the production controller. Damping from the wrist camera’s IMU can add high-frequency oscillation, and its effect depends on how the camera is mounted on the wrist.

Flag	Description
`--imu-damp C`	Damp the tool’s vertical shake with a force of −C times the shake velocity the wrist IMU measures, in N·s/m. Start at 5.
`--imu-damp-joint SIDE.JOINT[=SCALE]`	Joints that apply the damping, each with an optional scale. Repeatable (default: `shoulder_1`, `shoulder_2` and `elbow`).
`--imu-damp-joint-lp SIDE.JOINT=HZ`	Low-pass one joint’s damping torque. Repeatable.
`--imu-damp-ref encoder\|command\|model`	What the tool’s velocity is measured against: the encoders (default, flex past the joints only), the command (any departure from the path), or the `tune.tf` tracking model (ignores normal lag).
`--imu-damp-source imu\|encoder`	Measure the tool’s velocity with the wrist IMU (default) or from the joint encoders
`--imu-damp-lp HZ`	Upper edge of the damped band (default: 15)
`--imu-damp-hp HZ`	Lower edge of the damped band (default: 1.0). Below about twice this, the force acts more like a spring than a damper.
`--imu-damp-lead HZ`	Center of a lead-lag stage (default: 0, none)
`--imu-damp-notch HZ`	Notch the damping force (default: 0, none)
`--imu-damp-notch-q Q`	Quality factor of that notch (default: 1.0)
`--imu-damp-max NM`	Largest damping torque per joint (default: 0.5)
`--imu-damp-alternate`	Damp on passes 2, 4 and so on only, to compare within one session
`--gyro-damp C`	Damp flex past the joints from the wrist gyro, in N·m·s/rad. Needs `--gyro-mount`.
`--gyro-damp-joint SIDE.JOINT[=C]`	Joints that apply gyro damping, each with an optional gain. Repeatable (default: `shoulder_1` and `elbow`).
`--gyro-mount PATH`	The wrist cameras’ rotation relative to the gripper mount (default: `~/.almond/wrist_imu_mount.json`)
`--gyro-mount-fit RUN_ID`	Fit that rotation from a saved run with the IMU recorded, write it to `--gyro-mount`, and exit
`--torque-probe SIDE.JOINT=NM`	Add a known 0.5–15 Hz torque, up to NM peak, to a joint, to measure how joint torque moves the tool. Repeatable.

Reading the scorecard

Column	Meaning
`RMS °`	Tracking error against the reference
`lagfree °`	Error with the measured delay removed. This separates slowness from inaccuracy.
`lag ms`	Delay from command to measured motion
`jitter °`	3–15 Hz error RMS, the vibration the operator feels
`amp`	Measured over commanded motion in the middle band. Above 1 the arm rings, below 1 it filters.
`trq HF`	Torque chatter from one cycle to the next (Nm RMS)
`buzz °` / `@Hz`	Sustained motion at 20 Hz or more, which you hear as buzz, and its frequency. Healthy joints read about 0.005°, and an audible buzz 2 to 5 times that.

Wrist IMU shake

Each pass also prints the shake the wrist camera’s IMU measures at the gripper. It is reported in mm, as the typical peak-to-peak motion over 2 s in the 1–15 Hz band. The score is given overall and along gravity, and the vertical part is split into low_mm (1–3 Hz, slow sway) and high_mm (3–15 Hz). The IMU sees motion the joint encoders can’t, such as gear backlash, link flex and the gripper itself. It is the number that matches a shake you can see at the tool. The saved run stores it as metrics.imu, with the raw samples. Joints that move less than 1° in the motion show - in the tracking columns. They keep their row and are still scored for buzz and torque chatter, which is where a vibration at a held pose shows up.

Get Started

Operations

Mantis

Remote Teleop

Web Interfaces

Advanced

tune.motion

Safety

Gain fields

Noise, filters and IK

Controllers and rates

Learning and pre-compensation

Tracking guard

Research flags

Reading the scorecard

Wrist IMU shake

​Safety

​Gain fields

​Noise, filters and IK

​Controllers and rates

​Learning and pre-compensation

​Tracking guard

​Research flags

​Reading the scorecard

​Wrist IMU shake

Safety

Gain fields

Noise, filters and IK

Controllers and rates

Learning and pre-compensation

Tracking guard

Research flags

Reading the scorecard

Wrist IMU shake