Tormach Robot Programming Language

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.

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.

   from robot_command.rpl import *  # import all robot commands
   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

Special Python Method Names

The following Python method names have a special meaning in the TRPL interpreter:

main: The robot programs main loop. Required in every program.
on_abort: Called when the program is aborted as a result of an error or controlled exit by the operator.
on_pause: Called when the program is paused.

The on_abort and on_pause methods are useful for disabling digital outputs or cleaning up initialized resources. If an error occurs in the on_pause method on_abort will be called as a fallback. If an error occurs in the on_abort method the program will exit instantly.

Python Stubs

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

To use them, install the robot_command-stubs package by issuing the python3 setup.py install command.

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

Sets the active linear, angular and time units for the program.

Parameters:

linear – Linear/length unit type: m, mm, inch
angular – Angular/rotation unit type: deg, rad
time – Time unit type: s, min, h

Examples

set_units("mm", "deg", "s")
set_units(linear="in")
set_units(angular="rad")
set_units(time="s")

robot_command.rpl.get_units(with_time: bool = False) -> Tuple[str, str] | Tuple[str, str, str]

Returns the active linear, angular and time units from the program.

Parameters:	time – return the time unit type when set to True
Returns:	Linear/length unit type, angular/rotation unit type and time unit type

Examples

linear, angular = get_units()
linear, angular, time = get_units(with_time=True)

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 a frame from the world origin, usually located at the robot base. If no frame 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

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

copy() -> Joints

Creates a copy of the joints object.

Returns:

Copy of the joints object.

static from_list(joint_list: List[float]) -> Joints

Creates a new joint object from a list of joint positions.

Parameters:	joint_list – List of the six joint positions.
Returns:	New joints object.

from_ros_units(angular_unit: str | SharedRegistryObject | None = None)

Converts the joints object from native ROS units to the target units, removing the unit type if any.

Parameters:	angular_unit – Unit type for the angular joint positions.
Returns:	The resulting joints object.

to_list() -> List[float]

Convert the joints object to a list of joint positions.

Returns:

List of the six joint positions.

to_ros_units(angular_unit: str | SharedRegistryObject | None = None) -> Joints

Converts the joints object to native ROS units, removing the unit type if any. This is useful if you want to send the resulting data to a ROS service.

Parameters:	angular_unit – Unit type for the angular joint positions.
Returns:	The resulting joints object.

with_units(angular_unit: str | SharedRegistryObject | None = None) -> Joints

Adds a unit type to all positions of the joints object. The defaults are the native ROS units. In case a joint position already has units, the unit type is converted accordingly.

Parameters:	angular_unit – Unit type for the angular joint positions.
Returns:	The resulting joints object.

without_units(angular_unit: str | SharedRegistryObject | None = None) -> Joints

Removes units from the joint positions if any. If no unit type is specified ROS units are assumed.

Parameters:	angular_unit – Unit type for the angular joint positions.
Returns:	The resulting joints object.

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 or the j() shortcut which supports keyword arguments.

Examples

waypoint_1 = j[0.764, 1.64, 0.741, 0.433, 0.140, 2.74]
waypoint_2 = j(j3=0.543) # all other joint positions are 0.0 by default

robot_command.rpl.get_joint_values() -> Joints

Returns the current joint values.

Returns:

Current joint values.

Examples

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 frame in the robot UI. When no frame is defined, it is assumed that the waypoint is defined in world coordinates.

User frames are not enforced at runtime. You still need to use a change_user_frame() statement before an frame becomes active.

A robot pose consists of XYZ position ABC orientation parameters.

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

Examples

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.

__mul__(other: Pose) -> Pose

Use KDL frame multiplication to apply a frame to a pose.

Parameters:	other – Other pose.
Returns:	New pose object.

new_wp = Pose(x=10) * waypoint_1 # translates waypoint_1 by x=10
old_wp = Pose(x=10).inverse() * new_wp # translates new_wp back

copy() -> Pose

Creates a copy of the pose object.

Returns:

A copy of the pose.

static from_kdl_frame(frame: Frame) -> Pose

Converts a KDL frame to a pose object.

Parameters:	frame – KDL frame.
Returns:	New pose object.

static from_list(pose_list: List[float]) -> Pose

Creates a new pose object from a list of coordinates.

Parameters:	pose_list – List of the six coordinates.
Returns:	New pose object.

