Errors

When the robot control detects a failure, it enters the error state. The robot stops, all active and pending instructions are aborted and no new instructions are accepted until the error is reset. The failure can originate from the robot control itself, for example a safety violation, or it can be reported by the application.

This page covers how to set the robot control to the error state and how to reset it.

Setting an External Error

Note

Setting external errors is currently only supported for robots within the Victor Robot Behavior Group.

An application can put the robot control into the error state itself. This is useful when the application detects a failure the robot control cannot see, for example a fault in a connected device.

Warning

The error reaction depends on the robot in use. An error set during a movement may trigger a quick stop. Be careful when setting an error from your application.

To set an external error, call set_external_error_v() with the source of the error and a message. Both are shown in the error message of the robot control:

robot.set_external_error_v(
    source="Application", message="External error triggered!"
)

This method blocks until the robot control reports the error state. The optional timeout_s parameter defines the maximum time to wait and defaults to 5 seconds.

Resetting Errors

Warning

As this is a safety-critical task, there may be certain restrictions that apply. Be very careful with the programmatic resetting of errors.

The reset procedure depends on the robot arm in use and on the overall system the robot arm is part of. The robot control may not be able or authorized to reset an error itself. On the voraus.core, for example, the error state is shared across multiple subsystems and must be cleared through a dedicated error handler.

Resetting Errors on the voraus.core

Although the communication with the voraus error handler falls outside the scope of this library, the VorausErrorHandler class is provided for convenience. Its connect() method expects the host (IP address or hostname) and port of the voraus error handler OPC UA server. Use it as a context manager to ensure that the connection is closed upon shutdown:

error_handler = VorausErrorHandler()
with (
    robot.connect(VORAUS_CORE_HOST, VORAUS_ROBOT_CONTROL_PORT),
    error_handler.connect(VORAUS_CORE_HOST, VORAUS_ERROR_HANDLER_PORT),
):

Once connected, call reset_error() with the robot instance whose error should be reset. The method blocks until the robot reports that the error is reset and raises an exception otherwise. The optional timeout can be provided as an argument:

error_handler.reset_error(robot)
assert robot.get_lifecycle_state() == LifecycleState.CONNECTED

Full Example of Setting and Resetting an Error

The full example on how to set and reset an external error is provided below:

Complete Example for Setting and Resetting an Error

"""A simple example on how to put the robot control into an error state."""

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

from voraus_robot_arm import (
    LifecycleState,
    LifecycleTrait,
    SetExternalErrorVictorTrait,
    VorausErrorHandler,
    VorausIndustrialRobotArm,
    configure_logging,
)

_logger: Logger = getLogger(__name__)

VORAUS_CORE_HOST = "localhost"
VORAUS_ROBOT_CONTROL_PORT = 48401
VORAUS_ERROR_HANDLER_PORT = 48404


@runtime_checkable
class _RequiredRobotTraits(
    SetExternalErrorVictorTrait, LifecycleTrait, Protocol
): ...


def run_set_and_reset_error_example(
    robot: _RequiredRobotTraits, error_handler: VorausErrorHandler
) -> None:
    """Example showing how to set and reset an error."""
    robot.set_external_error_v(
        source="Application", message="External error triggered!"
    )
    assert robot.get_lifecycle_state() == LifecycleState.ERROR
    _logger.info("External error was set.")

    error_handler.reset_error(robot)
    assert robot.get_lifecycle_state() == LifecycleState.CONNECTED
    _logger.info("Error reset.")


if __name__ == "__main__":
    configure_logging()

    robot = VorausIndustrialRobotArm()
    error_handler = VorausErrorHandler()
    with (
        robot.connect(VORAUS_CORE_HOST, VORAUS_ROBOT_CONTROL_PORT),
        error_handler.connect(VORAUS_CORE_HOST, VORAUS_ERROR_HANDLER_PORT),
    ):
        robot.enable()
        run_set_and_reset_error_example(robot, error_handler)

Definition of the Set External Error Method

The method is defined in the SetExternalErrorVictorTrait:

SetExternalErrorVictorTrait

protocol SetExternalErrorVictorTrait

Trait to set an external error on a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod set_external_error_v(source, message, timeout_s=5.0)

Put the robot control into the error state.

This method blocks until the robot control reports the error state.

Parameters:

source (str) – Component that has detected the error.
message (str) – Description of the error.
timeout_s (float) – Maximum time in seconds to wait for the robot control to enter the error state.

Raises:

RuntimeError – If the robot control did not enter the error state within the timeout.

Return type:

None

Time Override

Payload