Stop

Stopping the robot’s movement can be useful to react to external events during program execution. When a stop command is sent, the robot decelerates along its current path until it comes to a complete stop. All active and pending instructions are aborted. In contrast to a pause, new instructions cannot be registered, until the stop signal is revoked. A stop overwrites a pause, so after resetting the stop signal the robot is ready to move again, even if it was paused before.

Stopping the Robot’s Movement

To stop the robot, the stop_motion() command must be called, which takes an optional timeout parameter to define the maximum time the robot is given to settle. If no explicit value is defined, it will default to 5 seconds. The stop_motion() method will only return after the robot has come to a stop or will raise an error in case of a failure to stop. It can be sent either in standstill or while the robot is moving:

robot.move_ptp(HOME).result()
robot.move_ptp(VERTICAL)
move_to_zero = robot.move_ptp(ZERO)
wait_some_time()
robot.stop_motion()

Note that the motion instructions to the VERTICAL pose and the ZERO pose are called asynchronously, which allows a stop during movement. The wait_some_time() method is a placeholder, which in this case only waits until the robot starts moving.

After invoking stop_motion() the registration of new motion instructions is blocked and all active and pending instructions are aborted. Sending a new motion instruction or awaiting the future of an aborted instruction causes a RobotArmError:

robot.stop_motion()
wait_some_time()

try:
    robot.move_ptp(HOME)
except RobotArmError:
    _logger.exception(
        "Cannot register new instruction because robot is stopped."
    )
try:
    move_to_zero.result()
except RobotArmError:
    _logger.exception("Instruction was aborted.")

Before sending any new motion instructions, an unstop_motion() command must be called:

robot.unstop_motion()
robot.move_ptp(ZERO).result()

Full Example of Stop and Unstop

The full example on how to stop and unstop a robot is provided below:

Complete Example for Stopping a Robot

"""A simple example on how to stop the robot."""

from logging import Logger, getLogger
from math import radians
from time import sleep
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    JointPose,
    MovePTPTrait,
    RobotArmError,
    StopTrait,
    VorausIndustrialRobotArm,
    configure_logging,
)

_logger: Logger = getLogger(__name__)

VORAUS_CORE_HOST = "localhost"
VORAUS_CORE_PORT = 48401

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


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


def run_my_application(robot: _RequiredRobotTraits) -> None:
    """Example showing how to stop the robot's motion."""
    robot.move_ptp(HOME).result()
    robot.move_ptp(VERTICAL)
    move_to_zero = robot.move_ptp(ZERO)
    wait_some_time()
    robot.stop_motion()
    wait_some_time()

    try:
        robot.move_ptp(HOME)
    except RobotArmError:
        _logger.exception(
            "Cannot register new instruction because robot is stopped."
        )
    try:
        move_to_zero.result()
    except RobotArmError:
        _logger.exception("Instruction was aborted.")
    robot.unstop_motion()
    robot.move_ptp(ZERO).result()


def wait_some_time() -> None:
    """This is a placeholder method to simulate something happening."""
    sleep(1)


if __name__ == "__main__":
    configure_logging()

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

Definition of the Stop and Unstop Methods

The stop and unstop methods are defined in the StopTrait:

StopTrait

protocol StopTrait

Trait to stop the motion of a robot.

This protocol is runtime checkable.

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

abstractmethod stop_motion(timeout_s=5.0)

Stop the robot’s motion.

The robot will decelerate on the planned path until standstill. All instructions will be aborted and it is not possible to register new ones until unstop_motion() is called.

A stop blocks until the robot has settled. Depending on the robot dynamics, this may take some time. If the robot does not stop within the given timeout, a RobotArmError is raised.

Stopping is possible while the robot is paused. In this case, the pause state will be overridden and all queued instructions will be aborted.

This method is thread safe. It is valid to call it from another thread than the instruction issuing thread.

Parameters:: timeout_s (float) – Maximum time in seconds for the robot to stop. Defaults to 5 seconds.
Return type:: None

abstractmethod unstop_motion()

Reset the robot from the stop_motion command.

After a stop, it is necessary to unstop in order to enable the robot to accept motion instructions again.

Return type:: None

Configuration of the Stop Behavior

For certain use cases, it might be necessary to configure the exact behavior of stopping a robot.

Note

Configuration of stop behavior is currently only supported for robots within the Victor Robot Behavior Group.

A stop can be triggered by different sources e.g. safety or user stop. The stop behavior can be configured for each available source independently. Available settings are the overall stop type and the duration until the robot stops.

For robots with Victor behavior, the reaction to the following stop sources can be configured:

class StopSourceVictor(value)

ERROR_STOP = 1: Triggered by robot control errors.

USER_STOP = 2: Triggered by the user commands. E.g. stop, pause, jogging timeout. This stop can only be executed on path.

SS1 = 3: Triggered by safety.

The following stop types are available:

class StopTypeVictor(value)

AXIS_STOP_RAPID = 1: Decelerate each axis individually as quickly as possible to a standstill with maximum acceleration. This stop is not on the planned path.

