Jogging

Jogging instructions move a robot arm in small increments along a desired direction or to a desired pose instead of following a whole path in one go. They require continuous input or confirmation to continue the motion.

Jogging instructions are especially helpful in an HMI application where they are used for maintenance interactions with the robotic system, programming robotic movements as well as debugging them.

Jogging instructions can not be mixed with normal instructions. Each type of instruction can only be processed exclusively at any given time. Issuing normal instructions will raise an error while jogging is active and vice versa.

Note

Jogging features are currently only available for robots of the Victor Robot Behavior Group.

Jogging of a joint

To jog with a single robot joint, the jog_joint_v method can be used. As long as the method is called repeatedly, the robot will keep jogging into the desired direction. Once calls are absent, the axis will decelerate and come to a stop.

Supply the joint index for the joint you want to jog, starting at 0 for the first joint.

The velocity of the movement can be controlled by specifying a maximum velocity in radian per second for rotational joints and meter per second for prismatic joints. By specifying a higher maximum velocity, the speed of the movement can be increased. The velocity also defines the direction of the jogging. A negative velocity moves the robot in the opposite direction.

Furthermore, a maximum acceleration in radian per second squared for rotational joints and meter per second squared for prismatic joints can be specified. The acceleration has to be a positive value. Note that other limits might apply before the provided maximum velocity or maximum acceleration is reached.

future = robot.jog_joint_v(
    joint_index=0,
    velocity=0.5,
    acceleration=0.5,
)

Similar to other instructions, you can call result() to synchronize with the Python interpreter. A jogging future is done when the jogging movement is finished, that means when the robot does not move anymore.

future.result()

To keep the motion alive, refresh the jogging instruction by periodically calling the jog_joint_v method again. Calling the method should have a cool down period as calling without throttling causes undesired side effects and will therefore raise an error. The example below jogs the robot for a specified duration by continuously refreshing the jogging instruction using a while loop. Note that all jogging futures of the loop are only done when the last jogging instruction is finished.

while time.time() - start_time < duration_s:
    future = robot.jog_joint_v(
        joint_index=0,
        velocity=0.5,
        acceleration=0.5,
    )
    time.sleep(throttling_time_s)

Jogging the Tool Center Point in Cartesian Space

To perform jogging in Cartesian space, the jog_tcp_v method can be used. As long as the method is called repeatedly, the tool center point of the robot will keep jogging into the desired direction of the coordinate system specified. Once calls are absent, the axis will decelerate and come to a stop.

Supply the coordinate system in which you want to move, a Cartesian velocity and optionally a Cartesian acceleration magnitude.

The Cartesian velocity describes the maximum velocity in each direction of the coordinate system in meter per second for the translational and in radian per second for the rotational velocities. Its possible to specify a single direction as well as multiple directions for this argument. Its also possible to jog into the opposite direction by specifying negative velocities.

The Cartesian acceleration magnitude describes the maximum acceleration for the translation in meter per second squared and the rotation in radian per second squared of the movement. A Cartesian acceleration magnitude should be a tuple of positive values. Note that other limits might apply before the provided maximum velocity or maximum acceleration is reached.

future = robot.jog_tcp_v(
    cs=CSVictor.ROBOT,
    velocity=CartesianVelocity(x=0.1, y=0.1),
    acceleration=CartesianAccelerationMagnitude(translational=1.0),
)
time.sleep(throttling_time_s)

future.result()

To jog continuously, refresh the jogging motion by periodically calling the jog_tcp_v method again. Calling the method should have a cool down period as calling without throttling causes undesired side effects and will therefore raise an error. The example below jogs the robot for a specified duration by continuously refreshing the jogging instruction using a while loop. Note that all jogging futures of the loop are only done when the last jogging instruction is finished.

while time.time() - start_time < duration_s:
    future = robot.jog_tcp_v(
        cs=CSVictor.ROBOT,
        velocity=CartesianVelocity(x=0.1, y=0.1),
        acceleration=CartesianAccelerationMagnitude(translational=1.0),
    )
    time.sleep(throttling_time_s)

Jogging to a Pose

A jogging instruction to a target pose behaves similar to a normal movement like move_ptp() or move_linear().

Use the methods jog_ptp_v() and jog_linear_v() for absolute motions and jog_ptp_relative_v() and jog_linear_relative_v() for relative motions.

The following first example jogs linear to a previously defined pose, while the second example jogs only the first joint by 60°.

jogging_handle = robot.jog_linear_v(HOME)

jogging_handle = robot.jog_ptp_relative_v(JointPose(j1=radians(60)))

The methods return a so called JoggingHandle, which allows to track the state of the jogging operation.

In contrast to the normal movement instructions and similarly to the continuous jogging ones, a keep alive call is required via continue_jogging() of the JoggingHandle to continue the execution. This way, it is guaranteed, that the jogging stops if a user input is removed or the application crashes or loses connection.

jogging_handle = robot.jog_linear_v(HOME)

