voraus_robot_arm package

A Python package for robot arm programming.

protocol AmendBlendingParametersTrait

Bases: Protocol

Trait to amend blending parameters retroactively.

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

abstractmethod amend_blending_parameter(blending)

Amend blending parameters retroactively to the previous movement instruction.

Calling this without a movement instruction does nothing. It is not possible to amend blending parameters to an instruction that already specified blending parameters. Amending the parameter too late - i.e. such that the robot already reached the previous end position - may result in a drop of the blend request by the robot control.

Parameters:: blending (Factor | Percent | Meters) – Blending with next instruction in percent or as factor.
Return type:: None

class ArrivingCSVictor(value)

Bases: IntEnum

An enum representing the arriving coordinate systems for robots with Victor behavior.

CAMERA = 2

MEDIA_FLANGE = 1

TOOL = 0

class CSVictor(value)

Bases: IntEnum

An enum representing the coordinate systems for robots with Victor behavior.

CAMERA = 3

ROBOT = 1

TOOL = 2

USER1 = 4

USER10 = 13

USER11 = 14

USER12 = 15

USER13 = 16

USER14 = 17

USER15 = 18

USER16 = 19

USER2 = 5

USER3 = 6

USER4 = 7

USER5 = 8

USER6 = 9

USER7 = 10

USER8 = 11

USER9 = 12

exception CanceledError

Bases: Exception

Initialize the error.

class CartesianAccelerationMagnitude(translational: float = 1, rotational: float = 1)

Bases: NamedTuple

Create new instance of CartesianAccelerationMagnitude(translational, rotational)

rotational: float: Rotational acceleration in radian per second squared.

translational: float: Translational acceleration in meter per second squared.

class CartesianPose(x=0, y=0, z=0, rx=0, ry=0, rz=0)

Bases: object

Create a new Cartesian pose.

Parameters:

