Time Override

The global time override of a robot arm is a scaling factor used to adjust the overall speed of the robot’s movements. It ranges from a factor of 0.01 to 1.0 (or from 1 % to 100 %), while a factor of 1.0 indicates the robot operates at its maximum speed, whereas lower values slow down the robot arm’s movements proportionally. The time override should be used to scale the velocity of a whole application for example to minimize hazards during testing.

Note

If possible, refrain from using the time override for scaling the velocity during operation. Instead, use the speed option of the motion instructions.

Reading the Current Time Override

Reading the current time override can be done using either the method get_time_override_factor() or get_time_override_percent(). The first method returns a custom Factor type that ranges from 0.01 to 1.0, the latter option a custom Percent type that ranges from 1.0 % to 100 %.

An example using get_time_override_factor() can be seen here:

_logger.info(
    "The current time override factor is %s",
    robot.get_time_override_factor(),
)

Setting the Current Time Override

The time override of the robot can be manipulated via the set_time_override() method. The desired time override can be provided either as Factor or as Percent.

robot.set_time_override(Factor(0.25), timeout_s=2.0)

As soon as this method returns, it is guaranteed that the desired time override is actually set on the robot control. If the time override could not be set for any reason, the method will raise an error. The maximum time to wait for the new time override to be set can also be provided.

Here is a complete example of how to set a new time override:

Using the time override example

"""An example on how to set the time override."""

import os
from logging import Logger, getLogger
from math import radians
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    CartesianPose,
    Factor,
    JointPose,
    MovePTPTrait,
    TimeOverrideTrait,
    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]]
)


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


def run_my_application(robot: _RequiredRobotTraits) -> None:
    """Example application showing how to set the time override."""
    _logger.info(
        "The current time override factor is %s",
        robot.get_time_override_factor(),
    )
    robot.move_ptp_relative(
        target=CartesianPose(z=0.1), speed=Factor(0.75)
    ).result()
    robot.move_ptp_relative(
        target=CartesianPose(z=-0.1), speed=Factor(1.0)
    ).result()


def decrease_speed_if_in_test_mode(robot: _RequiredRobotTraits) -> None:
    """Decrease the overall speed when running in test mode."""
    in_test_mode = os.environ.get("TEST_MODE", "").lower() == "true"
    if in_test_mode:
        robot.set_time_override(Factor(0.25), timeout_s=2.0)
    else:
        robot.set_time_override(Factor(1), timeout_s=2.0)


if __name__ == "__main__":
    configure_logging()

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

If you run this script, the time override will be set to 100 % but if the environment variable TEST_MODE is set to True, the time override will be decreased to 25 %.

Setting the Time Override with a Transition Time

The time override of a robot from the Victor behavior group can also be set dynamically over a defined transition time using the set_time_override_v() method. The desired time override can be provided either as Factor or as Percent. The transition time has to be provided in seconds.

robot.set_time_override_v(
    time_override_value=Factor(0.25), transition_time_s=5
)

If this method is called during a robot standstill, the time override is set immediately. If this method is called during a robot motion, the time override has a soft transition and reaches its value after the set transition time. If the robot motion stops before the transition time has ended, the time override transition continues until the target value is reached. A short transition time can lead to high accelerations and torques.

move_instruction = robot.move_ptp(VERTICAL)
_wait_for_robot_to_move(robot)
robot.set_time_override_v(
    time_override_value=Factor(0.25), transition_time_s=5
)
while not move_instruction.is_done():
    _logger.info(
        "The current time override factor is %0.2f",
        robot.get_time_override_factor(),
    )
    time.sleep(1)

[INFO ]  The current time override factor is 0.10
[INFO ]  The current time override factor is 0.11
[INFO ]  The current time override factor is 0.14
[INFO ]  The current time override factor is 0.20
[INFO ]  The current time override factor is 0.23
[INFO ]  The current time override factor is 0.25

This method does return as soon as the time override value starts to change and does not block until the desired value is reached. It will not raise an error if the desired value is never reached. Another call of this method while a transition is active, will overwrite the previous command.

Here is a complete example of how to set a time override with transition time:

Using the time override example

"""An example on how to set the time override with a transition time."""

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

from voraus_robot_arm import (
    Factor,
    GetJointPoseTrait,
    JointPose,
    MovePTPTrait,
    TimeOverrideTrait,
    TimeOverrideVictorTrait,
    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]]
)


@runtime_checkable
class _TimeOverrideVictorRobot(
    MovePTPTrait,
    TimeOverrideVictorTrait,
    TimeOverrideTrait,
    GetJointPoseTrait,
    Protocol,
): ...