start_time = time.time()
while (
    time.time() - start_time < duration_s
    and not jogging_handle.is_done()
):
    jogging_handle.continue_jogging()
    time.sleep(throttling_time_s)

jogging_handle.result()

As shown above, the JoggingHandle can furthermore be used similarly to the Future of other instructions to observe the overall result of the operation with result(). The JoggingHandle has a positive result if the desired pose is reached. It will raise if there was an exception, e.g. a robot error. Missing the keep alive call with continue_jogging() will also abort the overall instruction and raise an exception once result() is called.

Calling continue_jogging() should have a cool down period as calling without throttling causes undesired side effects and will therefore raise an error.

Full Example of Performing Jogging

The following example shows a simple application in which the jogging methods are used:

Jogging example

"""A simple example on how to jog a robot arm."""

import time
from math import radians
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    CartesianAccelerationMagnitude,
    CartesianVelocity,
    CSVictor,
    Factor,
    JogJointVictorTrait,
    JogLinearVictorTrait,
    JogPTPVictorTrait,
    JogTcpVictorTrait,
    JointPose,
    MovePTPTrait,
    VorausIndustrialRobotArm,
    configure_logging,
    y,
)

VORAUS_CORE_HOST = "localhost"
VORAUS_CORE_PORT = 48401

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


@runtime_checkable
class _RequiredRobotTraits(
    MovePTPTrait,
    JogJointVictorTrait,
    JogTcpVictorTrait,
    JogPTPVictorTrait,
    JogLinearVictorTrait,
    Protocol,
): ...


def run_jog_joint_example(
    robot: _RequiredRobotTraits,
) -> None:
    """Example showing how to jog a single joint."""
    robot.move_ptp(HOME).result()
    duration_s = 3
    future = None
    throttling_time_s = 0.1

    start_time = time.time()
    while time.time() - start_time < duration_s:
        future = robot.jog_joint_v(
            joint_index=0,
            velocity=0.5,
            acceleration=0.5,
        )
        time.sleep(throttling_time_s)

    if future:
        future.result()


def run_jog_tcp_example(
    robot: _RequiredRobotTraits,
) -> None:
    """Example showing how to jog the x-axis in the robot cs."""
    robot.move_ptp(HOME).result()
    duration_s = 3
    future = None
    throttling_time_s = 0.1

    start_time = time.time()
    # Cartesian jogging
    while time.time() - start_time < duration_s:
        future = robot.jog_tcp_v(
            cs=CSVictor.ROBOT,
            velocity=CartesianVelocity(x=0.1, y=0.1),
            acceleration=CartesianAccelerationMagnitude(translational=1.0),
        )
        time.sleep(throttling_time_s)

    if future:
        future.result()


def run_jog_ptp_example(
    robot: _RequiredRobotTraits,
) -> None:
    """Example showing how to jog a single joint a defined step."""
    robot.move_ptp(HOME).result()
    duration_s = 3
    throttling_time_s = 0.1

    jogging_handle = robot.jog_ptp_relative_v(JointPose(j1=radians(60)))

    start_time = time.time()
    while (
        time.time() - start_time < duration_s
        and not jogging_handle.is_done()
    ):
        jogging_handle.continue_jogging()
        time.sleep(throttling_time_s)

    jogging_handle.result()


def run_jog_linear_example(
    robot: _RequiredRobotTraits,
) -> None:
    """Example how to jog to a known pose."""
    robot.move_ptp(HOME, blending=Factor(1))
    robot.move_ptp_relative(y(-0.2)).result()
    duration_s = 3
    throttling_time_s = 0.1

    jogging_handle = robot.jog_linear_v(HOME)

    start_time = time.time()
    while (
        time.time() - start_time < duration_s
        and not jogging_handle.is_done()
    ):
        jogging_handle.continue_jogging()
        time.sleep(throttling_time_s)

    jogging_handle.result()


if __name__ == "__main__":
    configure_logging()

    robot = VorausIndustrialRobotArm()
    with robot.connect(host=VORAUS_CORE_HOST, port=VORAUS_CORE_PORT):
        robot.enable()
        run_jog_joint_example(robot)
        run_jog_tcp_example(robot)
        run_jog_ptp_example(robot)
        run_jog_linear_example(robot)

Definition of the Jogging Methods

The continuous jogging in joint space is defined in the JogJointVictorTrait:

JogJointVictorTrait

protocol JogJointVictorTrait

Trait to jog a single joint in a continuous manner for a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod jog_joint_v(joint_index, velocity, acceleration=1.25)

Continuous instruction to jog a single joint.

This instruction must be called repeatedly as long as jogging is desired. For a continuous motion, the time between instruction calls must not exceed 150 ms. By doing so, it is guaranteed, that the jogging stops even if the application crashes or loses connection. There should be a cool down period between invocations in order to avoid undesired side effects. A period of 100 ms between calls showed to be effective.

