Set Target Payload
SUMMARY
Set Target Payload configures the payload parameters used by the robot controller's dynamics model. Accurate payload settings improve motion performance, force estimation, and gravity compensation when a tool or workpiece is attached to the flange.
SUPPORTED ROBOTS
This skill is currently supported on Universal Robots only. Calling this method on other robot brands will raise a NotImplementedError.
The Skill
robot.set_target_payload(
mass=1.5,
cog=[0.0, 0.0, 0.05],
inertia=[0.001, 0.001, 0.0005, 0.0, 0.0, 0.0],
)The Code
Example: Set Payload with Full Inertia Tensor
Set the payload mass, center of gravity, and full inertia tensor.
from loguru import logger
from telekinesis.synapse.robots.manipulators import universal_robots
robot_ip = "192.168.1.2" # replace with your robot's IP
robot = universal_robots.UniversalRobotsUR10E()
# Connect
robot.connect(ip=robot_ip)
mass = 1.5
cog = [0.0, 0.0, 0.05]
inertia = [0.001, 0.001, 0.0005, 0.0, 0.0, 0.0]
robot.set_target_payload(mass=mass, cog=cog, inertia=inertia)
logger.success(
f"Target payload set: mass={mass} kg, CoG={cog} m, inertia={inertia} kg·m²"
)
# Disconnect
robot.disconnect()The Explanation of the Code
set_target_payload updates the controller's dynamics model with the given payload parameters. mass is the total payload mass [kg], cog is the 3-element center of gravity [x, y, z] expressed in the tool frame [m], and inertia is the 6-element symmetric inertia tensor [Ixx, Iyy, Izz, Ixy, Ixz, Iyz] [kg·m²]. Providing accurate values reduces joint tracking error and improves force/torque estimation. Returns True on success.
How to Tune the Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
mass | float | — | Total payload mass [kg]. |
cog | list[float] | [] | 3-element center of gravity [x, y, z] in the tool frame [m]. Empty list uses origin. |
inertia | list[float] | [] | 6-element symmetric inertia tensor [Ixx, Iyy, Izz, Ixy, Ixz, Iyz] [kg·m²]. Empty list uses zeros. |
Return Value
| Type | Description |
|---|---|
bool | True if the payload was accepted by the controller, False otherwise. |
Where to Use the Skill
- Tool change — Update payload after swapping end-effectors
- Pick-and-place — Set the combined tool + object mass after a successful grasp
- Force-control accuracy — Provide accurate inertia for better torque estimation
When Not to Use the Skill
Do not use Set Target Payload when:
- No payload is attached — the default zero payload is correct for an unloaded flange
- Reading current payload — use Get Payload to read the currently configured mass