static from_ros_pose(pose: Pose | PoseStamped) -> Pose

Converts a ROS native pose to a pose object.

Parameters:	pose – The ROS stamped pose.
Returns:	New pose object.

from_ros_units(linear_unit: str | SharedRegistryObject | None = None, angular_unit: str | SharedRegistryObject | None = None)

Converts the pose from native ROS units to the target units, removing the unit type.

Parameters:	linear_unit – Unit type for linear coordinates. angular_unit – Unit type for angular coordinates.
Returns:	The resulting pose.

inverse() -> Pose

Creates the inverse of the pose. Useful for calculating frames.

Returns:

New pose object.

to_kdl_frame() -> Frame

Converts the pose object to a KDL frame.

Returns:

KDL frame.

to_list() -> List[float]

Convert the pose to a list of the coordinates. :return: List of the six coordinates.

to_ros_pose() -> Pose

Converts the pose object to a native ROS pose.

Returns:

ROS pose.

to_ros_units(linear_unit: str | SharedRegistryObject | None = None, angular_unit: str | SharedRegistryObject | None = None) -> Pose

Converts the pose to native ROS units, removing the unit type if any. This is useful if you want to send the resulting data to a ROS service.

Parameters:	linear_unit – Unit type for linear coordinates. angular_unit – Unit type for angular coordinates.
Returns:	The resulting pose.

with_units(linear_unit: str | SharedRegistryObject | None = None, angular_unit: str | SharedRegistryObject | None = None) -> Pose

Adds a unit type to all coordinates of the pose. The defaults are the native ROS units. In case a coordinate already has units, the unit type is converted accordingly.

Parameters:	linear_unit – Unit type for linear coordinates. angular_unit – Unit type for angular coordinates.
Returns:	The resulting pose.

without_units(linear_unit: str | SharedRegistryObject | None = None, angular_unit: str | SharedRegistryObject | None = None) -> Pose

Removes units from the coordinates if any. If no unit type is specified ROS units are assumed.

Parameters:	linear_unit – Unit type for linear coordinates. angular_unit – Unit type for angular coordinates.
Returns:	The resulting pose.

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 or the p() shortcut which supports keyword arguments.

Examples

waypoint_1 = p[202.73, 750.08, 91.75, 6.63, 53.21, "table"]  # captured with table user frame
waypoint_2 = p(y=10.0, frame="table")  # all other coordinate values are 0.0 per default.

robot_command.rpl.get_pose(apply_user_frame: bool = True, apply_tool_frame: bool = True) -> Pose

Returns the current robot pose.

Parameters:	apply_user_frame – Applies the active user frame to the world pose. apply_tool_frame – Applies the active tool frame to the world pose.
Returns:	Current robot pose.

Examples

current_pose = get_pose()

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

Converts a global pose to a local pose

Parameters:	global_pose – Global workspace Pose to convert to local coordinates (based on specified arguments) apply_work_offset – Applies the active work offset apply_tool_offset – Applies the active tool offset
Returns:	converted local pose

Examples

local_pose = to_local_pose(global_pose)
work_only_pose = to_local_pose(global_pose, apply_tool_offset=False)

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 funct

robot_command.rpl.get_global_waypoint

alias of funct

Movement

The robot can be moved using the following move types:

movej - Joint Move

robot_command.rpl.movej(target: Pose | Joints, v: float = None, probe: int = 0, velocity_scale: float = 1.0) -> Tuple[int, Time, Joints, Pose] | None

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 waypoint or joints target
velocity_scale – 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
v –
scale factor for velocity (default is full speed)

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

movej(waypoint_1)
movej("global_waypoint_1", velocity_scale=0.6)
movej(p[0, 100, 0, 90, 20, 0])

movel - Linear Move

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 waypoint
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
velocity – move velocity as absolute value, interpreted in terms of currently set machine units if quantity without units is given.
accel – move acceleration as absolute value, interpreted in terms of currently set machine units if quantity without units is given.
accel_scale – move acceleration scaling factor 0.0 - 1.0
duration – target move duration in seconds. If move duration based on other inputs is longer, the planned duration will be used.
strict_limits – Enforces strict limits. Moves violating the velocity and acceleration limits will error.
v –
move velocity scaling factor 0.0 - 1.0
a –
move acceleration scaling factor 0.0 - 1.0

Tormach Robot Programming Language

Contents