This instruction returns a Future. The Future is done, when the jogging motion is finished e.g. when the robot does not move anymore. Note, that a repeated jogging call will refresh the motion and therefore the previous future is still active. Once the motion is finished, all previous futures of the jogging motion will be set to done.

Parameters:

joint_index (int) – The index of the joint to jog. The first joint has index 0.
velocity (float) – Defines the direction of movement as well as the desired maximum velocity of the joint to jog. A negative velocity moves the joint in the opposite direction. The unit is rad/s for rotational joints and m/s for prismatic joints.
acceleration (float) – The maximum acceleration magnitude of the joint to jog. The unit is rad/s² for rotational joints and m/s² for prismatic joints. Can’t be negative.

Return type:

Future

The continuous jogging in Cartesian space is defined in the JogTcpVictorTrait:

JogTcpVictorTrait

protocol JogTcpVictorTrait

Trait to jog the tool center point in Cartesian space in a continuous manner for a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod jog_tcp_v(velocity, cs=CSVictor.ROBOT, acceleration=None)

Continuous instruction to jog the tool center point in Cartesian space.

The velocity and acceleration arguments are interpreted in relation to the given coordinate system argument. The robot will for example jog in the direction of the x axis of the coordinate system USER1 if cs is set to USER1 and the velocity is set to x > 0 and everything else to 0.

Parameters:

cs (CSVictor) – The desired coordinate system in which the velocity and acceleration for the TCP is interpreted in. Defaults to CSVictor.ROBOT.
velocity (CartesianVelocity) – Defines the direction of movement as well as the maximum desired Cartesian velocity. Arbitrary directions are supported. Negative velocities move the robot into the opposite direction.
acceleration (CartesianAccelerationMagnitude | None) – The maximum jogging acceleration magnitude. If None is given it is the discretion of the underlying robot control to select a suitable value. Can’t be negative.

Return type:

Future

The jogging in joint space is defined in the JogPTPVictorTrait:

JogPTPVictorTrait

protocol JogPTPVictorTrait

Trait to jog via a point-to-point movement of a robot arm with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod jog_ptp_v(target, *, speed=None)

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

In comparison to normal motion instructions, jogging instructions need to be kept alive repeatedly. If the continue method is not called via the JoggingHandle, the robot motion is stopped, even if the target is not reached.

For a continuous motion, the time between continue method calls must not exceed 150 ms. By doing so, it is guaranteed, that the jogging stops even if the application crashes or loses connection. There should be a cool down period between invocations in order to avoid undesired side effects. A period of 100 ms between calls showed to be effective.

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

A CartesianPose is interpreted in the world coordinate system. It is not possible to choose a tool with this instruction, instead the currently configured tool is used. In order to specify which coordinate system your CartesianPose is interpreted in, the CartesianTargetVictor can be used.

The speed argument defines the general speed for the motion in regards to the possible joint speed. Please note, that jogging commands are limited to 0.25 m/s TCP velocity by default and this argument may be reduced implicitly to match the tcp jogging limitation. Giving no argument results in a Factor of 1, which reflects the maximum speed.

Parameters:

target (JointPose | CartesianPose | CartesianTargetVictor) – The target 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).

Return type:

JoggingHandle

Returns:

A JoggingHandle to track the state of this operation.

abstractmethod jog_ptp_relative_v(target, *, speed=None)

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

Please see jog_ptp_v for a detailed description of parameter options.

Return type:: JoggingHandle
Returns:: A JoggingHandle to track the state of this operation.

The jogging in Cartesian space is defined in the JogLinearVictorTrait:

JogLinearVictorTrait

protocol JogLinearVictorTrait

Trait to jog via a linear movement of a robot arm with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod jog_linear_v(target, *, velocity_mps=0.25, extra_parameters=None)

Instruction that jogs the end effector in a straight translational path to a target pose.

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

The velocity_mps argument defines the maximum translational velocity for the tool center point in m/s. Giving no argument results in a velocity of 0.25 m/s. Please note, that jogging commands are limited to 0.25 m/s TCP velocity by default and this argument may be reduced implicitly to match the TCP jogging limitation.

The params data structure allows further detailed customization of the given path.

Parameters:

target (JointPose | CartesianPose | CartesianTargetVictor) – The target pose of the desired motion.
velocity_mps (float) – Maximum translational velocity for the tool center point in m/s. Defaults to 0.25 m/s.
extra_parameters (MoveCartesianVictorParameters | None) – Detailed parameters to configure the motion.

Return type:

JoggingHandle

Returns:

A JoggingHandle to track the state of this operation.

abstractmethod jog_linear_relative_v(target, *, velocity_mps=0.25, extra_parameters=None)

Instruction that jogs the robot end effector in a straight translational path in the Cartesian workspace.

Please see jog_linear_v for a detailed description of parameter options.

Return type:: JoggingHandle
Returns:: A JoggingHandle to track the state of this operation.

Moving a Robot on a Circular Path

Coordinate Systems