Setting and Resetting Errors

Setting an External Error

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. The control stops the robot, aborts all active and pending instructions and accepts no new ones until the error is reset.

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() with the source of the error and a message. Both are shown in the error message of the robot control:

robot.set_external_error("Application", "External error triggered!")?;

The call blocks until the robot control reports the error state. The wait is bounded by the robot’s command timeout; if the state is not reached in time, it returns StateNotReached. The error was sent by then and the robot control may still enter the error state, so do not take StateNotReached as “no error set”. The handles of the aborted instructions resolve with RobotArmError::RobotInErrorState, whose ControlError carries the robot control’s message with the source and message, so a thread waiting on a motion can tell this abort from a failure of the motion itself.

Resetting Errors

When the robot control detects a failure, it enters the error state. The robot stops, and the library aborts all active and pending instructions. The control leaves the error state only by an explicit reset. Until then, enable() fails with WrongState, so the robot cannot move again. This page shows how to reset an error.

Warning

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

Additionally, the error state and its reset procedure can be influenced by the overall system, of which the robot arm is a component.

The voraus.core shares the error state across multiple subsystems, so the robot control cannot directly reset the error. Instead, the error must be cleared by following the specific reset procedure for the voraus.core, which involves invoking a dedicated error handler. Every robot type runs on the voraus.core, so this procedure applies to all of them.

Resetting Errors on the voraus.core

Although the communication with the voraus error handler falls outside the scope of this library, this functionality is nonetheless provided for convenience.

In order to reset an error when working with a voraus.core instance, communication with the voraus error handler is necessary. This library provides a ready-to-use struct for this purpose, the VorausErrorHandler.

Connecting to the Error Handler

The error handler is a separate OPC UA server, typically on port 48404, independent from the robot control server on port 48401. Create a VorausErrorHandler and connect it with the host (an IP address or a hostname) and port of that server. Like a robot, the error handler owns a connection and has its own command timeout that bounds its calls (default 5 seconds, set_command_timeout() from the CommandTimeout trait). It disconnects when it is dropped; call disconnect() explicitly when the outcome matters.

let mut error_handler = VorausErrorHandler::new();
error_handler.set_command_timeout(Duration::from_secs(10));
error_handler.connect(host, error_handler_port)?;

Resetting an Error

After the connection is established, reset_error() can be called. It triggers the reset and blocks until the error is reset, otherwise it returns an error. The wait is bounded by the handler’s command timeout. In order to check whether the error was actually reset, the relevant robot is passed as an argument. As a result, it is guaranteed that the error is reset after reset_error() returned:

info!("Resetting error...");
error_handler.reset_error(robot)?;

let state = robot.robot_state()?;
if state == RobotState::Error {
    return Err(ExampleError::ResetFailed);
}
info!("Error reset successful. Robot state: {state:?}");

Any robot or read-only view can be passed, since the reset is observed through GetRobotState: the call returns once the robot control has left the Error and Reset states. After the reset, the robot is in Standby; call enable() before moving again.

Full Example

The example sets an external error and resets it. Like every example, it requires a running voraus.core, selected through VORAUS_CORE_HOST (default localhost).

Setting and resetting errors example

//! Resetting errors with the [`VorausErrorHandler`].
//!
//! Demonstrates how to set an external error and how to use
//! [`VorausErrorHandler`] to connect to the voraus-core error handler OPC UA
//! server and reset it.

mod common;

use thiserror::Error;
use tracing::info;
use voraus_robot_arm::prelude::*;

