Set Payload
SUMMARY
Set Payload writes the payload mass (kg) and optional center-of-gravity offset (m) to the robot controller. These values affect force/torque compensation, safety limit calculations, and the dynamics model used for force-control modes.
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_payload(mass=2.0, cog=[0.0, 0.0, 0.05])The Code
Example: Set a 2 kg Payload with Center of Gravity Offset
Configure a 2 kg tool with its CoG 5 cm along the flange Z axis, then verify by reading back.
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 = 2.0
cog = [0.0, 0.0, 0.05]
robot.set_payload(mass=mass, cog=cog)
logger.success(f"Payload set: mass={mass} kg, CoG={cog} m")
actual_mass = robot.get_payload()
actual_cog = robot.get_payload_cog()
logger.info(f"Readback — mass: {actual_mass} kg, CoG: {actual_cog} m")
# Disconnect
robot.disconnect()The Explanation of the Code
set_payload writes the payload configuration to the robot controller (equivalent to Installation → Payload on the teach pendant). mass is in kilograms. cog is the 3D offset of the payload's center of gravity from the tool flange, in meters. An incorrect payload configuration degrades force-control accuracy and may trigger false safety stops.
How to Tune the Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
mass | float | — | Payload mass in kg. Must be ≥ 0. |
cog | list[float] | [] | CoG offset [CoGx, CoGy, CoGz] in meters from the tool mount. |
Return Value
| Return Type | Description |
|---|---|
None | Returns after the payload is written to the controller. |
Where to Use the Skill
- Set at robot startup whenever the mounted tool changes.
- Required before using force-control skills to ensure accurate wrench compensation.
When Not to Use the Skill
Use read-back methods to verify without changing:
- Use Get Payload and Get Payload Center of Gravity to verify the currently active configuration without changing it.