Payload

A typical task for a robotic arm often involves carrying payloads, which can vary in weight and significantly impact motion control. To address this, many robot control systems offer the option to specify a payload mass offset, ensuring that the system accounts for the payload weight during motion planning. This section provides guidance on how to read and modify the current payload mass offset.

Note

Payloads are currently only supported for robots within the Victor Robot Behavior Group.

Setting a Payload Mass Offset

To configure an additional payload mass the set_payload_v() method must be called, which expects a payload mass in kg as well as the position of the center of mass of the payload expressed in the tool coordinate system.

robot.set_payload_v(
    mass_kg=1.0, center_of_mass=CartesianPose(x=0.1, y=0.1, z=0.1)
)  # Set payload to 1 kg

A method to remove the current offset is available via remove_payload_v(). It will set the payload mass offset to 0 kg and the center of mass to the origin of the tool coordinate system.

robot.remove_payload_v()

Reading the Current Payload Offset

The currently configured payload mass offset can be read by invoking get_payload_mass_v(). It will return the mass in kg. Reading the corresponding center of mass is currently not supported.

_logger.info(robot.get_payload_mass_v())  # Returns 1.0

Full Example of Working with Payloads

The following example shows a simple application in which the payload changes:

Working with payloads example

"""A simple example on how to set a payload of a robot."""

from logging import Logger, getLogger
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    CartesianPose,
    PayloadVictorTrait,
    VorausIndustrialRobotArm,
    configure_logging,
)

_logger: Logger = getLogger(__name__)

VORAUS_CORE_HOST = "localhost"
VORAUS_CORE_PORT = 48401


@runtime_checkable
class _RequiredRobotTraits(PayloadVictorTrait, Protocol): ...


def run_my_application(robot: _RequiredRobotTraits) -> None:
    """Example showing how to set and get the robot's payload."""
    robot.set_payload_v(
        mass_kg=1.0, center_of_mass=CartesianPose(x=0.1, y=0.1, z=0.1)
    )  # Set payload to 1 kg
    _logger.info(robot.get_payload_mass_v())  # Returns 1.0
    robot.remove_payload_v()
    _logger.info(robot.get_payload_mass_v())  # Returns 0.0


if __name__ == "__main__":
    configure_logging()

    robot = VorausIndustrialRobotArm()
    with robot.connect(host=VORAUS_CORE_HOST, port=VORAUS_CORE_PORT):
        run_my_application(robot)

Definition of the Payload Methods

The payload related functionality is defined in the PayloadVictorTrait:

PayloadVictorTrait

protocol PayloadVictorTrait

Trait to set and get the payload for a robot with Victor behavior.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod set_payload_v(mass_kg, center_of_mass)

Set the payload mass of the robot.

This method is only available for robots within the Victor Robot Behavior Group.

Parameters:

mass_kg (float) – Mass of the payload in kg.
center_of_mass (CartesianPose | None) – Center of the payload mass in tool coordinate system. Orientation is ignored.

Return type:

None

abstractmethod get_payload_mass_v()

Get the currently configured payload mass of the robot.

This method is only available for robots within the Victor Robot Behavior Group.

Return type:: float
Returns:: The currently configured payload mass of the robot in kg.

abstractmethod remove_payload_v()

Remove the current payload.

This method is only available for robots within the Victor Robot Behavior Group.

Return type:: None

Resetting Errors

Limits