Tormach Robot Programming Language

Contents

The TRPL is based on Python. All commands interpreted by the TRPL interpreter are Python code, which means you can use any Python code to control the robot. However, the graphical conversational programming utility only supports re-interpretation of a subset of commands as defined here.

Supported Commands

New in version 0.1.3.

New in version 0.1.4.

New in version 0.2.2.

Program structure

A TRPL program is a simple Python file with a single main function containing the program code. The support RPL commands are imported per default; any additional external libraries can be imported if required.

Note that the program interpreter only can track code execution in the main program file. Blocking commands in external libraries might, therefore, lock up the program execution

The main function is executed in a loop. If you want to break this behavior, use the exit statement.

1 2 3 4 5 6 7 8 9 10 11 set_units("mm", "deg") # set the linear and angular unit types for the program # waypoints are defined in the header of the program waypoint_1 = j[0.764, 1.64, 0.741, 0.433, 0.140, 2.74] waypoint_2 = p[361.53,947.19, 937.11, 45, 0, 0] # the main function contains the program code def main(): movel(waypoint_1) # a linear move command sleep(0.5) # wait for 0.5 seconds movej(waypoint_2) # a joint move command sleep(0.5) # wait for 0.5 seconds

Python Stubs

Below you can find Python stub files, supported in most modern IDEs.

To use them, you need to add the from robot_command.rpl import * import at the beginning of the program. Moreover, install the robot_command-stubs package by issuing the python3 setup.py install command.

stubs.zip

Linear and Angular Units

The TRPL supports multiple linear and angular measurement units. It is advised to define the units used in a program as the first line of the program. Changing units at runtime is supported, but highly discouraged.

Supported linear unit types:

  • “m” - Meters

  • “mm” - Millimeters

  • “in” - Inches

Supported angular unit types:

  • “deg” - Degrees

  • “rad” - Radians

robot_command.rpl.set_units(linear: Optional[Union[str, pint.util.SharedRegistryObject]] = None, angular: Optional[Union[str, pint.util.SharedRegistryObject]] = None)

Sets the active linear and angular units for the program.

Parameters:

  • linear – Linear/length unit type: m, mm, inch

  • angular – Angular/rotation unit type: deg, rad

Examples

1 2 3 set_units("mm", "deg") set_units(linear="in") set_units(angular="rad")

robot_command.rpl.get_units() -> Tuple[str, str]

Returns the active linear and angular units from the program.

Returns:

Linear/length unit type and angular/rotation unit type.

Examples

1 linear, angular = get_units()

Waypoints

Waypoints are defined either as joint configuration, as list of joint positions, or as a robot pose with location in Cartesian coordinates XYZ and orientation in Euler angles ABC. Robot poses furthermore relate to an offset from the world origin, usually located at the robot base. If no offset is active or specified with the waypoint, reference to the world origin is assumed.

Global and Local Waypoints

Global waypoints are waypoints that can be reused between programs. These waypoints are referenced by name inside the TRPL. Contrary, local waypoints are defined in the beginning of a robot program as Python variables.

Joints - Waypoint Defined as Joint Configuration

Joint positions can be defined by using the Joints object or the JointsFactory using the j[] shortcut. The values of j1 to j6 are the six joint positions of the robot arm.

class robot_command.rpl.Joints(j1: float = 0.0, j2: float = 0.0, j3: float = 0.0, j4: float = 0.0, j5: float = 0.0, j6: float = 0.0)

The Joints object consists of six joint position values to be used as target for move commands or to represent the current robot joint state.

Examples

1 2 waypoint_1 = Joint(323.62, 345.37, 477.76, 431.10, 918.62) waypoint_2 = Joint(j3=0.543) # all other joint positions are 0.0 by default

class robot_command.rpl.JointsFactory

The JointsFactory class helps constructing Joints object using a shorthand notation. In the robot program it can be accessed using the j[] shortcut.

Examples

1 waypoint_1 = j[0.764, 1.64, 0.741, 0.433, 0.140, 2.74]

robot_command.rpl.get_joint_values() -> robot_command.rpl.Joints

Returns the current joint values.

Returns:

Current joint values.

Examples

1 joint_value = get_joint_values()

