set_pid_gains¶

Runs at once Any mode Takes control

Set the control gains and limits of one joint's drive. The robot stores the values given and at once sends that drive its whole configuration again: its watchdog, its current, velocity and voltage limits and every gain. Values not named keep theirs. Joints count from 0 here, unlike in free_joint() and joint_test(). The values last until the robot software restarts; nothing is saved to the robot's configuration.

Syntax¶

robot.set_pid_gains(joint, **gains)

Arguments¶

Name	Type	Default	Description
`joint`	`int`	required	The drive: 0 for J1 up to the number of joints minus 1 (5 for J6 on PAR6). The gripper's drive cannot be set this way.
`**gains`	`float`	`{}`	The values to set, in the drive's own units as in the robot's configuration: `KPP` (the position loop's proportional gain), `KPV` and `KIV` (the velocity loop's proportional and integral gains), `KPIQ` and `KIIQ` (the current loop's), `KP` and `KD` (the stiffness and damping of the drive's impedance controller), `Ilim` (the current limit, in milliamperes), `vel_lim` (the motor's velocity limit, in encoder ticks per second) and `vlim` (the voltage limit, in millivolts: 0 uses the supply voltage, and any other value below 6000 mV is raised to 6000 mV).

Default values¶

From the robot's configuration file (robots/<robot>.xml), read each time the robot software starts. PAR6's J1, for example: KPP 88, KPV 0.078, KIV 0.00012, KPIQ 1.5, KIIQ 0.1, KP 0.12, KD 0.002, Ilim 2400 mA, vel_lim 88000 ticks/s, vlim 6000 mV.

Returns¶

Any

None: the robot sends no data back.

Examples¶

robot.set_pid_gains(0, KPP=88, KPV=0.078)

Further details¶

Warning

A gain can make the joint oscillate or run away, and a low Ilim lets it sag or fall. Change gains with the arm at rest and a hand on the E-stop.

Usage restrictions 4 codes

This command runs at once; it is not queued. The robot accepts it in any mode and state, from the client that holds control or when no client does.

It answers with one of these codes when it does not carry the command out:

[6101] Control held by another client — another client holds control; the message names it
[6003] Invalid arguments — joint is out of range, a gain's name is unknown, a value is not a finite number, a gain is negative, Ilim or vel_lim is not above 0 or is above that joint's limit in the robot's configuration, or no gain is given
[6010] Command not allowed now — the robot is homing, or the Hall sensor check, a freed joint or a joint test runs: each relies on the joint's current limit, which this command sets
[6025] RTI not running or not answering — rTI did not answer within 1 s: it is not running or not responding. The command may still have taken effect

In Python, a code above raises CommandRejected; its number is the code. The call raises:

CommandRejected: The robot refused it: a value is wrong, homing or a test runs (see Errors), or another client holds control. Or RTI refused it or did not answer within 1 s (Errors:).
RobotTimeout: The robot did not answer within 5 s.
RobotConnectionError: The client is not connected.
ValueError: joint is not a whole number, or a gain is not a number. Nothing is sent.
TypeError: joint or a gain is None. Nothing is sent.

If the connection drops while the call waits for the robot's answer, it raises CommandRejected with the code CONNECTION_LOST (DISCONNECTED after disconnect()); while it waits for the robot's status, RobotConnectionError.

Like every immediate command, it also answers BAD_ARGS when a raw client sends a value the robot cannot read at all, and INTERNAL when it fails inside the robot.

Protocol¶

A client that does not use robotclient sends this over the TCP command protocol (port 29000) for the example above:

{"id": "c1", "cmd": "set_pid_gains", "args": ["joint", "KPP", "KPV"]}