/// The errors of this example.
#[derive(Debug, Error)]
enum ExampleError {
    /// A call to the robot failed.
    #[error(transparent)]
    Robot(#[from] RobotArmError),
    /// The robot is not enabled before the external error is set.
    #[error("the robot is {actual:?}, expected it enabled")]
    NotEnabled {
        /// The state the robot reports.
        actual: RobotState,
    },
    /// The robot is not in the error state after the external error is set.
    #[error("the robot is {actual:?}, expected it in the error state")]
    NotInError {
        /// The state the robot reports.
        actual: RobotState,
    },
    /// The robot is still in the error state after the reset.
    #[error("the robot is still in the error state after the reset")]
    ResetFailed,
}

/// Demonstrate error handling: set an external error, then reset it via the
/// [`VorausErrorHandler`].
fn run_resetting_errors_example(
    robot: &(impl GetRobotState + SetExternalError),
    host: &str,
    error_handler_port: u16,
) -> Result<(), ExampleError> {
    use std::time::Duration;

    info!("--- Resetting Errors ---");

    // The robot should currently be enabled.
    let state = robot.robot_state()?;
    if !state.is_enabled() {
        return Err(ExampleError::NotEnabled { actual: state });
    }

    // Put the robot control into the error state. The call returns once the
    // control reports that state.
    robot.set_external_error("Application", "External error triggered!")?;
    let state = robot.robot_state()?;
    if state != RobotState::Error {
        return Err(ExampleError::NotInError { actual: state });
    }
    info!("External error was set.");

    // Connect to the error handler and reset the error. The handler owns a
    // connection, so it has its own command timeout; dropping it disconnects.
    let mut error_handler = VorausErrorHandler::new();
    error_handler.set_command_timeout(Duration::from_secs(10));
    error_handler.connect(host, error_handler_port)?;

    info!("Resetting error...");
    error_handler.reset_error(robot)?;

    let state = robot.robot_state()?;
    if state == RobotState::Error {
        return Err(ExampleError::ResetFailed);
    }
    info!("Error reset successful. Robot state: {state:?}");
    Ok(())
}

fn main() -> Result<(), ExampleError> {
    common::init_logging();
    let robot = common::create_connected_robot()?;

    run_resetting_errors_example(&robot, &common::robot_host(), common::error_handler_port())?;

    info!("Done.");
    Ok(())
}

API Summary

SetExternalError

pub trait SetExternalError {
    /// Put the robot control into the error state and wait until it reports
    /// that state.
    ///
    /// The control shows `source` and `message` in its error message.
    ///
    /// # Arguments
    ///
    /// * `source` - The component that detected the error.
    /// * `message` - A description of the error.
    ///
    /// # Returns
    ///
    /// `Ok(())` once the control reports the error state.
    ///
    /// # Errors
    ///
    /// Returns
    /// [`RobotArmError::StateNotReached`](crate::error::RobotArmError::StateNotReached)
    /// if the control does not report the error state within the command
    /// timeout (see
    /// [`CommandTimeout::set_command_timeout`](crate::traits::CommandTimeout::set_command_timeout)),
    /// or another [`RobotArmError`](crate::error::RobotArmError) if the call
    /// fails. `StateNotReached` comes after the error was sent: the control
    /// may still enter the error state, so do not treat it as "no error set".
    fn set_external_error(&self, source: &str, message: &str) -> Result<()> {
        self.send_external_error(source, message)?.confirm()
    }

    /// Send the external error.
    ///
    /// The call returns before the control confirms the error state. Call
    /// [`confirm`](CommandHandle::confirm) on the returned handle to wait
    /// for it.
    ///
    /// # Arguments
    ///
    /// * `source` - The component that detected the error.
    /// * `message` - A description of the error.
    ///
    /// # Returns
    ///
    /// The handle that confirms the error state. [`CommandHandle::confirm`]
    /// returns
    /// [`RobotArmError::StateNotReached`](crate::error::RobotArmError::StateNotReached)
    /// if the control does not report the error state within the command
    /// timeout. The control may still enter the error state then.
    ///
    /// # Errors
    ///
    /// Returns [`RobotArmError`](crate::error::RobotArmError) if the call
    /// fails.
    fn send_external_error(&self, source: &str, message: &str) -> Result<CommandHandle<'_>>;
}

The error handler is a struct, not a trait; its methods are documented in the API reference. The signatures of the two calls this chapter uses to reset an error:

pub fn connect(&mut self, host: &str, port: u16) -> Result<()> {

pub fn reset_error<R: GetRobotState + ?Sized>(&self, robot: &R) -> Result<()> {

Time Override

Payload