Pose - Waypoint Defined as Pose

Poses can be defined using the Pose object or the PoseFactory using the p[] shortcut. x, y, z are the Cartesian coordinates of the robot position. a, b, c is the orientation defined in Euler angles (static XYZ).

Optionally, poses can be defined with a reference frame defined as offset in the robot UI. When no offset is defined, it is assumed that the waypoint is defined in world coordinates.

Work offsets are not enforced at runtime. You still need to use a change_work_offset() statement before an offset becomes active.

class robot_command.rpl.Pose(x: Union[numbers.Number, pint.quantity.build_quantity_class.<locals>.Quantity] = 0.0, y: Union[numbers.Number, pint.quantity.build_quantity_class.<locals>.Quantity] = 0.0, z: Union[numbers.Number, pint.quantity.build_quantity_class.<locals>.Quantity] = 0.0, a: Union[numbers.Number, pint.quantity.build_quantity_class.<locals>.Quantity] = 0.0, b: Union[numbers.Number, pint.quantity.build_quantity_class.<locals>.Quantity] = 0.0, c: Union[numbers.Number, pint.quantity.build_quantity_class.<locals>.Quantity] = 0.0, offset: str = '')

A robot pose consists of XYZ position ABC orientation parameters.

Optionally, an offset frame can be recorded with a waypoint.

Examples

1 2 waypoint_1 = Pose(483.21, 34.21, 21.59, 42.03, 71.14) waypoint_2 = Pose(a=0.543) # all other coordinate values are 0.0 per default.

class robot_command.rpl.PoseFactory

The PoseFactory class helps constructing Pose object using a shorthand notation. In the robot program it can be accessed using the p[] shortcut.

Examples

1 waypoint_1 = p[202.73, 750.08, 91.75, 6.63, 53.21, "table"] # captured with table work offset

robot_command.rpl.get_pose(apply_work_offset: bool = True, apply_tool_offset: bool = True) -> robot_command.rpl.Pose

Returns the current robot pose.

Parameters:

  • apply_work_offset – Applies the active work offset to the world pose.

  • apply_tool_offset – Applies the active tool offset to the world pose.

Returns:

Current robot pose.

Examples

1 current_pose = get_pose()

Setting and getting global waypoints from robot programs

Robot programs can set or get a global waypoint as part of its execution. Setting of a new global waypoint is achieved by calling robot_command.rpl.set_global_waypoint(). Getting of existing global waypoints is accomplished by calling robot_command.rpl.get_global_waypoint().

robot_command.rpl.set_global_waypoint

alias of robot_command.rpl._create_doc_commands.<locals>.funct

robot_command.rpl.get_global_waypoint

alias of robot_command.rpl._create_doc_commands.<locals>.funct

Movement

The robot can be moved using the following move types:

movej - Joint Move

robot_command.rpl.movej(target: Union[robot_command.rpl.Pose, robot_command.rpl.Joints], v: float = 1.0, probe: int = 0) -> Optional[Tuple[int, rospy.rostime.Time, robot_command.rpl.Joints, robot_command.rpl.Pose]]

Moves the robot end effector to the target waypoint with a joints move. Targets can be local waypoints or global waypoints defined as pose or joints.

Parameters:

  • target – target target

  • v – scale factor for velocity (default is full speed)

  • probe – specify the probe mode (2-6, or 0 for no probing) Probe mode 2: look for rising edge on probe signal (i.e. contact), raise ProbeFailedError if move completes without seeing a rising edge Probe mode 3: like mode 2 but does not raise error if move completes without rising edge Probe mode 4: like mode 2 but looks for falling edge Probe mode 5: like mode 4 but does not raise an error if move completes without falling edge Probe mode 6: “retract” mode, ignore falling edges and allow motion while probe signal is active, but raise ProbeUnexpectedContactError if a rising edge is seen

Returns:

tuple of probe results (for probing mode 2,3,4,5) or None: (probe contact type (0 = no contact, 1 = rising, 2 = falling), time of probe contact, Joint positions at probe contact, End-effector position / orientation pose at probe contact)

Examples

1 2 3 movej(waypoint_1) movej("global_waypoint_1") movej(p[0, 100, 0, 90, 20, 0])