x (float) – The x coordinate in meter. Defaults to 0.
y (float) – The y coordinate in meter. Defaults to 0.
z (float) – The z coordinate in meter. Defaults to 0.
rx (float) – Rotation around x axis in radian for a Cardan rotation matrix (Rx*Ry'*Rz''). Defaults to 0.
ry (float) – Rotation around y axis in radian for a Cardan rotation matrix (Rx*Ry'*Rz''). Defaults to 0.
rz (float) – Rotation around z axis in radian for a Cardan rotation matrix (Rx*Ry'*Rz''). Defaults to 0.

classmethod from_list(pose)

Initialize the class from a list.

Parameters:: pose (list[float]) – The pose for the Cartesian pose. The translation part [x,y,z] in meter and the orientation part [rx, ry, rz] in radian for a Cardan rotation matrix (Rx*Ry'*Rz'').
Raises:: ValueError – If the list is not of length six.
Return type:: CartesianPose
Returns:: The initialized class.

classmethod from_tuple(pose)

Initialize the class from a tuple.

Parameters:: pose (tuple[float, ...]) – The pose for the Cartesian pose. The translation part [x,y,z] in meter and the orientation part [rx, ry, rz] in radian for a Cardan rotation matrix (Rx*Ry'*Rz'').
Raises:: ValueError – If the tuple is not of length six.
Return type:: CartesianPose
Returns:: The initialized class.

to_list()

Return the pose as a list.

Return type:: list[float]
Returns:: The pose as a list.

to_tuple()

Return the pose as a tuple.

Return type:: tuple[float, float, float, float, float, float]
Returns:: The pose as a tuple.

class CartesianTargetVictor(pose, cs=CSVictor.ROBOT, arriving_cs=ArrivingCSVictor.TOOL, configuration_vector=None)

Bases: object

A class to represent a Cartesian target for robots with Victor behavior.

A Cartesian target describes a target for a general movement without ambiguity. As such it as an extension of a Cartesian pose by adding the desired coordinate system of the target pose, the arriving coordinate system and the desired robot configuration.

The configuration vector can be used to eliminate the ambiguity of a Cartesian pose by hinting the specific joint space tilt of the axis. Its length equals the number of robot axis and may only contain the values 1 or -1.

If no configuration vector is provided, the configuration of the start pose is adopted for PTP motions. Linear and circular movements will ignore the configuration vector in favor of interpolating the desired path.

class CartesianVelocity(x: float = 0, y: float = 0, z: float = 0, rx: float = 0, ry: float = 0, rz: float = 0)

Bases: NamedTuple

Create new instance of CartesianVelocity(x, y, z, rx, ry, rz)

rx: float: Rotational velocity around the X-axis in radian per second.

ry: float: Rotational velocity around the Y-axis in radian per second.

rz: float: Rotational velocity around the Z-axis in radian per second.

x: float: Translational velocity in X-direction in meter per second.

y: float: Translational velocity in Y-direction in meter per second.

z: float: Translational velocity in Z-direction in meter per second.

protocol CoordinateSystemVictorTrait

Bases: Protocol

Trait to configure coordinate systems for Victor robots.

This protocol is runtime checkable.

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

abstractmethod get_cs_origin_v(cs)

Get the origin of a coordinate system.

It is valid for robots with Victor behavior.

Parameters:: cs (CSVictor) – The coordinate system of which the origin should be read. Predefined non-user CS can not be read.
Raises:: AttributeError – Reading non-user CS is not supported. This exception will change to a ‘ValueError’ in the next major release. Consider using except (ValueError, AttributeError): when specifying exception handlers.
Return type:: CartesianPose
Returns:: The Cartesian pose of the origin of the desired coordinate system in robot CS

abstractmethod set_cs_origin_v(cs, new_origin)

Define the origin of a specific coordinate system.

It is valid for robots with Victor behavior.

Parameters:

cs (CSVictor) – The coordinate system to set. Predefined non-user CS can not be set and are not allowed.
new_origin (JointPose | CartesianPose | CartesianTargetVictor) – The desired pose for the new origin. CartesianPose is interpreted in RobotCS. CartesianTargetVictor uses the defined CS.

Raises:

AttributeError – Setting non-user CS is not allowed. This exception will change to a ‘ValueError’ in the next major release. Consider using except (ValueError, AttributeError): when specifying exception handlers.

Return type:

None

protocol DigitalInput

Bases: ReadableDigitalPin, Protocol

Protocol to interact with digital inputs.

A digital input of a robot control is a readable interface that is used for communication between a robot and external devices or sensors. Digital signals are binary, they can only be in one of two states: HIGH (true) or LOW (false).

Depending on the specific robot, a digital input may represent a physical pin on the robot cabinet or an abstract bit on a fieldbus.

This protocol is runtime checkable.

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

abstractmethod get_id()

Get the pin identifier for the represented pin.

Return type:: int

abstractmethod is_set()

Whether the digital pin is set to HIGH.

Return type:: bool

protocol DigitalInputGroup

Bases: ReadableDigitalPinGroup, Protocol

This protocol is runtime checkable.

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

abstractmethod get_ids()

Get the pin identifiers for all represented pins of this group.

Return type:: tuple[int, ...]

abstractmethod to_dict()

Read the latest values of all represented pins and return them as a dictionary mapping ids to values.

Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: dict[int, bool]

abstractmethod to_int()

Read the latest values of all represented pins and return them as a single base 10 integer.

The least significant bit is read from the pin with the lowest id, while the highest significant bit is read from the pin with the highest id. Bits in between are in increasing id order.

Please note, that gaps in ids do not jump binary increments and the maximum number returned is 2^len(get_ids)-1.

Example: If the group represents the ids 1, 2, and 4 with the values False, True and True the returned value is 6. Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: int

abstractmethod to_tuple()

Read the latest values of all represented pins and return them as a tuple of bools.

The order of values in the tuple matches to the same order of ids retrievable with get_ids. Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: tuple[bool, ...]

protocol DigitalInputVictorTrait

Bases: Protocol

Trait to read digital inputs for a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod get_digital_input_group_v(ids)

Get a group handle for digital inputs.

Parameters:: ids (tuple[int, ...]) – A tuple of input ids to handle as a group. IDs must be in increasing order.
Return type:: DigitalInputGroup
Returns:: A handle to the digital inputs.

abstractmethod get_digital_input_v(id)

Get a digital input handle.

Parameters:: id (int) – The id of the digital input to handle.
Return type:: DigitalInput
Returns:: A handle to the digital input.

abstractmethod get_maximum_input_id()

Get maximum id which can be read with the current robot.

Return type:: int

protocol DigitalOutput

Bases: ReadableDigitalPin, WritableDigitalPin, Protocol

Protocol to interact with digital outputs.

A digital output of a robot control is a readable and writable interface that is used for communication between a robot and external devices or sensors. Digital signals are binary, they can only be in one of two states: HIGH (True) or LOW (False).

Depending on the specific robot, a digital output may represent a physical pin on the robot cabinet or an abstract bit on a fieldbus.

This protocol is runtime checkable.

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

abstractmethod clear()

Set the digital pin to LOW.

Return type:: None

abstractmethod get_id()

Get the pin identifier for the represented pin.

Return type:: int

abstractmethod is_set()

Whether the digital pin is set to HIGH.

Return type:: bool

abstractmethod set()

Set the digital pin to HIGH.

Return type:: None

protocol DigitalOutputGroup

Bases: ReadableDigitalPinGroup, WritableDigitalPinGroup, Protocol

This protocol is runtime checkable.

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

abstractmethod get_ids()

Get the pin identifiers for all represented pins of this group.

Return type:: tuple[int, ...]

abstractmethod set_from_dict(to)

Set the pins of this group to the values within the provided dict.

Note that it depends on the robot control in use whether the values are set at once or sequential.

Parameters:: to (dict[int, bool]) – The states of the pins to be set. The keys of the dicts are the pin ids, the values are the desired pin state. All pin ids within the dict must be member of the pin group. Setting only a subset of pins of the group is supported.
Raises:: ValueError – If one or more pin ids are not member of this pin group
Return type:: None

abstractmethod set_from_int(to)

Set the all represented pins based on a single base 10 integer.

Note that it depends on the robot control in use whether the values are set at once or sequential.

Parameters:: to (int) – The base 10 integer that represent the bits to set the pins of this group. The least significant bit is set to the pin with the lowest id, while the highest significant bit is set to the pin with the highest id. Bits in between are in increasing id order. Please note, that gaps in ids do not jump binary increments and the maximum number returned is 2^len(get_ids)-1. Example: If the group represents the ids 1, 2, and 4 and should be set to the values False, True and True correct value is 6.
Return type:: None

abstractmethod set_from_tuple(to)

Set the pins of this group via a tuple.

The order of values in the to argument has to match the same order of ids retrievable with get_ids. Note that it depends on the robot control in use whether the values are set at once or sequential.

Parameters:: to (tuple[bool, ...]) – The states of the pins to be set. All pins of the group must be set.
Return type:: None

abstractmethod to_dict()

Read the latest values of all represented pins and return them as a dictionary mapping ids to values.

Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: dict[int, bool]

abstractmethod to_int()

Read the latest values of all represented pins and return them as a single base 10 integer.

The least significant bit is read from the pin with the lowest id, while the highest significant bit is read from the pin with the highest id. Bits in between are in increasing id order.

Please note, that gaps in ids do not jump binary increments and the maximum number returned is 2^len(get_ids)-1.

Return type:: int

abstractmethod to_tuple()

Read the latest values of all represented pins and return them as a tuple of bools.

The order of values in the tuple matches to the same order of ids retrievable with get_ids. Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: tuple[bool, ...]

protocol DigitalOutputVictorTrait

Bases: Protocol

Implementation of a trait to read and write digital outputs and outputs for a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod get_digital_output_group_v(ids)

Get a group handle for digital outputs.

Parameters:: ids (tuple[int, ...]) – A tuple of output ids to handle as a group. IDs must be in increasing order.
Return type:: DigitalOutputGroup
Returns:: A handle to the digital outputs.

abstractmethod get_digital_output_v(id)

Get a digital output handle.

Parameters:: id (int) – The id of the digital output to handle.
Return type:: DigitalOutput
Returns:: A handle to the digital output.

abstractmethod get_maximum_output_id()

Get maximum id which can be read with the current robot.

Return type:: int

class Factor(value: float)

Bases: _UnitBase

Create a new unit object from the unit base class.

Parameters:: value – The unit specific value.
Returns:: The new unit object.

to_percent()

Convert the factor to percent.

Return type:: Percent
Returns:: The value in percent.

class FanucRobotArm

Bases: LifecycleOpcUaImpl, MovePTPOpcUaImpl, MoveLinearOpcUaImpl, StopOpcUaImpl, WaitTimeOpcUaImpl, GetJointPoseOpcUaImpl, TimeOverrideOpcUaImpl, GetTcpPoseOpcUaImpl

Initialize the OPU UA driver.

class Future

Bases: object

Initialize the future.

is_done()

Return whether the future is done.

A future is done if its underlying operation - finished without errors or - was canceled or - finished with an exception.

Return type:: bool
Returns:: Whether the future is done.

result(timeout_s=None)

Wait for the future to be done and returns its result.

Parameters:

timeout_s (float | None) – Time in seconds to wait for a result. Defaults to None, which means there is no limit to the wait time.

Raises:

Exception – If the future is done but the operation raised an exception. That exception gets raised.
CanceledError – If the operation was canceled.
TimeoutError – If the future was not done within the given timeout.

Return type:

Any

Returns:

The result of the future’s operation.

protocol GetJointAccelerationsTrait

Bases: Protocol

Trait to retrieve joint acceleration data from the robot.

This protocol is runtime checkable.

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

abstractmethod get_joint_accelerations()

Get the current joint accelerations of the robot in rad/s².

Return type:: tuple[float, ...]
Returns:: The current joint accelerations in rad/s².

protocol GetJointPoseTrait

Bases: Protocol

Trait to get the current joint pose.

This protocol is runtime checkable.

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

abstractmethod get_joint_pose()

Get the current joint pose of the robot in radians.

Return type:: JointPose
Returns:: The current joint pose in radians.

protocol GetJointVelocitiesTrait

Bases: Protocol

Trait to retrieve joint velocities from the robot.

This protocol is runtime checkable.

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

abstractmethod get_joint_velocities()

Get the current joint velocities of the robot in rad/s.

Return type:: tuple[float, ...]
Returns:: The current joint velocities in rad/s.

protocol GetLimitsVictorTrait

Bases: Protocol

Trait to get limitations for robots with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod get_active_limits_v()

Get the currently active limits. The values reflect the combined effect of all active limit sets.

Return type:: LimitsVictor
Returns:: All currently active limit values.

abstractmethod get_limits_v(limit_set)

Get the limits for a specific limit set.

Parameters:: limit_set (str) – The limit set name.
Return type:: LimitsVictor
Returns:: A model with all limit of the given set.
Raises:: RobotArmError – If the limit set does not exist on the robot control.

protocol GetRobotStateVictorTrait

Bases: Protocol

Trait to retrieve the main state of a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod get_robot_state_v()

Get the current main state of the robot.

It is valid for robots with Victor behavior.

Return type:: RobotStateVictor
Returns:: The current main state of the robot.

protocol GetTcpPoseTrait

Bases: Protocol

Trait to get the tool center point (TCP) pose from the robot.

This protocol is runtime checkable.

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

abstractmethod get_tcp_pose()

Get the current tool center point (TCP) pose of the robot.

Return type:: CartesianPose
Returns:: The current TCP pose in meter for the translational part and radian for the orientational part.

protocol GetTcpVelocityTrait

Bases: Protocol

Trait to get the the tool center point (TCP) velocity of the robot.

This protocol is runtime checkable.

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

abstractmethod get_tcp_velocity()

Get the current tool center point (TCP) velocity of the robot.

Return type:: CartesianVelocity
Returns:: The current TCP velocity in m/s for the translational part and rad/s for the rotational part.

class HeartbeatKiller

Bases: object

Kill all active heartbeats because an error is detected.

static kill()

Kill all active heartbeats because an error is detected.

With a call to this function, all active heartbeats of the application will be killed manually.

It only works, if the automatic monitoring of thread exceptions is disabled, else a call to this function does nothing.

Return type:: None

class HeartbeatState(value)

Bases: StrEnum

An enum representing the heartbeat state.

ALIVE = 'ALIVE': The heartbeat is active and in a healthy state.

DEAD = 'DEAD': The heartbeat was active but was killed due to a detected error.

INACTIVE = 'INACTIVE': The heartbeat is not active.

protocol HeartbeatVictorTrait

Bases: Protocol

Trait to initialize a heartbeat for robots with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod get_heartbeat_state_v()

Get the heartbeat state.

Return type:: HeartbeatState
Returns:: The current heartbeat state.

abstractmethod heartbeat_v(session_id=None, interval_ms=1000)

Context manager for a heartbeat session with the robot control.

Only one voraus-robot-arm heartbeat session can be active at once.

Parameters:

session_id (int | None) – The id of the heartbeat session to start. If None, a random id will be generated. Defaults to None.
interval_ms (int) – The amount of time in ms the robot control waits for a new heartbeat signal before transitioning into an error state. Defaults to 1000.

Return type:

Generator[None, None, None]

abstractmethod start_heartbeat_v(session_id=None, interval_ms=1000)

Initiate a heartbeat session with the robot control.

Only one voraus-robot-arm heartbeat session can be active at once.

Parameters:

session_id (int | None) – The id of the heartbeat session to start. If None, a random id will be generated. Defaults to None.
interval_ms (int) – The amount of time in ms the robot control waits for a new heartbeat signal before transitioning into an error state. Defaults to 1000.

Return type:

None

abstractmethod start_unique_heartbeat_v(session_id=None, interval_ms=1000)

Initiate a unique heartbeat session with the robot control.

Unique means that this is the only active heartbeat session that exists globally for the robot control. Registering a new heartbeat while a unique heartbeat is active will be rejected and causes a robot control error. Calling this function while another heartbeat is active will cause a robot control error.

Parameters:

session_id (int | None) – The id of the heartbeat session to start. If None, a random id will be generated. Defaults to None.
interval_ms (int) – The amount of time in ms the robot control waits for a new heartbeat signal before transitioning into an error state. Defaults to 1000.

Return type:

None

abstractmethod stop_heartbeat_v()

Stop the currently active heartbeat session gracefully.

Requires an active heartbeat session else this raises an error.

Return type:: None

abstractmethod unique_heartbeat_v(session_id=None, interval_ms=1000)

Context manager for a unique heartbeat session with the robot control.

Parameters:

session_id (int | None) – The id of the heartbeat session to start. If None, a random id will be generated. Defaults to None.
interval_ms (int) – The amount of time in ms the robot control waits for a new heartbeat signal before transitioning into an error state. Defaults to 1000.

Return type:

Generator[None, None, None]

protocol JogContinuousCartesianVictorTrait

Bases: Protocol

Trait to jog in Cartesian space in a continuous manner for a robot with Victor behavior.

Deprecated since version 1.3.0: Was renamed to JogTcpVictorTrait. This old name is kept for compatibility but will be dropped with one of the next major versions.

This protocol is runtime checkable.

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

abstractmethod jog_continuous_cartesian_v(cs, velocity, acceleration=None)

Continuous instruction to jog in Cartesian space.

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:

cs (CSVictor) – The desired coordinate system.
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

Deprecated since version 1.3.0: Was renamed to jog_tcp_v. This old name is kept for compatibility but will be dropped with one of the next major versions.

protocol JogContinuousJointVictorTrait

Bases: Protocol

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

Deprecated since version 1.3.0: Was renamed to JogJointVictorTrait. This old name is kept for compatibility but will be dropped with one of the next major versions.

This protocol is runtime checkable.

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

abstractmethod jog_continuous_joint_v(joint_index, velocity, acceleration=1.25)

Continuous instruction to jog a single joint.

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

Deprecated since version 1.3.0: Was renamed to jog_joint_v. This old name is kept for compatibility but will be dropped with one of the next major versions.

protocol JogJointVictorTrait

Bases: Protocol

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.

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

protocol JogLinearVictorTrait

Bases: Protocol

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_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.

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.

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 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.

protocol JogPTPVictorTrait

Bases: Protocol

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_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.

abstractmethod jog_ptp_v(target, *, speed=None)

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

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

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.

protocol JogTcpVictorTrait

Bases: Protocol

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

class JoggingHandle(future, continue_call)

Bases: object

Initialize the jogging routine.

continue_jogging()

Continue the jogging routine.

Keep the jogging motion alive by periodically calling this method.

If the method is not called after a given period of time, which is robot specific, the robot will stop the motion.

Calling the method should have a cool down period. Calling without throttling causes undesired side effects and will therefore reject the request with a raised an error. Calling it at a later time is still valid.

Calling the method more than once after the target is reached results in an exception.

Raises:

RobotArmError – Cant continue jogging because the instruction is already done.
RobotArmError – If there are too many requests.

Return type:

None

is_done()

Return whether the jogging routine is done.

A jogging routine is done if its underlying operation - finished without errors or - was canceled or - finished with an exception.

Return type:: bool
Returns:: Whether the jogging routine is done.

result(timeout_s=None)

Wait for the jogging routine to be done and return its result.

Parameters:

timeout_s (float | None) – Time in seconds to wait for a result. Defaults to None, which means there is no limit to the wait time.

Raises:

Exception – If the jogging routine is done but the operation raised an exception. That exception gets raised.
CancelledError – If the jogging routine was canceled.
TimeoutError – If the jogging routine was not done within the given timeout.

Return type:

Any

Returns:

The result of the jogging routine’s operation.

class JointPose(j1=0, j2=0, j3=0, j4=0, j5=0, j6=0)

Bases: object

Create a new joint pose.

Parameters:

j1 (float) – The joint value in radian of axis 1.
j2 (float) – The joint value in radian of axis 2.
j3 (float) – The joint value in radian of axis 3.
j4 (float) – The joint value in radian of axis 4.
j5 (float) – The joint value in radian of axis 5.
j6 (float) – The joint value in radian of axis 6.

classmethod from_list(pose)

Initialize the class from a list.

Parameters:: pose (list[float]) – The pose for the joint pose in radian.
Raises:: ValueError – If the list is not of length six.
Return type:: JointPose
Returns:: The initialized class.

classmethod from_tuple(pose)

Initialize the class from a tuple.

Parameters:: pose (tuple[float, ...]) – The pose for the joint pose in radian.
Raises:: ValueError – If the tuple is not of length six.
Return type:: JointPose
Returns:: The initialized class.

to_list()

Return the the pose a list.

Return type:: list[float]
Returns:: The pose a list.

to_tuple()

Return the pose as a tuple.

Return type:: tuple[float, float, float, float, float, float]
Returns:: The pose as a tuple.

class K4PRobotArm

Bases: _VictorOpcUaRobot

Initialize the OPC UA driver for the K4P robot.

class LifecycleState(value)

Bases: StrEnum

Enum that represents the state of the robot lifecycle.

CONNECTED = 'CONNECTED': A connection is established, but the robot is not ready to move.

DISCONNECTED = 'DISCONNECTED': The robot instance is created. Default value.

ENABLED = 'ENABLED': The robot is ready to move and can receive instructions.

ERROR = 'ERROR': The robot is in an error state and not ready to move.

protocol LifecycleTrait

Bases: Protocol

Trait to read and manipulate the general lifecycle of a robot.

A typical lifecycle consist of the following steps:

The RobotArm object is created. It can be configured as desired, but has no connection to any robot.
After calling connect, RobotArm establishes a connection to the robot it would like to control. Utility interactions are now possible e.g. configuring robot settings but the robot is not ready to move and regulators are off.
Calling enable will bring the robot into an operational state, in which it is ready to move. This is usually the state in which all functionality of RobotArm is available.
Once the movement and operations have finished, disable brings the robot into a state where it is connected but cannot move. This is the same state as in step 2.
If RobotArm should not be used anymore, disconnect can be called. This step will execute any necessary operations to bring the robot in a clean state and then disconnect.

Because disable and disconnect may contain clean up operations, they should always be called. Otherwise the robot might be left in an unclean state. In order to guarantee this, a context manager for this class is available:

It is assumed that a dedicated error handler is responsible for resetting errors.

Typical state transitions are:

DISCONNECTED -> connect() -> CONNECTED -> disconnect() -> DISCONNECTED CONNECTED -> enable() -> ENABLED -> disable() -> CONNECTED

This protocol is runtime checkable.

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

abstractmethod __enter__()

Enter the context for clean up and disconnection handling after the robot is connected.

Return type:: Self

abstractmethod __exit__(exception_type, exception_instance, exception_traceback)

Exit the context and automatically clean up and disconnect.

Parameters:

exception_type (type[BaseException] | None) – The exception type, if an exception was raised.
exception_instance (BaseException | None) – The exception instance, if an exception was raised.
exception_traceback (TracebackType | None) – The exception traceback, if an exception was raised.

Return type:

None

abstractmethod connect(host, port)

Establish communication with the robot.

This function has to be called prior to any other operation. Use the result as a context manager to automatically disconnect on error.

Parameters:

host (str) – The host (e.g. IP address or hostname) to connect to.
port (int) – The port to use.

Return type:

Self

Returns:

The connected self instance.

abstractmethod disable()

Bring the robot into a state where it does not move anymore.

Return type:: None

abstractmethod disconnect()

Tear down communication with the robot.

This function has to be called as the last operation. A manual usage of disconnect is discouraged. Use the context manager instead.

Return type:: None

abstractmethod enable()

Bring the robot into a state where it is ready to move.

Return type:: None

abstractmethod get_lifecycle_state()

Get the current state of the lifecycle.

Return type:: LifecycleState
Returns:: The current lifecycle state.

class LimitsVictor(axes_acceleration: tuple[float, ...] | None = None, axes_velocity: tuple[float, ...] | None = None, axes_position_min: tuple[float, ...] | None = None, axes_position_max: tuple[float, ...] | None = None, axes_torque_relative: tuple[float, ...] | None = None, axes_torque_absolute: tuple[float, ...] | None = None, tcp_velocity_translational: float | None = None, tcp_velocity_rotational: float | None = None, tcp_force: float | None = None, elbow_translational_velocity: float | None = None, robot_power: float | None = None)

Bases: NamedTuple

Create new instance of LimitsVictor(axes_acceleration, axes_velocity, axes_position_min, axes_position_max, axes_torque_relative, axes_torque_absolute, tcp_velocity_translational, tcp_velocity_rotational, tcp_force, elbow_translational_velocity, robot_power)

axes_acceleration: tuple[float, ...] | None: Limitation of the axes acceleration in radian per second squared for rotational axes and meter per second squared for prismatic axes.

axes_position_max: tuple[float, ...] | None: Limitation of the maximum axes positions in radian for rotational axes and meter for prismatic axes.

axes_position_min: tuple[float, ...] | None: Limitation of the minimum axes positions in radian for rotational axes and meter for prismatic axes.

axes_torque_absolute: tuple[float, ...] | None: Limitation of the absolute axes torques in newton meter.

axes_torque_relative: tuple[float, ...] | None: Limitation of the relative axes torques in newton meter.

axes_velocity: tuple[float, ...] | None: Limitation of the axes velocities in radian per second for rotational axes and meter per second for prismatic axes.

elbow_translational_velocity: float | None: Limitation of the elbow translational velocity in meter per second.

robot_power: float | None: Limitation of the robot mechanical power in watt.

tcp_force: float | None: Limitation of the force at the tool center point in newton.

tcp_velocity_rotational: float | None: Limitation of the tool center point angular speed in radian per second.

tcp_velocity_translational: float | None: Limitation of the tool center point translational velocity in meter per second.

class Meters(value: float)

Bases: _UnitBase

Create a new unit object from the unit base class.

Parameters:: value – The unit specific value.
Returns:: The new unit object.

class MoveCartesianVictorParameters(acceleration_mps2=1, rotation_velocity_radps=1, rotation_acceleration_radps2=1, orientation_interpolation=OrientationInterpolationVictor.TO_TARGET_ORIENTATION, short_rotation=True)

Bases: object

Detail parameters to configure a Cartesian motion for robots with Victor behavior.

acceleration_mps2: Maximum absolute acceleration for translation [m/s2]. Defaults to 1. rotation_velocity_radps: Maximum absolute velocity for rotation [rad/s]. Defaults to 1. rotation_acceleration_radps2: Maximum absolute acceleration for rotation [rad/s2]. Defaults to 1. orientation_interpolation: Mode of orientation interpolation to use. short_rotation: Use the shorter or longer interpolation solution for orientation.

acceleration_mps2: float = 1

orientation_interpolation: OrientationInterpolationVictor = 1

rotation_acceleration_radps2: float = 1

rotation_velocity_radps: float = 1

short_rotation: bool = True

protocol MoveCircularTrait

Bases: Protocol

Trait to perform a circular movement using an intermediate via pose.

This protocol is runtime checkable.

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

abstractmethod move_circular(target, via, *, velocity_mps=1.0, blending=None)

Instruction that moves the robot end effector on a circular path in the Cartesian workspace.

The circle is defined by the start pose, the target pose and an intermediate via pose.

The CartesianPose is interpreted in the world coordinate system. No specific tool is assumed. The behavior depends on the specific robot in use.

A CartesianPose itself can be ambiguous in regards to the exact joint configuration of the robot. It is at the discretion of the underlying robot control to choose a convenient joint configuration to reach the given pose. This means, that the robot configuration reached depends on the starting position. With this generic interface it is not possible to force a specific robot configuration in Cartesian space. Please use a robot specific trait for this purpose.

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 1 m/s.

If blending is activated, the given target pose will not be reached exactly. The higher the blending factor, the more and earlier the blended path will deviate from the original path that would reach the target pose. In most cases this allows the robot to maintain a higher path velocity and complete the overall path faster.

The exact behavior and interpretation of the blending parameter as well as implicit limitations are highly dependent on the specific robot used.

Blending only works, if this instruction is not synchronized to the Python interpreter and the next instruction is received prior to the execution of this instruction. Otherwise, the robot will hold at the starting point of this instruction. If in that case the instruction leading to the starting point of this instruction also contained a blending parameter, the blending parameter of the previous instruction will be ignored. As a result, the previous instruction will not be blended.

Parameters:

target (CartesianPose | JointPose) – The target pose of the desired motion.
via (CartesianPose | JointPose) – An intermediate pose used to define the circular path between the start and target pose.
velocity_mps (float) – Maximum translational velocity for the tool center point in m/s. Defaults to 1 m/s.
blending (Factor | Percent | None) – Blending with next instruction in percent or as factor. Only works if this instruction is not synchronized to the Python interpreter.

Return type:

Future

Returns:

A Future to track the state of this operation.

abstractmethod move_circular_relative(target, via, *, velocity_mps=1.0, blending=None)

Instruction that moves the robot end effector on a circular path in the Cartesian workspace.

The target and via pose must be provided relative to the start pose. Please see move_circular for a detailed description of parameter options.

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

protocol MoveCircularVictorTrait

Bases: Protocol

Trait to perform a circular movement using an intermediate via pose.

It is valid for robots with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod move_circular_relative_v(target, via, *, velocity_mps=1.0, blending=None, extra_parameters=None)

Instruction that moves the robot end effector on a circular path in the Cartesian workspace.

This is a full parameter implementation for all robots with Victor behavior.

The target and via pose must be provided relative to the start pose. Please see move_circular_v for a detailed description of parameter options.

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

abstractmethod move_circular_v(target, via, *, velocity_mps=1.0, blending=None, extra_parameters=None)

Instruction that moves the robot end effector on a circular path in the Cartesian workspace.

This is a full parameter implementation for all robots with Victor behavior.

The circle is defined by the start pose, the target pose and an intermediate via pose.

The 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 velocity_mps argument defines the maximum translational velocity for the tool center point in m/s. Giving no argument results in a velocity of 1 m/s.

If blending is activated, the given target pose will not be reached exactly. The higher the blending factor, the more and earlier the blended path will deviate from the original path that would reach the target pose. It is interpreted as a radius around the given target. Once inside the radius, the robot is allowed to leave its path. The radius is limited to half of the shorter segments leading to or from the target, even if greater values are provided. Factor or Percent is directly related to this maximum radius.

Parameters:

target (CartesianPose | JointPose | CartesianTargetVictor) – The target pose of the desired motion.
via (CartesianPose | JointPose | CartesianTargetVictor) – An intermediate pose used to define the circular path between the start and target pose.
velocity_mps (float) – Maximum translational velocity for the tool center point in m/s. Defaults to 1 m/s.
blending (Factor | Percent | Meters | None) – Blending with next instruction in percent or as factor. Only works if this instruction is not synchronized to the Python interpreter.
extra_parameters (MoveCartesianVictorParameters | None) – Detailed parameters to configure the motion.

Return type:

Future

Returns:

A Future to track the state of this operation.

protocol MoveLinearTrait

Bases: Protocol

Trait to perform a linear movement of a robot arm.

This protocol is runtime checkable.

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

abstractmethod move_linear(target, *, velocity_mps=1.0, blending=None)

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

The CartesianPose is interpreted in the world coordinate system. No specific tool is assumed. The behavior depends on the specific robot in use.

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 1 m/s.

If blending is activated, the given target pose will not be reached exactly. The higher the blending factor, the more and earlier the blended path will deviate from the original path that would reach the target pose. In most cases this allows the robot to maintain a higher path velocity and complete the overall path faster.

The exact behavior and interpretation of the blending parameter as well as implicit limitations are highly dependent on the specific robot used.

Parameters:

target (JointPose | CartesianPose) – The target pose of the desired motion.
velocity_mps (float) – Maximum translational velocity for the tool center point in m/s. Defaults to 1 m/s.
blending (Factor | Percent | None) – Blending with next instruction in percent or as factor. Only works if this instruction is not synchronized to the Python interpreter.

Return type:

Future

Returns:

A Future to track the state of this operation.

abstractmethod move_linear_relative(target, *, velocity_mps=1.0, blending=None)

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

Please see move_linear for a detailed description of parameter options.

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

protocol MoveLinearVictorTrait

Bases: Protocol

Trait to perform 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 move_linear_relative_v(target, *, velocity_mps=1.0, blending=None, extra_parameters=None)

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

This is a full parameter implementation for all robots with Victor behavior.

Please see move_linear_v for a detailed description of parameter options.

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

abstractmethod move_linear_v(target, *, velocity_mps=1.0, blending=None, extra_parameters=None)

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

This is a full parameter implementation for all robots with Victor behavior.

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 1 m/s.

If blending is activated, the given target pose will not be reached exactly. The higher the blending factor, the more and earlier the blended path will deviate from the original path that would reach the target pose. It is interpreted as a radius around the given target. Once inside the radius, the robot is allowed to leave its path. The radius is limited to half of the shorter segments leading to or from the target, even if greater values are provided. Factor or Percent is directly related to this maximum radius.

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 1 m/s.
blending (Factor | Percent | Meters | None) – Blending with next instruction in percent or as factor. Only works if this instruction is not synchronized to the Python interpreter.
extra_parameters (MoveCartesianVictorParameters | None) – Detailed parameters to configure the motion.

Return type:

Future

Returns:

A Future to track the state of this operation.

protocol MovePTPTrait

Bases: Protocol

Trait to perform a point-to-point movement of a robot arm.

This protocol is runtime checkable.

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

abstractmethod move_ptp(target, *, speed=None, blending=None)

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

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

The CartesianPose is interpreted in the world coordinate system. No specific tool is assumed. The behavior depends on the specific robot in use.

The speed argument defines the general speed for the motion in regards to the possible maximum joint speed. Giving no argument results in a Factor of 1, which reflects the maximum speed.

If blending is activated, the given target pose will not be reached exactly. The higher the blending factor, the more and earlier the blended path will deviate from the original path that would reach the target pose. In most cases this allows the robot to maintain a higher path velocity and complete the overall path faster.

The exact behavior and interpretation of the blending parameter as well as implicit limitations are highly dependent on the specific robot used.

Parameters:

target (JointPose | CartesianPose) – The target pose 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).
blending (Factor | Percent | None) – Blending with next instruction in percent or as factor. Only works if this instruction is not synchronized to the Python interpreter.

Return type:

Future

Returns:

A Future to track the state of this operation.

abstractmethod move_ptp_relative(target, *, speed=None, blending=None)

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

Please see move_ptp for a detailed description of parameter options.

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

protocol MovePTPVictorTrait

Bases: Protocol

Trait to perform 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 move_ptp_relative_v(target, *, speed=None, blending=None)

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

This is a full parameter implementation for all robots with Victor behavior.

Please see move_ptp_v for a detailed description of parameter options.

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

abstractmethod move_ptp_v(target, *, speed=None, blending=None)

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

This is a full parameter implementation for all robots with Victor behavior.

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

The speed argument defines the general speed for the motion in regards to the possible maximum joint speed. Giving no argument results in a Factor of 1, which reflects the maximum speed.

If blending is activated, the given target pose will not be reached exactly. The higher the blending factor, the more and earlier the blended path will deviate from the original path that would reach the target pose. In most cases this allows the robot to maintain a higher path velocity and complete the overall path faster.

The exact behavior and interpretation of the blending parameter as well as implicit limitations are highly dependent on the specific robot used.

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).
blending (Factor | Percent | None) – Blending with next instruction in percent or as factor. Only works if this instruction is not synchronized to the Python interpreter.

Return type:

Future

Returns:

A Future to track the state of this operation.

exception OpcUaDriverError(message)

Bases: Exception

Initialize a OpcUaDriver error with a custom error message.

class OrientationInterpolationVictor(value)

Bases: IntEnum

An enum representing the orientation interpolation options for robots with Victor behavior.

CONSTANT_TO_PATH = 2

NONE = 0

TO_TARGET_ORIENTATION = 1

protocol PauseContinueTrait

Bases: Protocol

Trait to pause and continue the motion of a robot.

This protocol is runtime checkable.

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

abstractmethod continue_motion()

Continue the robot motion after it has been stopped by the pause_motion command.

Return type:: None

abstractmethod pause_motion(timeout_s=5.0)

Pause the robot’s motion.

The robot will decelerate on the planned path until standstill. Instructions can still be issued, but the robot will only execute the remaining instructions after continue_motion() is called.

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

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

If the robot was already stopped with stop_motion a pause has no effect.

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

protocol PayloadVictorTrait

Bases: Protocol

Trait to set and get the payload for a robot with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod get_payload_mass_v()

Get the currently configured payload mass of the robot.

This method is only available for robots within the Victor Robot Behavior Group.

Return type:: float
Returns:: The currently configured payload mass of the robot in kg.

abstractmethod remove_payload_v()

Remove the current payload.

This method is only available for robots within the Victor Robot Behavior Group.

Return type:: None

abstractmethod set_payload_v(mass_kg, center_of_mass)

Set the payload mass of the robot.

This method is only available for robots within the Victor Robot Behavior Group.

Parameters:

mass_kg (float) – Mass of the payload in kg.
center_of_mass (CartesianPose | None) – Center of the payload mass in tool coordinate system. Orientation is ignored.

Return type:

None

class Percent(value: float)

Bases: _UnitBase

Create a new unit object from the unit base class.

Parameters:: value – The unit specific value.
Returns:: The new unit object.

to_factor()

Convert a factor to percent.

Return type:: Factor
Returns:: The value as factor.

class PoseManager

Bases: object

Initialize an empty PoseManager.

add_pose(name, pose)

Add a new pose to the manager.

Example use:

pose_manager = PoseManager()
pose = JointPose(10, 20, 30, 40, 50, 60)
pose_manager.add_pose("pickup_pose", pose)

Parameters:

name (str) – Name of the pose.
pose (CartesianPose | JointPose | VorausPose) – The pose object.

Raises:

ValueError – If a pose with the same name already exists.

Return type:

None

delete_pose(name)

Delete a pose by name.

Example use:

pose_manager = PoseManager()
pose = JointPose(10, 20, 30, 40, 50, 60)
pose_manager.add_pose("pickup_pose", pose)
pose_manager.delete_pose("pickup_pose")

Parameters:: name (str) – The name of the pose to retrieve.
Raises:: KeyError – If the pose is not found.
Return type:: None

export_poses(file_path)

Export all poses to a YAML file.

Example use:

pose_manager = PoseManager()
pose = JointPose(10, 20, 30, 40, 50, 60)
pose_manager.add_pose("pickup_pose", pose)
file_path = Path("exported_poses.yaml")
pose_manager.export_poses(file_path)

Parameters:: file_path (Path) – Path to the YAML file where poses will be saved.
Raises:: TypeError – If unsupported pose type.
Return type:: None

get_all_poses()

Retrieve all poses as list.

Example use:

pose_manager = PoseManager()
pose = JointPose(10, 20, 30, 40, 50, 60)
pose_manager.add_pose("pickup_pose", pose)
print(pose_manager.get_all_pose())

Return type:: list[CartesianPose | JointPose | VorausPose]
Returns:: The poses as list.

get_pose(name)

Retrieve a pose by name.

Example use:

pose_manager = PoseManager()
pose = JointPose(10, 20, 30, 40, 50, 60)
pose_manager.add_pose("pickup_pose", pose)
print(pose_manager.get_pose("pickup_pose"))

Parameters:: name (str) – The name of the pose to retrieve.
Raises:: KeyError – If the pose is not found.
Return type:: CartesianPose | JointPose | VorausPose
Returns:: The pose object.

import_poses(file_path)

Import poses from a YAML file.

Example use:

file_path = Path(tmp_path / "exported_poses.yaml")
pose_manager = PoseManager()
pose_manager.import_poses(file_path)

Parameters:: file_path (Path) – Path to the YAML file to load poses from.
Return type:: None

protocol ReadableDigitalPin

Bases: Protocol

Protocol to specify read methods on digital pins.

This protocol is runtime checkable.

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

abstractmethod get_id()

Get the pin identifier for the represented pin.

Return type:: int

abstractmethod is_set()

Whether the digital pin is set to HIGH.

Return type:: bool

protocol ReadableDigitalPinGroup

Bases: Protocol

Protocol to specify read methods on a group of digital pins.

This protocol is runtime checkable.

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

abstractmethod get_ids()

Get the pin identifiers for all represented pins of this group.

Return type:: tuple[int, ...]

abstractmethod to_dict()

Read the latest values of all represented pins and return them as a dictionary mapping ids to values.

Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: dict[int, bool]

abstractmethod to_int()

Read the latest values of all represented pins and return them as a single base 10 integer.

The least significant bit is read from the pin with the lowest id, while the highest significant bit is read from the pin with the highest id. Bits in between are in increasing id order.

Please note, that gaps in ids do not jump binary increments and the maximum number returned is 2^len(get_ids)-1.

Return type:: int

abstractmethod to_tuple()

Read the latest values of all represented pins and return them as a tuple of bools.

The order of values in the tuple matches to the same order of ids retrievable with get_ids. Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: tuple[bool, ...]

exception RobotArmError(error_code, args=None)

Bases: Exception

Initialize the robot arm exception.

The error message gets retrieved from ROBOT_ARM_ERRORS and formatted with args. Robot-specific implementations should register their error codes and messages by updating ROBOT_ARM_ERRORS.

Parameters:

error_code (str) – The exception’s error code.
args (tuple[Any, ...] | None) – The arguments used for formatting the error message.

class RobotStateVictor(value)

Bases: IntEnum

An enum representing the robot main state of a robot with Victor behavior.

ACTIVE = 5: Robot is moving. Position, velocity and acceleration of each axis module is provided by the interpolator.

COLLISIONREACTION = 9: A collision has been detected by the robot. Robot will execute the configured collision reaction.

ERROR = 4: Error has occurred, robot comes to standstill as fast as possible and remains in this state until reset.

GRAVCOMP = 7: Robot is in gravitation compensation mode.

INIT = 0: Starting phase, initialization of robot and waiting for peripheral hardware.

READY = 2: Regulators are turned on, but robot is not moving. Waiting for user input

RESET = 6: Attempt to clear errors. Fieldbus connection is re-established if it was lost.

SHUTDOWN = 8: Transit the robot into standstill and turns off regulators. Terminates the robot control process.

STANDBY = 1: Robot is initialized and ready to turn regulators on. Robot can not move.

STOPPING = 3: Not implemented.

protocol SelectLimitSetsVictorTrait

Bases: Protocol

Trait to handle limit set selection for robots with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod activate_limit_set_v(limit_set)

Activate the given limit set.

Parameters:: limit_set (str) – The limit set name to activate.
Raises:: RobotArmError – If the limit set does not exist or cannot be activated.
Return type:: None

abstractmethod deactivate_limit_set_v(limit_set)

Deactivate the given limit set.

Parameters:: limit_set (str) – The limit set name to deactivate.
Raises:: RobotArmError – If the limit set does not exist or cannot be deactivated.
Return type:: None

abstractmethod get_active_limit_sets_v()

Get the names of the currently active limit sets.

Return type:: tuple[str, ...]
Returns:: The names of the currently active limit sets.

abstractmethod get_default_limit_sets_v()

Get the names of all default limit sets. Default limit sets are always activated.

Return type:: tuple[str, ...]
Returns:: The names of the default limit sets.

abstractmethod get_optional_limit_sets_v()

Get the names of all optional user-defined limit sets that can be activated or deactivated.

Return type:: tuple[str, ...]
Returns:: The names of the optional limit sets.

protocol SelectToolVictorTrait

Bases: Protocol

Trait to select a tool for robots with Victor behavior.

This protocol is runtime checkable.

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

abstractmethod deselect_tool_v()

Deselect the currently selected tool.

Raises:: RobotArmError – If no tool is selected.
Return type:: None

abstractmethod get_selectable_tools_v()

Get the names of the selectable tools.

Return type:: tuple[str, ...]
Returns:: The names of the selectable tools.

abstractmethod get_selected_tool_v()

Get the name of the tool which is currently selected.

If no tool is selected, this will return None.

Return type:: str | None
Returns:: The currently selected tool name or None.

abstractmethod select_tool_v(tool_name)

Select the given tool.

Note, the tool must be configured on the robot control.

Parameters:: tool_name (str) – The tool name to select.
Raises:: RobotArmError – If the tool does not exist on the robot control.
Return type:: None

protocol StopBehaviorVictorTrait

Bases: Protocol

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 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.

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 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

class StopSourceVictor(value)

Bases: Enum

ERROR_STOP = 1: Triggered by robot control errors.

SS1 = 3: Triggered by safety.

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

protocol StopTrait

Bases: Protocol

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

class StopTypeVictor(value)

Bases: Enum

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.

protocol TimeOverrideTrait

Bases: Protocol

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 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 %).

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

protocol TimeOverrideVictorTrait

Bases: Protocol

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.

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.

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

exception UnitLimitError(lower, value, upper)

Bases: ValueError

Initialize the unit limit error.

Parameters:

lower (float) – The lower limit.
value (_UnitBase) – The value which led to the error.
upper (float) – The upper limit.

class VorausErrorHandler

Bases: object

Create an VorausErrorHandler object.

connect(host, port)

Connect the VorausErrorHandler with the OPC UA server.

Parameters:

host (str) – The host (e.g. IP address or hostname) of the error handler OPC UA server.
port (int) – The port of the error handler OPC UA server.

Raises:

VorausErrorHandlerError – If already connected.

Return type:

Self

property connected: bool

Whether the VorausErrorHandler is connected or not.

Returns:: True, if the VorausErrorHandler is connected to the OPC UA server.

disconnect()

Disconnect the VorausErrorHandler from the OPC UA server.

Return type:: None

reset_error(robot, timeout_s=2.0)

Reset the error.

The error is guaranteed to be reset after this method returns, otherwise an exception is raised.

Parameters:

robot (LifecycleTrait) – The robot for which the error is expected to be reset.
timeout_s (float) – The maximum time in seconds to wait for the reset to be completed. Defaults to 2.0 s.

Raises:

VorausErrorHandlerError – If not connected.
VorausErrorHandlerError – If the error reset was not successful.

Return type:

None

exception VorausErrorHandlerError(message)

Bases: Exception

Initialize a VorausErrorHandlerError with a custom error message.

class VorausIndustrialRobotArm

Bases: _VictorOpcUaRobot

Initialize the OPC UA driver for voraus industrial robot.

protocol WaitTimeTrait

Bases: Protocol

Trait to halt the robot’s movement.

This protocol is runtime checkable.

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

abstractmethod wait_time(time_s)

Instruction that halts the robot’s movement for a specified time before continuing the execution.

The waiting is executed by the robot itself and not by the client, i.e. it is not equivalent to calling time.sleep().

Parameters:: time_s (float) – Time in seconds the robot waits before continuing with the next command.
Return type:: Future
Returns:: A Future to track the state of this operation.

protocol WritableDigitalPin

Bases: Protocol

Protocol to specify write methods on digital pins.

This protocol is runtime checkable.

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

abstractmethod clear()

Set the digital pin to LOW.

Return type:: None

abstractmethod set()

Set the digital pin to HIGH.

Return type:: None

protocol WritableDigitalPinGroup

Bases: Protocol

Protocol to specify write methods on a group of digital pins.

This protocol is runtime checkable.

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

abstractmethod set_from_dict(to)

Set the pins of this group to the values within the provided dict.

Note that it depends on the robot control in use whether the values are set at once or sequential.

Parameters:: to (dict[int, bool]) – The states of the pins to be set. The keys of the dicts are the pin ids, the values are the desired pin state. All pin ids within the dict must be member of the pin group. Setting only a subset of pins of the group is supported.
Raises:: ValueError – If one or more pin ids are not member of this pin group
Return type:: None

abstractmethod set_from_int(to)

Set the all represented pins based on a single base 10 integer.

Note that it depends on the robot control in use whether the values are set at once or sequential.

Parameters:: to (int) – The base 10 integer that represent the bits to set the pins of this group. The least significant bit is set to the pin with the lowest id, while the highest significant bit is set to the pin with the highest id. Bits in between are in increasing id order. Please note, that gaps in ids do not jump binary increments and the maximum number returned is 2^len(get_ids)-1. Example: If the group represents the ids 1, 2, and 4 and should be set to the values False, True and True correct value is 6.
Return type:: None

abstractmethod set_from_tuple(to)

Set the pins of this group via a tuple.

Parameters:: to (tuple[bool, ...]) – The states of the pins to be set. All pins of the group must be set.
Return type:: None

class YuRobotArm

Bases: _VictorOpcUaRobot

Initialize the OPC UA driver for Yu.

configure_logging(log_file_dir=None, log_file_retention_amount=3)

Convenience function to configure logging.

This function configures the following log outputs:

A log file “app.log” containing all logs emitted by the application and its dependencies (level = INFO, or DEBUG if environment variable ‘DEBUG’ is True)
A stdout logger containing all logs emitted by the application and its dependencies (level = INFO, or DEBUG if environment variable ‘DEBUG’ is True)
A log file “voraus-robot-arm.log” containing all logs emitted by voraus-robot-arm (level = DEBUG)

It is only designed to generate quickly accessible logs during programming and prototyping. Do not use it in production environments. The usage of the enabled DEBUG level may result in a performance burden.

Each run will create a new log file until the maximum number of log files to keep log_file_retention_amount is reached. If this number is exceeded, the oldest log file will be overwritten.

Parameters:

log_file_dir (Path | None) – The directory where the log files are created. If no path is given, the current working directory is used. Defaults to None.
log_file_retention_amount (int | None) – The max. number of log files to keep on disk. If this number is exceeded, the oldest log file will be overwritten. If None, all log files are kept forever. Defaults to 3.

Return type:

None

setup_logging(logger=None, log_file_dir=None, log_file_retention_amount=3)

Convenience function to configure logging.

Creates a stdout handler as well as a file handler with custom formatting and a retention policy. The log file will be named like the provided logger.

Parameters:

logger (Logger | None) – The logger to configure, if no logger provided the voraus robot arm logger is used. Defaults to None.
log_file_dir (Path | None) – The directory where the log file is created. If no path is created, the current working directory used. Defaults to None.
log_file_retention_amount (int | None) – The number of log files to keep on disk. If this number is exceeded, the oldest log file will be overwritten. If None, all log files are kept forever. Defaults to 3.

Return type:

None

Deprecated since version 1.4.0: This function does not do, what it was designed to do. It was replaced by configure_logging. This old version is kept for compatibility but will be dropped with one of the next major versions.

x(value)

Return a Cartesian pose with only an x value.

Note: All other attributes of the Cartesian pose are initialized as zero.

Parameters:: value (float) – The x value in meter to initialize the pose with.
Return type:: CartesianPose
Returns:: The Cartesian pose

y(value)

Return a Cartesian pose with only a y value.

Note: All other attributes of the Cartesian pose are initialized as zero.

Parameters:: value (float) – The y value in meter to initialize the pose with.
Return type:: CartesianPose
Returns:: The Cartesian pose.

z(value)

Return a Cartesian pose with only a z value.

Note: All other attributes of the Cartesian pose are initialized as zero.

Parameters:: value (float) – The z value in meter to initialize the pose with.
Return type:: CartesianPose
Returns:: The Cartesian pose.

Generate the changelog for a release

Changelog