Moving a Robot in Joint Space

A point-to-point (PTP) motion is a movement where the robot travels to a target configuration by following the shortest path in joint space. The motion is therefore the quickest possible, but the resulting end effector path in Cartesian space can be unpredictable.

This chapter specifically explains PTP movements. For detailed information on how to use these methods synchronously or asynchronously, see the asynchronous instructions chapter.

Performing a PTP Movement

Performing a PTP movement can be done using the method move_ptp(), which requires a target pose of either type JointPose or CartesianPose.

Note

The CartesianPose is interpreted in the world coordinate system. No specific tool is assumed. The behavior depends on the specific robot in use.

A CartesianPose itself can be ambiguous in regards to the exact joint configuration of the robot. It is at the discretion of the underlying robot control to choose a convenient joint configuration to reach the given pose. This means, that the robot configuration reached depends on the starting position.

The speed argument defines the general speed for the motion in regard to the possible maximum joint speed. Its input parameter has to be of either the custom data type Factor, which ranges between 0.0 and 1.0, or of type Percent, which ranges between 0.0% and 100.0%. Giving no argument results in a Factor of 1, which reflects the maximum speed.

Perform a PTP Movement using a JointPose

To perform a PTP movement to a target defined in joint space, use a JointPose as an input target argument:

robot.move_ptp(HOME, speed=Factor(0.25)).result()
robot.move_ptp(VERTICAL, speed=Percent(100)).result()

Perform a PTP Movement using a CartesianPose

To perform a PTP movement to a target defined in Cartesian space, use a CartesianPose as an input target argument:

vertical_c = CartesianPose().from_list(
    [0.1382, 0.550, 0.296, 3.14159, 0.0, 0.0]
)
robot.move_ptp(vertical_c, speed=Percent(100)).result()

Since a Cartesian pose is ambiguous for a six axis robot, the resulting joint configuration at the target can differ depending on the starting pose of the robot.

Perform a PTP Movement with Blending

PTP movements can use blending by supplying a Factor or Percent input to the blending argument. The higher the blending factor, the more and earlier the blended path will deviate from the original path that would reach the target pose. In most cases this allows the robot to maintain a higher path velocity and complete the overall path faster.

The exact behavior and interpretation of the blending parameter as well as implicit limitations are highly dependent on the specific robot used.

To use blending, add a blending input argument to the method. Blending only works, if the instructions used for blending are known to robot control in advance. As such, it is not possible to blend two instructions, which are synced to the Python interpreter. For more details on how to use and how not to use the blending functionality, please refer to the asynchronous instructions chapter. Here is a simple example of how to use blending:

# Pose BLENDING_1 and BLENDING_2 will be blended
robot.move_ptp(BLENDING_1, blending=Percent(50))
robot.move_ptp(BLENDING_2, blending=Factor(0.5))
# Pose BLENDING_3 will be reached
robot.move_ptp(BLENDING_3).result()

Note how the .result(), which syncs the instruction to the Python interpreter, is only used for the last movement instruction which itself does not contain a blending argument.

Amending blending parameters

If your robot supports sending delayed blending parameters, it is possible to amend a blending parameter after sending the motion instruction using the amend_blending_parameters() method.

robot.move_ptp(BLENDING_1)
robot.amend_blending_parameter(blending=Percent(50))
robot.move_ptp(BLENDING_2)
robot.amend_blending_parameter(blending=Factor(0.5))
robot.move_ptp(BLENDING_3).result()

In this example the robot will blend the poses BLENDING_1 and BLENDING_2 just like in the previous example, but the blending parameters are supplied after sending the motion instruction.

Note that amending the parameter too late - i.e. such that the robot already reached the previous target pose - may result in a drop of the blend request by the robot control.

Perform a Relative PTP Movement

For moving the robot relatively to its current pose, use the move_ptp_relative() method. Other than that, the method accepts the same arguments as move_ptp().

In the example below, the robot moves relatively in the positive z-direction from its current pose. The z input argument is a CartesianPose, where every argument is zero except the value of z:

robot.move_ptp_relative(z(0.1), speed=Percent(100)).result()

Full Example of Performing PTP Movements

The following example shows a simple application in which the move_ptp() method is being used:

Using move_ptp() example

"""An example on how to perform PTP movements."""

from math import radians
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    AmendBlendingParametersTrait,
    CartesianPose,
    Factor,
    JointPose,
    MovePTPTrait,
    Percent,
    VorausIndustrialRobotArm,
    configure_logging,
    x,
    y,
    z,
)

VORAUS_CORE_HOST = "localhost"
VORAUS_CORE_PORT = 48401

HOME = JointPose().from_list(
    [radians(d) for d in [0, -90, 90, -90, -90, 0]]
)
HOME_C = CartesianPose().from_list(
    [0.550, -0.1382, 0.4743, -3.14, -0, 1.57]
)

VERTICAL = JointPose().from_list(
    [radians(d) for d in [0, -90, 0, -90, -90, 0]]
)

BLENDING_1 = HOME_C - z(0.2)
BLENDING_2 = BLENDING_1 + y(0.2)
BLENDING_3 = BLENDING_2 - x(0.2)


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


@runtime_checkable
class _AmendBlendingTraits(
    MovePTPTrait, AmendBlendingParametersTrait, Protocol
): ...


def run_simple_ptp_movement_using_a_joint_pose(
    robot: _RequiredRobotTraits,
) -> None:
    """Example of a simple absolute PTP movement using a JointPose."""
    robot.move_ptp(HOME, speed=Factor(0.25)).result()
    robot.move_ptp(VERTICAL, speed=Percent(100)).result()


