set_payload¶

Runs at once Any mode Homed Takes control

Declare the part the gripper holds: its mass and centre of mass. The robot adds the part to the gripper's own body in its model and rebuilds the model at once, in every mode: gravity compensation, the inertia and Coriolis feedforward, the external torque estimate behind collision detection, and the inertia the freedrive walls push against. A declared part then floats with the arm in freedrive and does not read as a contact. While the estimate starts again, collision detection pauses for 0.1 s.

Call it each time the gripper picks up or lets go of a part; set_payload(0) brings back the gripper alone. latest_status() shows the payload in force in payload (mass, com) shortly after the call returns.

Syntax¶

robot.set_payload(mass_kg, com_m=(0.0, 0.0, 0.0))

Arguments¶

Name	Type	Default	Description
`mass_kg`	`float`	required	The part's mass, in kilograms: from 0 up to the robot XML's `<max_payload_kg>` (0.4 kg on PAR6).
`com_m`	`Sequence[float]`	`(0.0, 0.0, 0.0)`	The part's centre of mass `(x, y, z)`, in metres, in the tool frame: its origin is the tool centre point, and +z points from the flange toward the jaws. At most 0.5 m from that origin. The default puts it at the tool centre point.

Default values¶

0 kg (the gripper alone), set each time the robot software starts.

Returns¶

Any

{"mass": kg, "com": [x, y, z], "max_payload_kg": kg}: the payload asked for, in kilograms and metres, and the robot's maximum.

Examples¶

robot.set_payload(0.2, (0.0, 0.0, 0.03))
robot.set_payload(0)

Further details¶

Warning

Declare what the gripper really holds, and call set_payload(0) once it lets go. In freedrive a declared mass the arm does not carry pushes it up, and an undeclared one lets it sink.

Usage restrictions 5 codes

This command runs at once; it is not queued. The robot accepts it only when it is homed, 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:

[6010] Command not allowed now — the message names the mode or state it needs
[6101] Control held by another client — another client holds control; the message names it
[6016] Payload not accepted — the mass is below 0 or above <max_payload_kg>, a value is not finite, com_m does not hold exactly three numbers, or the centre of mass is more than 0.5 m from the tool centre point
[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
[6026] Refused by RTI — rTI refused the payload. The message says why; the payload in force stays

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

CommandRejected: The robot refused it, for example before homing, with a payload out of bounds (PAYLOAD_LIMIT), or because 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: mass_kg or a value in com_m is not a number. Nothing is sent.
TypeError: mass_kg is None, or com_m is not a sequence. 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_payload", "args": [0.2, [0.0, 0.0, 0.03]]}