movel - Linear Move

robot_command.rpl.movel(target: Union[robot_command.rpl.Pose, robot_command.rpl.Joints], a: float = 0.5, v: float = 0.5, probe: int = 0) -> Optional[Tuple[int, rospy.rostime.Time, robot_command.rpl.Joints, robot_command.rpl.Pose]]

Moves the robot end effector in a straight line from the current position to the target waypoint. Targets can be local waypoints or global waypoints defined as pose or joints.

Parameters:

  • target – target target

  • v – move velocity scaling factor 0.0 - 1.0

  • a – move acceleration scaling factor 0.0 - 1.0

  • probe – specify the probe mode (2-6, or 0 for no probing) Probe mode 2: look for rising edge on probe signal (i.e. contact), raise ProbeFailedError if move completes without seeing a rising edge Probe mode 3: like mode 2 but does not raise error if move completes without rising edge Probe mode 4: like mode 2 but looks for falling edge Probe mode 5: like mode 4 but does not raise an error if move completes without falling edge Probe mode 6: “retract” mode, ignore falling edges and allow motion while probe signal is active, but raise ProbeUnexpectedContactError if a rising edge is seen

Returns:

tuple of probe results: (probe contact type (0 = no contact, 1 = rising, 2 = falling), time of probe contact, Joint positions at probe contact, End-effector position / orientation pose at probe contact)

Examples

1 2 3 movel(waypoint_1) movel("global_waypoint_1", a=0.4, v=0.2) movel(j[0.764, 1.64, 0.741, 0.433, 0.140, 2.74])

movec - Circular Move

robot_command.rpl.movec(interim: Union[robot_command.rpl.Pose, robot_command.rpl.Joints], target: Union[robot_command.rpl.Pose, robot_command.rpl.Joints], a: float = 0.5, v: float = 0.5, probe: int = 0) -> Optional[Tuple[int, rospy.rostime.Time, robot_command.rpl.Joints, robot_command.rpl.Pose]]

Circular/Arc move command.

Parameters:

  • interim – interim waypoint

  • target – target waypoint

  • v – move velocity scaling factor 0.0 - 1.0

  • a – move acceleration scaling factor 0.0 - 1.0

  • probe – specify the probe mode (2-6, or 0 for no probing) Probe mode 2: look for rising edge on probe signal (i.e. contact), raise ProbeFailedError if move completes without seeing a rising edge Probe mode 3: like mode 2 but does not raise error if move completes without rising edge Probe mode 4: like mode 2 but looks for falling edge Probe mode 5: like mode 4 but does not raise an error if move completes without falling edge Probe mode 6: “retract” mode, ignore falling edges and allow motion while probe signal is active, but raise ProbeUnexpectedContactError if a rising edge is seen

Returns:

tuple of probe results (for probing mode 2,3,4,5) or None: (probe contact type (0 = no contact, 1 = rising, 2 = falling), time of probe contact, Joint positions at probe contact, End-effector position / orientation pose at probe contact)

movef - Free-form Move

robot_command.rpl.movef(target: Union[robot_command.rpl.Pose, robot_command.rpl.Joints]) -> None

Free move command.

Parameters:

target – target target

Trajectory Execution

In same cases it is beneficial to execute a raw trajectory pre-planned in another program, for example Maya Mimic. The robot program supports loading, saving and executing such trajectories.

robot_command.rpl.load_trajectory(file_path: str) -> trajectory_msgs.msg._JointTrajectory.JointTrajectory

Loads a raw joint trajectory from a CSV file and returns them in ROS format.

Parameters:

file_path – Path of the CSV file.

Returns:

A ROS joint trajectory.

robot_command.rpl.save_trajectory(file_path: str, trajectory: trajectory_msgs.msg._JointTrajectory.JointTrajectory) -> None

The save trajectory command saves a joint trajectory to a CSV file.

Parameters:

  • file_path – Path of the CSV file.

  • trajectory – The joint trajectory to save.

robot_command.rpl.execute_trajectory(trajectory: trajectory_msgs.msg._JointTrajectory.JointTrajectory, v: float = 1.0, retime: bool = False) -> None

