GuidesRobot and arm controlTune the joints
Tune the joints live
Change each joint's gains and limits while the robot runs, one joint or all of them, and read back what every joint actually uses.
Each joint's drive runs its own control loops with its own gains and limits. You can change them while a session runs and see the effect at once, then read back from the boards what they actually use. A new session sets the limits and the main gains again from the robot's saved settings; the other settings stay on the drives until they are switched off (What a new session sets).
Tune from the console
Open the Tuning page from the page menu next to the robot's name. It shares the session with Control, so you can switch back and forth while connected.

- Choose the scope with the chips at the top: all for every drive, or one joint of one arm. The header then names the joint, its board, its firmware and its motor preset.
- Type a new value. The field turns into a dashed amber draft and Push changes counts the drafts. Esc drops a draft.
- Click Push changes or press Enter. The console sends the values and then reads them back from the drives.
- A value the drive did not take is marked in red with what the drive runs instead, and the Tuning log records every push and read.
The switches on Adaptive gains, Cogging compensation and Ripple compensation flip on the drive the moment you click them. Read asks every drive for its settings again. The strip at the bottom shows the selected joint's position, velocity and current over the last four seconds, so you see the effect of a change while you make it.
Tune from Python
robot.control.set_actuator_parameters({"kp_angle": 12}) # every joint
robot.control.set_actuator_parameters({"J03-R/kp_angle": 15, # one joint
"J03-R/kd_angle": 0.2})A plain key applies to every joint; "<joint>/<key>" applies to one. The robot applies a change within tens of milliseconds. The drive keeps it until the next session sets that key again, or, for a key a session does not set, until the drive is switched off.
Every session starts each joint at the current limit in the robot's actuators.toml. As the robot ships, that is 8 A for J1 to J3, 5 A for J4 to J6, 4 A for the head and 3 A for the grippers. Raise a limit here when your work needs more torque, a little at a time, and once a value suits you, keep it as in Keep settings for good. Keep in mind that the full torque also needs a supply of full size (250 W or more for one arm, 500 W for the dual arm system).
Current limits come in two sizes, because the three joints nearest the base have bigger motors than the wrist:
robot.control.set_actuator_parameters({"max_current_big": 9.0, # J1 to J3, A (ships at 8)
"max_current_small": 6.0}) # J4 to J6 and the head (5 and 4)
robot.control.set_actuator_parameters({"J02-R/max_current": 9.0}) # one jointmax_current_small sets the head too, so the second line raises it from 4 A to 6 A. These calls reach the arm joints and, on a dual arm system, the head. They never reach the grippers: a gripper's current limit is in the robot's actuators.toml (see Keep settings for good).
Read back what the drives use
params = robot.control.get_actuator_parameters()
params["J03-R"]["kp_angle"] # 15.0
params["J03-R"]["max_current"] # this joint's own limit, A
params["J03-R"]["firmware"] # 2.05
robot.control.get_actuator_parameters(keys=["kp_angle", "max_current"])Nothing is cached: the robot asks the boards, after any change you pushed has landed, so what you read is what they run. Reading only a few keys is faster. A drive with firmware older than 2.04 answers with an error entry instead of values.
What the settings do
The drive runs three loops inside each other: position around velocity around current. The current loop runs at 14 kHz inside the motor controller.
| Group | Keys | What they change |
|---|---|---|
| Limits | max_velocity, max_current, output_ramp, position_filter_amount | how fast the drive may turn, how much current it may use, how quickly its output may change, and how much it smooths incoming targets (0 raw, up to 1) |
| Position PID | kp_angle, ki_angle, kd_angle | stiffness around the target; higher kp_angle tracks tighter but overshoots and buzzes sooner |
| Velocity PID | adaptive_vpid_enabled, adaptive_vpid_p_min, adaptive_vpid_p_max, adaptive_vpid_i_min, adaptive_vpid_i_max, adaptive_vpid_vel_min, adaptive_vpid_vel_max, kp_velocity, ki_velocity, kd_velocity | damping; with adaptive gains on, the drive uses the max gains near standstill for a firm hold and the min gains at speed for smooth motion, blending between the two speeds |
| Current PID | kp_current, ki_current, kd_current | the innermost loop; rarely worth changing |
| Cogging compensation | cogging_enabled, cogging_gain, cogging_max_iq_ff, cogging_fade_start, cogging_fade_end and three finer ones | cancels the motor's magnetic detents at low speed, fading out as speed rises |
| Ripple compensation | ripple_enabled and its gains | cancels torque ripple from the gearbox |
Speeds here are the drive's own, at the motor before the gearbox: max_velocity, the adaptive gains' two speeds and the cogging fade speeds. Divide by 38 for J1 to J3 and by 39 for J4 to J6 to get rad/s at the joint. As the robot ships, a session sets max_velocity to 200 for J1 to J4 and 300 for J5 and J6. The cockpit's Max velocity writes its value times the ratio, never more than these.
The Motor group on the Tuning page is read only: the pole pairs, phase resistance and KV of the drive's motor preset, the torque constant its torque mode uses, its control mode and its firmware.
Tune safely
- Change one thing at a time, and watch the live strip or the telemetry.
- A pushed
max_current,max_current_bigormax_current_smallgoes to the drive as it is, and the torque fraction no longer scales it; a pushedmax_velocityreplaces the speed limit ofrobot.safety. A low torque fraction gives no protection here: raise these a little at a time, with the arm clear. A new session brings the saved limits back. - Settings a session does not set stay on the drives into the next one. Push the old values back, or switch the arm or robot off and on.
- A value that looks ignored may have been clamped by the drive; read it back to see what it runs.
What a new session sets
When a session starts, the robot writes these keys to every drive, from actuators.toml or the robot's defaults:
max_currentandmax_velocityoutput_rampandposition_filter_amountkp_angleandkd_anglecogging_enabledand the sevenadaptive_vpid_keys
It does not write ki_angle, kp_velocity, ki_velocity, kd_velocity, the current loop gains, the other cogging_ keys or the ripple_ keys. A drive runs those at its own values until you push others, and keeps what you pushed until it is switched off; a line for them in actuators.toml has no effect. Torque on and a pushed current limit also set position_filter_amount back to its saved value.
Keep settings for good
Every session sets the keys of What a new session sets from the robot's actuators.toml, so one of those settings you want to keep goes into that file. Where it is depends on the robot:
- An arm on your PC: in the kit folder, in
robot-calibrations/<name>/actuators.toml.<name>is your PC's name in lower case: the SDK made that folder the first time the arm connected. The Robot Console andRobot.connect_local()use it;Arm.connect()with no name does not (The older entry point). - A dual arm system: on the robot's head computer, in
~/repos/core/robot-calibrations/<name>/actuators.toml, where<name>is the name on the robot's card, for example~/repos/core/robot-calibrations/acme-robot-02/actuators.toml. A new name for the robot in your account does not change it. You reach it over SSH (Add SSH keys). Your PC has no copy of it.
The SDK wrote the file with a table for each part of the robot: [classes] holds the numbers the arm joints refer to by name, such as max_current_big = 8 for J1 to J3; [defaults] applies to every joint but the grippers; [joints.J1] to [joints.J6] apply to that joint on both arms; [joints.gripper] to both grippers; and [joints.head] to the head. Change a value on its line in the table that is already there. A table for one arm only, such as [joints.left_J2], is not in the file yet: add it at the end. Never write a table name a second time: the file then does not load, and no session starts. The next session uses the file.
For example, to raise the grippers' current limit to 4 A, change the max_current line of the [joints.gripper] table:
[joints.gripper]
is_big = false
controller_type = "aqldrive"
kp_angle = 20
max_velocity = 400
max_current = 4.0
output_ramp = 5000To keep a higher limit for J1 to J3, change max_current_big in [classes] the same way.