@runtime_checkable
class _JointPoseRobot(GetJointPoseTrait, Protocol): ...


def _almost_equal(list_1: list[float], list_2: list[float]) -> bool:
    return all(
        math.isclose(list_1_item, list_2_item)
        for list_1_item, list_2_item in zip(list_1, list_2, strict=True)
    )


def _wait_for_robot_to_move(
    robot: _JointPoseRobot,
    timeout_s: float = 2,
) -> None:
    last_pose = robot.get_joint_pose().to_list()
    start_time = time.time()
    while time.time() - start_time < timeout_s:
        time.sleep(0.01)
        current_pose = robot.get_joint_pose().to_list()
        if not _almost_equal(current_pose, last_pose):
            return

    msg = f"Robot did not start moving within {timeout_s} seconds!"
    raise RuntimeError(msg)


def _robot_is_not_moving(
    robot: _JointPoseRobot,
) -> bool:
    is_robot_moving = False

    last_pose = robot.get_joint_pose().to_list()
    for _ in range(10):
        current_pose = robot.get_joint_pose().to_list()
        if not _almost_equal(current_pose, last_pose):
            is_robot_moving = True
        time.sleep(0.01)

    return not is_robot_moving


def run_example(
    robot: _TimeOverrideVictorRobot,
) -> None:
    """Example showing how to set a timeout with a transition time."""
    robot.move_ptp(HOME).result()
    old_time_override = robot.get_time_override_factor()
    robot.set_time_override(Factor(0.1))

    move_instruction = robot.move_ptp(VERTICAL)
    _wait_for_robot_to_move(robot)
    robot.set_time_override_v(
        time_override_value=Factor(0.25), transition_time_s=5
    )
    while not move_instruction.is_done():
        _logger.info(
            "The current time override factor is %0.2f",
            robot.get_time_override_factor(),
        )
        time.sleep(1)
    move_instruction.result()

    robot.set_time_override(old_time_override)


def run_standstill_example(
    robot: _TimeOverrideVictorRobot,
) -> None:
    """Example showing time override with transition time in standstill."""
    old_time_override = robot.get_time_override_factor()
    does_not_matter_during_standstill = 1

    robot.set_time_override(Factor(0.1))
    _logger.info(
        "Time override factor is %0.2f",
        robot.get_time_override_factor(),
    )
    assert _robot_is_not_moving(robot)
    robot.set_time_override_v(
        time_override_value=Factor(0.5),
        transition_time_s=does_not_matter_during_standstill,
    )
    _logger.info(
        "The current time override factor is %0.2f",
        robot.get_time_override_factor(),
    )

    robot.set_time_override(old_time_override)


if __name__ == "__main__":
    configure_logging()

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

Definition of the Time Override Methods

The time override methods are defined in the TimeOverrideTrait:

TimeOverrideTrait

protocol TimeOverrideTrait

Trait to read and manipulate the time override of a robot.

This protocol is runtime checkable.

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

abstractmethod set_time_override(time_override_value, timeout_s=5.0)

Set the global time override to a specific value.

Parameters:

time_override_value (Factor | Percent) – The desired time override, either as a factor (0.01 - 1.0) or in percent (1.0 - 100.0).
timeout_s (float) – The maximum time in seconds to wait for the time override to be set. Defaults to 5.0 seconds.

Return type:

None

abstractmethod get_time_override_factor()

Get the global time override as factor.

Return type:: Factor
Returns:: Time override factor (0.01 - 1.0).

abstractmethod get_time_override_percent()

Get the global time override in percent.

Return type:: Percent
Returns:: Time override in percent (1 % - 100 %).

The time override methods for robots with Victor behavior are defined in the TimeOverrideVictorTrait:

TimeOverrideVictorTrait

protocol TimeOverrideVictorTrait

Trait to read and manipulate the time override for a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod set_time_override_v(time_override_value, transition_time_s, first_reaction_timeout_s=2.0)

Set the global time override to a specific value within a transition time.

This method does return as soon as the time override value starts to change and does not block until the desired value is reached. It will not raise an error if the desired value is never reached.

Another call of this method while a transition is active will overwrite the previous command.

Parameters:

time_override_value (Factor | Percent) – The desired time override, either as a factor (0.01 - 1.0) or in percent (1.0 - 100.0).
transition_time_s (float) – Transition time in seconds to smoothly adapt the desired time override. Minimum 0.25 seconds.
first_reaction_timeout_s (float) – The maximum time in seconds to wait for the time override to change. Defaults to 2 seconds.

Return type:

None

Stop

Resetting Errors