The execute trajectory command executes a ROS JointTrajectory. Before running the joint trajectory, the robot moves to the start joint position using a joint move command.

Parameters:

  • trajectory – a ROS joint trajectory

  • v – move velocity scaling factor 0.0 - 1.0

  • retime – Enable retiming the trajectory to make use of the velocity scaling.

Examples

1 2 3 trajectory = load_trajectory('test.csv') execute_trajectory(trajectory) save_trajectory('test2.csv', trajectory)

Glossary of Move Errors

Move commands typically fails due to two major reasons, either during planning or during execution. You can catch those errors and retry a move inside the robot program.

exception robot_command.rpl.MovePlanningError

exception robot_command.rpl.MoveExecutionError(message=None, error_code=None)

Examples

1 2 3 4 try: movel(waypoint) except MovePlanningError: # is raised in case of a planning error notify("Move planning failed", warning=True)

Path Blending

Joint moves as well as linear and circular moves can be blended together into one continuous motion. This behavior can be enabled using the set_path_blending() method. Note that the motion will be executed before the next non-motion command. To force the execution of blended commands, use the the sync() method.

robot_command.rpl.set_path_blending(enable: bool, blend_radius: Optional[float] = None) -> None

Enables or disables path blending and sets the blend radius.

Parameters:

  • enable – Enable or disable path blending.

  • blend_radius – The blend radius between moves in meters.

Examples

1 2 3 4 5 6 set_path_blending(True, 0.0) # enable path blending, blend radius 0.0m movej(waypoint1) movej(waypoint2) movej(waypoint3) sync() # moves executed before this command set_path_blending(False) # disable path blending again

robot_command.rpl.sync() -> None

The sync command is used in wait cycles and to force the execution of queued move commands.

Work and Tool Offsets

The TRPL supports an arbitrary number of named work and tool offsets. These offsets are usually defined in the robot UI, however, can also be set inside a program.

Work Offsets

robot_command.rpl.change_work_offset(name: Optional[str]) -> None

Change the currently active work offset. If an empty string or None is used as as the name parameter, the empty work offset world becomes active.

Parameters:

name – The name of the tool offset to activate or None to disable work offsets.

Examples

1 2 change_work_offset("table") change_work_offset(None) # disable any active offsets

robot_command.rpl.set_work_offset(name: str, pose: Optional[Union[robot_command.rpl.Pose, str]] = None, position: Optional[Union[robot_command.rpl.Pose, str]] = None, orientation: Optional[Union[robot_command.rpl.Pose, str]] = None) -> None

Sets a work offset using a pose, position or orientation or clears an offset.

The position and orientation arguments can be combined to overwrite the pose’s position or orientation.

Parameters:

  • name – Name of the work offset

  • pose – Pose to use for the work offset

  • position – Use the position of this pose to override the position of the pose.

  • orientation – Use the orientation of this pose to override the orientation of the pose.

Examples

1 2 3 set_work_offset("table", p[0, 100, 0, 0, 0, 0]) set_work_offset("offset_1", waypoint_2, orientation=Pose(a=90)) set_work_offset("offset_1") # clears offset_1

robot_command.rpl.get_work_offset(name: str) -> Optional[robot_command.rpl.Pose]

Returns the pose of a work offset.

Parameters:

name – Name of the work offset.

Returns:

Pose of the work offset.

Raises:

TypeError – if no work offset with the name is found

Examples

1 pose = get_work_offset("table")

robot_command.rpl.work_offset(pose=None, position=None, orientation=None, world=False)

Scoped offset command. Applies a work offset temporarily on top of the currently active work offset.

The scoped offset command can be used to automatically switch the active offset back to a previous state when the scope is left. Scoped offsets can be nested. Scoped offsets are temporary and do not have a name.

Parameters:

  • pose – The offset pose.

  • position – A pose from which the position is used for the offset.

  • orientation – A pose from which the orientation is used for the offset.

  • world – If set to True the offset is absolute.

Examples

1 2 3 with work_offset(p[0, 100, 0, 90, 20, 0]): # creates a temporary offset and activates it movel(Pose(x=10)) # move x by 10 starting from the offset # the active offset automatically reset when the scope is left

Tool Offsets