def run_simple_ptp_movement_using_a_cartesian_pose_absolute(
    robot: _RequiredRobotTraits,
) -> None:
    """Example of a simple absolute PTP movement using a CartesianPose."""
    robot.move_ptp(HOME_C, speed=Factor(0.25)).result()
    vertical_c = CartesianPose().from_list(
        [0.1382, 0.550, 0.296, 3.14159, 0.0, 0.0]
    )
    robot.move_ptp(vertical_c, speed=Percent(100)).result()


def run_simple_ptp_movement_using_a_cartesian_pose_relative(
    robot: _RequiredRobotTraits,
) -> None:
    """Example of a simple relative PTP movement using a CartesianPose."""
    robot.move_ptp(HOME, speed=Factor(0.5)).result()
    robot.move_ptp_relative(z(0.1), speed=Percent(100)).result()


def run_simple_ptp_movement_with_blending(
    robot: _RequiredRobotTraits,
) -> None:
    """Example of a simple PTP instruction block with blending."""
    robot.move_ptp(HOME).result()
    # Pose BLENDING_1 and BLENDING_2 will be blended
    robot.move_ptp(BLENDING_1, blending=Percent(50))
    robot.move_ptp(BLENDING_2, blending=Factor(0.5))
    # Pose BLENDING_3 will be reached
    robot.move_ptp(BLENDING_3).result()


def run_amend_blending_parameters_example(
    robot: _AmendBlendingTraits,
) -> None:
    """Example of amending blending parameters to a motion instruction."""
    robot.move_ptp(HOME).result()
    robot.move_ptp(BLENDING_1)
    robot.amend_blending_parameter(blending=Percent(50))
    robot.move_ptp(BLENDING_2)
    robot.amend_blending_parameter(blending=Factor(0.5))
    robot.move_ptp(BLENDING_3).result()


if __name__ == "__main__":
    configure_logging()

    robot = VorausIndustrialRobotArm()
    with robot.connect(host=VORAUS_CORE_HOST, port=VORAUS_CORE_PORT):
        robot.enable()
        robot.move_ptp(VERTICAL).result()
        run_simple_ptp_movement_using_a_joint_pose(robot)
        run_simple_ptp_movement_using_a_cartesian_pose_absolute(robot)
        run_simple_ptp_movement_using_a_cartesian_pose_relative(robot)
        run_simple_ptp_movement_with_blending(robot)
        run_amend_blending_parameters_example(robot)

Definition of the Move PTP Method

The move PTP method is defined in the MovePTPTrait:

MovePTPTrait

protocol MovePTPTrait

Trait to perform a point-to-point movement of a robot arm.

This protocol is runtime checkable.

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

abstractmethod move_ptp(target, *, speed=None, blending=None)

Instruction that moves the robot to a target pose with a joint space point-to-point motion.

The resulting geometric path of the end effector is not explicitly defined. It results from the given axis limitations for velocity and acceleration.

The CartesianPose is interpreted in the world coordinate system. No specific tool is assumed. The behavior depends on the specific robot in use.

A CartesianPose itself can be ambiguous in regards to the exact joint configuration of the robot. It is at the discretion of the underlying robot control to choose a convenient joint configuration to reach the given pose. This means, that the robot configuration reached depends on the starting position. With this generic interface it is not possible to force a specific robot configuration in Cartesian space. Please use a robot specific trait for this purpose.

The speed argument defines the general speed for the motion in regards to the possible maximum joint speed. Giving no argument results in a Factor of 1, which reflects the maximum speed.

If blending is activated, the given target pose will not be reached exactly. The higher the blending factor, the more and earlier the blended path will deviate from the original path that would reach the target pose. In most cases this allows the robot to maintain a higher path velocity and complete the overall path faster.

The exact behavior and interpretation of the blending parameter as well as implicit limitations are highly dependent on the specific robot used.

Blending only works, if this instruction is not synchronized to the Python interpreter and the next instruction is received prior to the execution of this instruction. Otherwise, the robot will hold at the starting point of this instruction. If in that case the instruction leading to the starting point of this instruction also contained a blending parameter, the blending parameter of the previous instruction will be ignored. As a result, the previous instruction will not be blended

Parameters:

  • target (JointPose | CartesianPose) – The target pose of the desired motion.

  • speed (Factor | Percent | None) – General speed for the motion in regards to the possible maximum joint speed. Defaults to Factor(1).

  • blending (Factor | Percent | None) – Blending with next instruction in percent or as factor. Only works if this instruction is not synchronized to the Python interpreter.

Return type:

Future

Returns:

A Future to track the state of this operation.

abstractmethod move_ptp_relative(target, *, speed=None, blending=None)

Instruction that moves the robot to a relative target pose with a joint space point-to-point motion.

Please see move_ptp for a detailed description of parameter options.

Return type:

Future

Returns:

A Future to track the state of this operation.

The methods to amend blending parameters are defined in the AmendBlendingParametersTrait:

AmendBlendingParametersTrait

protocol AmendBlendingParametersTrait

Trait to amend blending parameters retroactively.

This protocol is runtime checkable.

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

abstractmethod amend_blending_parameter(blending)

Amend blending parameters retroactively to the previous movement instruction.

Calling this without a movement instruction does nothing. It is not possible to amend blending parameters to an instruction that already specified blending parameters. Amending the parameter too late - i.e. such that the robot already reached the previous end position - may result in a drop of the blend request by the robot control.

Parameters:

blending (Factor | Percent | Meters) – Blending with next instruction in percent or as factor.

Return type:

None