AXIS_STOP_TIME_BASED = 2: Decelerate all axis so that they come to a standstill after a defined time. This stop is not on the planned path. Depending on the stop time, acceleration limits may be violated.

PATH_STOP_TIME_BASED = 3: Decelerate the robot within a specified time into standstill. This stop is exactly on the planned path. Depending on the stop time, acceleration limits may be violated.

The relevant methods to configure the stop behavior are set_stop_type_v() and set_stop_duration_v(). Both expect the stop source for which the configuration should be applied as first argument The second argument is the desired stop type or the desired stop duration in seconds respectively.

robot.set_stop_type_v(
    StopSourceVictor.SS1, StopTypeVictor.AXIS_STOP_RAPID
)

robot.set_stop_duration_v(
    StopSourceVictor.USER_STOP, stop_duration_s=1.0
)

The currently configured values can be retrieved by using get_stop_type_v() or get_stop_duration_v(). Once again, the relevant stop source must be provided as argument.

robot.get_stop_type_v(StopSourceVictor.USER_STOP)

robot.get_stop_duration_v(StopSourceVictor.USER_STOP)

Note that not every combination of stop source and stop type is supported. Furthermore, the transition time will only be considered if the chosen stop type is time based. The overview table below depicts the possible combinations.

	Stop Source
Stop Type	Error Stop	User Stop	SS1
Axes stop rapid	Duration parameter ignored	Not possible	Duration parameter ignored
Axes stop time based	Duration parameter considered	Not possible	Duration parameter considered
Path stop time based	Duration parameter considered	Duration parameter considered	Duration parameter considered

Full Example of the Configuration of the Stop Behavior

The full example on how to configure the stop behavior is provided below:

Complete Example for Configuring the Stop Behavior

"""A simple example on how configure the stop behavior."""

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

from voraus_robot_arm import (
    JointPose,
    MovePTPTrait,
    StopBehaviorVictorTrait,
    StopSourceVictor,
    StopTrait,
    StopTypeVictor,
    VorausIndustrialRobotArm,
    configure_logging,
)

VORAUS_CORE_HOST = "localhost"
VORAUS_CORE_PORT = 48401

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


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


def run_my_application(robot: _RequiredRobotTraits) -> None:
    """Example showing how to configure and stop the robot's motion."""
    robot.set_stop_type_v(
        StopSourceVictor.SS1, StopTypeVictor.AXIS_STOP_RAPID
    )
    robot.set_stop_type_v(
        StopSourceVictor.ERROR_STOP, StopTypeVictor.AXIS_STOP_TIME_BASED
    )
    robot.set_stop_type_v(
        StopSourceVictor.USER_STOP, StopTypeVictor.PATH_STOP_TIME_BASED
    )
    robot.set_stop_duration_v(
        StopSourceVictor.USER_STOP, stop_duration_s=1.0
    )

    robot.move_ptp(HOME).result()
    robot.move_ptp(VERTICAL)
    sleep(0.1)
    robot.stop_motion()

    # Overwrite the stop duration for all stop sources
    desired_stop_duration_s = 3.0
    for source in list(StopSourceVictor):
        robot.set_stop_duration_v(source, desired_stop_duration_s)

    assert (
        robot.get_stop_type_v(StopSourceVictor.USER_STOP)
        == StopTypeVictor.PATH_STOP_TIME_BASED
    )
    assert (
        robot.get_stop_duration_v(StopSourceVictor.USER_STOP)
        == desired_stop_duration_s
    )

    robot.unstop_motion()
    robot.move_ptp(ZERO).result()


if __name__ == "__main__":
    configure_logging()

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

Definition of the Configure Stop Behavior Methods

The relevant methods for configuring the stop behavior are defined in the StopBehaviorVictorTrait:

StopBehaviorVictorTrait

protocol StopBehaviorVictorTrait

Trait to read and manipulate the stop behavior of a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod set_stop_type_v(stop_source, stop_type)

Set the robot stop method to the desired stop type.

Parameters:

stop_source (StopSourceVictor) – The stop source for which the new stop type is set.
stop_type (StopTypeVictor) – The desired stop type.

Raises:

ValueError – If the stop type is not supported by the stop source.

Return type:

None

abstractmethod get_stop_type_v(stop_source)

Get the currently configured stop type for a given stop source.

Parameters:: stop_source (StopSourceVictor) – The stop source to obtain the stop type for.
Return type:: StopTypeVictor
Returns:: The currently configured stop type for the given stop source.

abstractmethod set_stop_duration_v(stop_source, stop_duration_s)

Set the robot stop duration. This value will only be used for time based stops.

Parameters:

stop_source (StopSourceVictor) – The stop source to set the new stop duration for.
stop_duration_s (float) – The desired duration of the stop operation in seconds. Must be in the range [0.1, 10].

Return type:

None

abstractmethod get_stop_duration_v(stop_source)

Get the currently configured stop duration for a given stop source.

Return type:: float
Returns:: The currently configured stop duration in seconds for the given stop source.

Pause and Continue

Time Override