robot_command.rpl.change_tool_offset(name: Optional[str]) -> None

Change the currently active tool offset. If an empty string or None is used as as the name parameter, the empty tool offset none becomes active.

Parameters:

name – The name of the tool offset to activate or None to disable tool offsets.

Examples

1 2 change_tool_offset("table") change_tool_offset(None) # disable any active offsets

robot_command.rpl.set_tool_offset(name: str, pose: Union[robot_command.rpl.Pose, str] = None, position: Union[robot_command.rpl.Pose, str] = None, orientation: Union[robot_command.rpl.Pose, str] = None) -> None

Sets a tool offset using a pose, position or orientation or clears an offset.

The position and orientation arguments can be combined to overwrite the pose’s position or orientation.

Parameters:

  • name – Name of the tool offset

  • pose – Pose to use for the tool offset

  • position – Use the position of this pose to override the position of the pose.

  • orientation – Use the orientation of this pose to override the orientation of the pose.

Examples

1 2 3 set_tool_offset("some_tool", p[0, 0, 100, 0, 0, 0]) set_tool_offset("other_tool", waypoint_2, position=Pose(z=0.1)) set_tool_offset("other_tool") # clears offset other_tool

robot_command.rpl.get_tool_offset(name: str) -> Optional[robot_command.rpl.Pose]

Returns the pose of a tool offset.

Parameters:

name – Name of the tool offset.

Returns:

Pose of the work offset or None if it does not exist.

Raises:

TypeError – if no tool offset with the name is found

Examples

1 pose = get_tool_offset("tool1")

Digital I/O

Digital input/output pins can be accessed via their name or by their number.

robot_command.rpl.set_digital_out(nr_or_name: Union[int, str], state: bool) -> None

Sets a digital output pin to high or low state.

Parameters:

  • nr_or_name – The number or name of the digital output pin.

  • state – Set to True or False for on and off.

Examples

1 2 set_digital_out("gripper", True) set_digital_out(2, False)

robot_command.rpl.get_digital_in(nr_or_name: Union[str, int]) -> bool

Returns the current digital input state.

Parameters:

nr_or_name – The number or name of the digital output pin.

Returns:

True or False for High and Low.

Examples

1 2 io_state = get_digital_in("gripper") x = get_digital_in(3)

PathPilot Remote

The PathPilot remote interface can be used to remotely control a PathPilot instance.

robot_command.rpl.pathpilot_cycle_start(instance: str = '') -> None

Starts a cycle on the remote PathPilot instance. If no instance argument is given, the command is executed on the first connected PathPilot instance.

Parameters:

instance – PathPilot instance on which cycle start should be executed.

Examples

1 2 pathpilot_cycle_start() pathpilot_cycle_start("left_mill")

robot_command.rpl.pathpilot_mdi(command: str, instance: str = '') -> None

Starts an MDI command on the remote PathPilot instance. If no instance argument is given, the command is executed on the first connected PathPilot instance.

Parameters:

  • command – MDI command to execute.

  • instance – PathPilot instance on which this command shall be executed.

Examples

1 2 pathpilot_mdi("G0 X10") pathpilot_mdi("G1 Y-5 F300", "right_mill")

robot_command.rpl.get_pathpilot_state(instance: str = '') -> str

Returns the current state of a PathPilot instance. If no instance argument is given, the command is executed on the first connected PathPilot instance.

Possible states are:

  • “disconnected” - Instance disconnected

  • “estop” - Emergency stop active

  • “running” - a program is running

  • “ready” - instance is ready to start program

  • “idle” - instance is idle, no program loaded

Parameters:

instance – PathPilot instance on which cycle start should be executed.

Returns:

The current PathPilot state.

Examples

1 2 3 state = get_pathpilot_instance() while get_pathpilot_instance("left_mill") != "ready": sleep(0.1)

robot_command.rpl.set_machine_offset(pose: Union[robot_command.rpl.Pose, str], instance: str = '') -> None

Sets the origin offset for the 3D visualization of the PathPilot remote machine model.

Parameters:

  • pose – Pose to use for the machine offset.

  • instance – Optional machine instance name. If not given, default instance is used.

Examples

1 2 set_machine_offset(p[0,0,0,90,0,0], "instance") set_machine_offset(Pose(x=100)) # sets offset for default instance

Notifications

The TRPL supports interactive user notifications displayed in the robot UI.

robot_command.rpl.notify(message: str, warning: bool = False, error: bool = False, image_path: str = '', timeout: Optional[float] = None) -> None

Creates a popup notification message on the robot UI.

The message argument text is shown to the user.

By default, the message is displayed as informational and thus will not block the program flow. The warning argument shows a warning message, which breaks program flow and can be declined by the operator. The error argument shows a blocking error message, which aborts the program.

The optional image_path argument can be used to display an informational image along with the message

Parameters:

  • message – Message text to display in the popup.

  • warning – Set to true if this message is a warning.

  • error – Set to true if this message is an error message.

  • image_path – Optional path to an image file to displayed in the popup.

  • timeout – Optional timeout in seconds.

Examples

1 2 3 notify("Hello World!") notify("No part found, check the palette.", warning=True) notify("This should not happen.", error=True, image_path="./fatal_error.png")

robot_command.rpl.input(message: str, default: str = '', image_path: str = '') -> float

Creates a popup input dialog on the robot UI.

The message argument text is shown to the user.

The option default argument can be used to set the default input text.

The optional image_path argument can be used to display an informational image along with the message.

Parameters:

  • message – Message text to display in the popup.

  • default – The default input value.

  • image_path – Optional path to an image file to displayed in the popup.

Returns:

User input text or None if cancelled

Examples

1 2 user_input = input("How many parts should be made?", default="5") n = int(user_input)

Program Flow

robot_command.rpl.sleep(secs: float) -> None

robot_command.rpl.pause(optional: bool = False, active: bool = False) -> None

The pause command pauses the program execution. Equivalent to M01 break.

The optional states whether the pause is optional or not. Optional pause can be enabled in the robot UI by the operator.

Parameters:

  • optional – If this pause is optional or not.

  • active – When set to true, this indicates an active pause allowing to operator to jog the program.

Examples

1 2 pause() pause(optional=True)

exit()

The Python builtin exit command instantly aborts the program execution.

Examples

1 exit()

Loops

The TRPL supports all Python statements, including loops.

Examples

1 2 3 4 5 6 # move through 4 points for i range(5): movel(Pose(x=i*0.1)) # wait for a condition while get_digital_in("start") == False: sync()

Conditions

Similarly, conditions are also supported.

Examples

1 2 if get_pathpilot_state() != "ready": notify("PathPilot is not ready", warning=True)

Subprograms

The TRPL supports subprograms / reusable Python functions.

Examples

1 2 3 4 5 def subprogram(): movel(p[0, 100, 0, 0, 0, 0]) def main(): subprogram()

Persistent Parameter Storage

The TRPL supports storing and retrieving Python objects to the persistent parameter store. This is useful if you want to store data between program runs.

robot_command.rpl.set_param(name: str, value: object) -> None

Sets a user parameter to a the defined value.

Parameters:

  • name – Parameter name.

  • value – Value to store.

1 set_param("my_waypoint", waypoint1)

robot_command.rpl.get_param(name: str, default: object = None) -> object

Fetch a stored user parameter.

Parameters:

  • name – Parameter name.

  • default – Default value return if the parameter is not defined.

Returns:

Returns a base Python type, construct rpl types or returns a dict if the parameter is set, else returns the default value.

Examples

1 wp = get_param("my_waypoint", Pose())

Probing

Under development

The probel command is a simple probing cycle:

robot_command.rpl.probel(target: Union[robot_command.rpl.Pose, robot_command.rpl.Joints, str], a: float = 0.5, v: float = 0.1, v_retract: float = 0.1, away: bool = False) -> robot_command.rpl.Pose

Simple probing cycle that returns to the initial pose (regardless of the probe result). The sequence is:

  1. Linear move at specified vel / accel scale towards the target position

  2. Stop at probe contact, error condition, or motion end

  3. Retract to original position

  4. Raise any errors from the cycle, or return the probe result

Parameters:

  • target – end point of probing motion (probe cycle uses movel internally)

  • v – move velocity scaling factor 0.0 - 1.0

  • a – move acceleration scaling factor 0.0 - 1.0

  • v_retract – velocity scaling factor to use during retract phase

  • away – Probe towards work (default) if False, otherwise probe away from work

assumes mode 2/4 for probing, meaning an error will be thrown if it reaches the end without contact. Caller can catch this exception if they want mode 3/5 functionality

Examples

1 contact_pose = probel(probe_goal_pose, a=0.5, v=0.01, v_retract=0.1, away=False)

When called, probel() executes two motions:

movel() towards a target position at specified accelerations scale a (default 0.5), and velocity scale v (default 0.01), stopping when the probe makes contact.

movel() to retract to the original position (at velocity v_retract, default 0.1)

It’s also possible to create custom probing cycles by adding a “probe” keyword to any of the following move commands:

For example, a linear move that expects probe contact would look like this:

1 contact_type, contact_time, contact_joint_positions, contact_pose = movel(probe_goal_pose, probe=2)

The numerical value of the “probe” argument has the following meaning:

probe=2 means look for contact (rising edge), or raise a ProbeFailedError if it reaches the end without making contact, or if the probe is active at the start of the move.

probe=3 is like (2), but reaching the end of the motion is not an error.

probe=4 means look for the probe to break contact (falling edge). It raises a ProbeFailedError if it reaches the end without breaking contact, or if the probe is not active at the start.

probe=5 is like (4), but reaching the end of the motion is not an error.

probe=6 is for retraction. The motion will execute normally with the probe on or off, but if the probe signal gets a rising edge (i.e. retracting from a surface too far and hitting another surface), then it will raise a ProbeUnexpectedContactError

if the probe fails to make contact in mode 3 (or leave contact in mode 5), movel will return “None” instead of a result tuple.

Glossary of Probe Errors

There are several probing-specific errors that are reported as python exceptions. All of them are derived from the ProbeError exception class.

exception robot_command.rpl.ProbeUnexpectedContactError(error_code=None)

exception robot_command.rpl.ProbeContactAtStartError(error_code=None)

exception robot_command.rpl.ProbeFailedError(error_code=None)

Calibration

The robot_command.calibration module contains a few useful functions to write custom calibration programs. Note that these functions must be imported manually.

robot_command.calibration.calculate_tool_offset_4(wp1: robot_command.rpl.Pose, wp2: robot_command.rpl.Pose, wp3: robot_command.rpl.Pose, wp4: robot_command.rpl.Pose) -> robot_command.rpl.Pose

Calculate the XYZ coordinates of the tool offset using 4 waypoints using the center of sphere method.

Parameters:

  • wp1 – Waypoint 1

  • wp2 – Waypoint 2

  • wp3 – Waypoint 3

  • wp4 – Waypoint 4

Returns:

The tool offset pose containing the XYZ tool offset.

robot_command.calibration.calculate_work_offset_3(origin_wp: robot_command.rpl.Pose, x_axis_wp: robot_command.rpl.Pose, y_axis_wp: robot_command.rpl.Pose) -> robot_command.rpl.Pose

Calculates the work offset origin pose based on 3 waypoints that lie on a plane.

The angular unit of all input poses must be in radians.

Parameters:

  • origin_wp – Origin of the plane.

  • x_axis_wp – A waypoint that lies on the X-axis of the plane.

  • y_axis_wp – A waypoint that lies in the direction of the Y-axis of the plane.

Returns:

Origin waypoint of the constructed work offset.

robot_command.calibration.calculate_work_offset_4(origin_wp: robot_command.rpl.Pose, x_axis_wp: robot_command.rpl.Pose, y_axis_wp: robot_command.rpl.Pose, position_wp: robot_command.rpl.Pose) -> robot_command.rpl.Pose

Calculates the work offset origin pose based on 3 waypoints that lie on a plane and one additional waypoint which is used to define the origin location.

The angular unit of all input poses must be in radians.

Parameters:

  • origin_wp – Origin of the plane.

  • x_axis_wp – A waypoint that lies on the X-axis of the plane.

  • y_axis_wp – A waypoint that lies in the direction of the Y-axis of the plane.

  • position_wp – Origin location of the new work offset.

Returns:

Origin waypoint of the constructed work offset.