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.
Contents
Program structureAnchor id1 id1
Supported CommandsSpecial Python Method NamesAnchor id2 id2
Program structurePython StubsAnchor id3 id3
Linear and Angular UnitsAnchor id4 id4
WaypointsAnchor id5 id5
MovementGlobal and Local WaypointsAnchor id6 id6
Work and Tool OffsetsJoints - Waypoint Defined as Joint ConfigurationAnchor id7 id7
Digital I/OPose - Waypoint Defined as PoseAnchor id8 id8
PathPilot RemoteAnchor id9 id9 Setting and getting global waypoints from robot programsAnchor
NotificationsAnchor id10 id10
Program Flowmovej - Joint MoveAnchor id11 id11
Persistent Parameter Storagemovel - Linear MoveAnchor id12 id12
Probingmovec - Circular MoveAnchor id13 id13
CalibrationAnchor id14 id14
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
Info |
---|
New in version 0.1.3. |
Info |
---|
New in version 0.1.4. |
Info |
---|
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.
...
Trajectory ExecutionAnchor id15 id15
Glossary of Move ErrorsAnchor id16 id16
Path BlendingAnchor id17 id17
User and Tool FramesAnchor id18 id18
User FramesAnchor id19 id19
Tool FramesAnchor id20 id20
Digital I/OAnchor id21 id21
PathPilot RemoteAnchor id22 id22
NotificationsAnchor id23 id23
Program FlowAnchor id24 id24
LoopsAnchor id25 id25
ConditionsAnchor id26 id26
SubprogramsAnchor id27 id27
Persistent Parameter StorageAnchor id28 id28
ProbingAnchor id29 id29
Glossary of Probe ErrorsAnchor id30 id30
InterruptsAnchor id31 id31
CalibrationAnchor id32 id32
List of Supported and Deprecated CommandsAnchor id33 id33
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
...
Code Block | ||||
---|---|---|---|---|
| ||||
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
...
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.
Linear and Angular Units
...
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.
...
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 a frame from the world origin, usually located at the robot base. If no offset 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.
...
Anchor robot_command.rpl.get_joint_values robot_command.rpl.get_joint_values robot_command.rpl.
get_joint_values
() -> JointsReturns the current joint values.
Returns: Current joint values.
Examples
Code Block language python linenumbers false 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 frame in the robot UI. When no offset frame is defined, it is assumed that the waypoint is defined in world coordinates.
Work offsets User frames are not enforced at runtime. You still need to use a change_
workuser_
offsetframe()
statement before an offset frame becomes active.
classAnchor robot_command.rpl.Pose robot_command.rpl.Pose robot_command.rpl.
Pose
(x: Union[Number, Quantity] = 0.0, y: Union[Number, Quantity] = 0.0, z: Union[Number, Quantity] = 0.0, a: Union[Number, Quantity] = 0.0, b: Union[Number, Quantity] = 0.0, c: Union[Number, Quantity] = 0.0, frame: str = '')A robot pose consists of XYZ position ABC orientation parameters.
Optionally, an frame frame can be recorded with a waypoint.
Examples
Code Block language python linenumbers false 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.
Anchor robot_command.rpl.Pose.__mul__ robot_command.rpl.Pose.__mul__ __mul__
(other: Pose) -> PoseUse KDL frame multiplication to apply a frame to a pose.
Parameters: other – Other pose.
Returns: New pose object.
Code Block language python linenumbers false 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
Anchor robot_command.rpl.Pose.copy robot_command.rpl.Pose.copy copy
() -> PoseCreates a copy of the pose object.
Returns: A copy of the pose.
staticAnchor robot_command.rpl.Pose.from_kdl_frame robot_command.rpl.Pose.from_kdl_frame from_kdl_frame
(frame: Frame) -> PoseConverts a KDL frame to a pose object.
Parameters: frame – KDL frame.
Returns: New pose object.
staticAnchor robot_command.rpl.Pose.from_list robot_command.rpl.Pose.from_list from_list
(pose_list: List[float]) -> PoseCreates a new pose object from a list of coordinates.
Parameters: pose_list – List of the six coordinates.
Returns: New pose object.
staticAnchor robot_command.rpl.Pose.from_ros_pose robot_command.rpl.Pose.from_ros_pose from_ros_pose
(pose: Union[Pose, PoseStamped]) -> PoseConverts a ROS native pose to a pose object.
Parameters: pose – The ROS stamped pose.
Returns: New pose object.
Anchor robot_command.rpl.Pose.from_ros_units robot_command.rpl.Pose.from_ros_units from_ros_units
(linear_unit: Optional[Union[str, SharedRegistryObject]] = None, angular_unit: Optional[Union[str, SharedRegistryObject]] = 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.
Anchor robot_command.rpl.Pose.inverse robot_command.rpl.Pose.inverse inverse
() -> PoseCreates the inverse of the pose. Useful for calculating frames.
Returns: New pose object.
Anchor robot_command.rpl.Pose.to_kdl_frame robot_command.rpl.Pose.to_kdl_frame to_kdl_frame
() -> FrameConverts the pose object to a KDL frame.
Returns: KDL frame.
Anchor robot_command.rpl.Pose.to_list robot_command.rpl.Pose.to_list to_list
() -> List[float]Convert the pose to a list of the coordinates. :return: List of the six coordinates.
Anchor robot_command.rpl.Pose.to_ros_pose robot_command.rpl.Pose.to_ros_pose to_ros_pose
() -> PoseConverts the pose object to a native ROS pose.
Returns: ROS pose.
Anchor robot_command.rpl.Pose.to_ros_units robot_command.rpl.Pose.to_ros_units to_ros_units
(linear_unit: Optional[Union[str, SharedRegistryObject]] = None, angular_unit: Optional[Union[str, SharedRegistryObject]] = None) -> PoseConverts 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.
Anchor robot_command.rpl.Pose.with_units robot_command.rpl.Pose.with_units with_units
(linear_unit: Optional[Union[str, SharedRegistryObject]] = None, angular_unit: Optional[Union[str, SharedRegistryObject]] = None) -> PoseAdds 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.
Anchor robot_command.rpl.Pose.without_units robot_command.rpl.Pose.without_units without_units
(linear_unit: Optional[Union[str, SharedRegistryObject]] = None, angular_unit: Optional[Union[str, SharedRegistryObject]] = None) -> PoseRemoves 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.
...
Anchor robot_command.rpl.get_pose robot_command.rpl.get_pose robot_command.rpl.
get_pose
(apply_user_frame: bool = True, apply_tool_frame: bool = True) -> PoseReturns 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
Code Block language python linenumbers false current_pose = get_pose()
Setting and getting global waypoints from robot programs
...
Anchor robot_command.rpl.
...
to_
...
local_pose robot_command.rpl.
...
to_
...
anchor
local_pose robot_command.rpl.
setto_
global_waypointrobot_command.rpl.set_global_waypoint robot_command.rpl.
set_global_waypoint
alias of
funct
alias of
funct
robot_command.rpl.
get_global_waypoint
Movement
The robot can be moved using the following move types:
movej - Joint Move
robot_command.rpl.
movej
(target: Union[Pose, Joints], v: float = None, probe: int = 0, velocity_scale: float = 1.0) -> Optional[Tuple[int, Time, Joints, 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.
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 –
local_pose
(global_pose, apply_work_offset: bool = True, apply_tool_offset: bool = True) -> PoseConverts a global pose to a local pose
Parameters: |
|
Returns: | converted local pose |
Examples
Code Block | ||||
---|---|---|---|---|
| ||||
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()
.
Anchor robot_command.rpl.set_global_waypoint robot_command.rpl.set_global_waypoint robot_command.rpl.
set_global_waypoint
alias of
funct
...
Anchor robot_command.rpl.get_global_waypoint robot_command.rpl.get_global_waypoint robot_command.rpl.
get_global_waypoint
alias of
funct
...
Movement
The robot can be moved using the following move types:
movej - Joint Move
...
Anchor robot_command.rpl.movej robot_command.rpl.movej robot_command.rpl.
movej
(target: Union[Pose, Joints], v: float = None, probe: int = 0, velocity_scale: float = 1.0) -> Optional[Tuple[int, Time, Joints, 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: 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 target – target waypoint or joints target
velocity_scale – scale factor for velocity (default is full speed)
noteDeprecated since version 3.1.1: use velocity_scale instead
Returns: 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)
Note Deprecated since version 3.1.1: use velocity_scale instead
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
Code Block language python linenumbers false movej(waypoint_1) movej("global_waypoint_1", velocity_scale=0.6) movej(p[0, 100, 0, 90, 20, 0])
movel - Linear Move
Anchor robot_command.rpl.movel robot_command.rpl.movel robot_command.rpl.
movel
(target: Union[Pose, Joints], a: float = None, v: float = None, probe: int = 0, velocity: Optional[Union[float, Quantity]] = None, accel: Optional[Union[float, Quantity]] = None, accel_scale: float = 0.5, duration: Optional[Union[float, Quantity]] = None, strict_limits: bool = False) -> Optional[Tuple[int, Time, Joints, 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 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
Note Deprecated since version 3.1.1: use velocity instead
a –
move acceleration scaling factor 0.0 - 1.0
Note Deprecated since version 3.1.1: use accel_scale instead
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
Code Block language python linenumbers false movel(waypoint_1) movel("global_waypoint_1", velocity=100) movel(j[0.764, 1.64, 0.741, 0.433, 0.140, 2.74])
movec - Circular Move
Anchor robot_command.rpl.movec robot_command.rpl.movec robot_command.rpl.
movec
(interim: Union[Pose, Joints], target: Union[Pose, Joints], a: float = None, v: float = None, probe: int = 0, velocity: Optional[Union[float, Quantity]] = None, accel: Optional[Union[float, Quantity]] = None, accel_scale: float = 0.5, duration: Optional[Union[float, Quantity]] = None, strict_limits: bool = False) -> Optional[Tuple[int, Time, Joints, Pose]]Circular/Arc move command.
Parameters: interim – interim waypoint
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
Note Deprecated since version 3.1.1: use velocity instead
a –
move acceleration scaling factor 0.0 - 1.0
Note Deprecated since version 3.1.1: use accel_scale instead
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
Code Block language python linenumbers false movec(waypoint_1, waypoint_2)
movef - Free-form Move
Anchor robot_command.rpl.movef robot_command.rpl.movef robot_command.rpl.
movef
(target: Union[Pose, Joints]) -> NoneFree 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.
...
Code Block | ||||
---|---|---|---|---|
| ||||
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.
...
Code Block | ||||
---|---|---|---|---|
| ||||
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.
...
Anchor robot_command.rpl.sync robot_command.rpl.sync robot_command.rpl.
sync
() -> NoneThe sync command is used in wait cycles and to force the execution of queued move commands.
...
User and Tool
...
Frames
The TRPL supports an arbitrary number of named work user and tool offsetsframes. These offsets frames are usually defined in the robot UI, however, can also be set inside a program.
...
User Frames
Anchor robot_command.rpl.change_workuser_offsetframe robot_command.rpl.change_workuser_offsetframe robot_command.rpl.
change_workuser_offset
(*args, **kwargsframe
(name: Optional[str]) -> NoneChange the currently active user frame. If an empty string or
None
is used as the name parameter, the empty user frame world becomes active.Parameters: name – The name of the tool frame to activate or None to disable user frames.
Examples
Code Block language python linenumbers false change_user_frame("table") change_user_frame(None) # disable any active frames
robot_command.rpl.
set_work_offset
(*args, **kwargs) -> None...
Anchor robot_command.rpl.getset_workuser_offsetframe robot_command.rpl.getset_workuser_offsetframe robot_command.rpl.
getset_workuser_offset
(*args, **kwargs) -> Optional[Pose]Anchor robot_command.rpl.work_offset robot_command.rpl.work_offset robot_command.rpl.
work_offset
(*args, **kwargs)
Tool Offsets
Anchor robot_command.rpl.change_tool_offset robot_command.rpl.change_tool_offset robot_command.rpl.
change_tool_offset
(*args, **kwargs) -> NoneAnchor robot_command.rpl.set_tool_offset robot_command.rpl.set_tool_offset robot_command.rpl.
set_tool_offset
(*args, **kwargs) -> Noneframe
(name: str, pose: Optional[Union[Pose, str]] = None, position: Optional[Union[Pose, str]] = None, orientation: Optional[Union[Pose, str]] = None) -> NoneSets a user frame using a pose, position or orientation or clears an frame.
The position and orientation arguments can be combined to overwrite the pose’s position or orientation.
Parameters: name – Name of the user frame
pose – Pose to use for the user frame
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
Code Block language python linenumbers false set_user_frame("table", p[0, 100, 0, 0, 0, 0]) set_user_frame("frame_1", waypoint_2, orientation=Pose(a=90)) set_user_frame("frame_1") # clears frame_1
Anchor robot_command.rpl.get_tooluser_offsetframe robot_command.rpl.get_tooluser_offsetframe robot_command.rpl.
get_tooluser_offset
(*args, **kwargsframe
(name: str) -> Optional[Pose]
...
Digital input/output pins can be accessed via their name or by their number.
Returns the pose of a user frame.
Parameters: name – Name of the user frame.
Returns: Pose of the user frame.
Raises: TypeError – if no user frame with the name is found
Examples
Code Block language python linenumbers false pose = get_user_frame("table")
- code
Anchor robot_command.rpl.user_frame robot_command.rpl.setuser_digital_outframe robot_command.rpl.
setuser_digital_out
(nr_or_name: Union[int, str], state: bool) -> Nonenr_or_name – The number or name of the digital output pin.
state – Set to True or False for on and off.
frame
(pose=None, position=None, orientation=None, world=False)Scoped frame command. Applies a user frame temporarily on top of the currently active user frame.
The scoped frame command can be used to automatically switch the active frame back to a previous state when the scope is left. Scoped frames can be nested. Scoped frames are temporary and do not have a name.
Parameters: pose – The frame pose.
position – A pose from which the position is used for the frame.
orientation – A pose from which the orientation is used for the frame.
world – If set to True the frame is absolute.
Examples
Code Block language python linenumbers false set_digital_out("gripper", True) set_digital_out(2, False)
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
Code Block language python linenumbers false io_state = get_digital_in("gripper") x = get_digital_in(3)
Sets a digital output pin to high or low state.
Parameters: |
Examples
robot_command.rpl.
get_digital_in
(nr_or_name: Union[str, int]) -> bool PathPilot Remote
...
with user_frame(p[0, 100, 0, 90, 20, 0]): # creates a temporary frame and activates it movel(Pose(x=10)) # move x by 10 starting from the frame # the active frame automatically reset when the scope is left
Tool Frames
Anchor robot_command.rpl.pathpilotchange_cycletool_startframe robot_command.rpl.pathpilotchange_cycletool_startframe robot_command.rpl.
pathpilotchange_cycletool_startframe
(instancename: Optional[str = '']) -> NoneStarts a cycle on the remote PathPilot instance. If no instance argument is given, the command is executed on the first connected PathPilot instanceChange the currently active tool frame. If an empty string or
None
is used as the name parameter, the empty tool frame none becomes active.Parameters: instance – PathPilot instance on which cycle start should be executedname – The name of the tool frame to activate or None to disable tool frames.
Examples
Code Block language python linenumbers false pathpilotchange_cycletool_startframe("table") pathpilotchange_cycletool_start("left_mill")frame(None) # disable any active frames
command – MDI command to execute.
Anchor | ||||
---|---|---|---|---|
|
robot_command.rpl.
pathpilotset_tool_mdi
(command: str, instance: str = '') -> NoneStarts an MDI command on the remote PathPilot instance. If no instance argument is given, the command is executed on the first connected PathPilot instance.
frame
(name: str, pose: Union[Pose, str] = None, position: Union[Pose, str] = None, orientation: Union[Pose, str] = None) -> NoneSets a tool frame using a pose, position or orientation or clears an frame.
The position and orientation arguments can be combined to overwrite the pose’s position or orientation.
Parameters: |
|
Examples
Code Block | ||||
---|---|---|---|---|
| ||||
pathpilotset_mdi("G0 X10") pathpilot_mdi("G1 Y-5 F300", "right_mill")tool_frame("some_tool", p[0, 0, 100, 0, 0, 0]) set_tool_frame("other_tool", waypoint_2, position=Pose(z=0.1)) set_tool_frame("other_tool") # clears frame other_tool |
Anchor robot_command.rpl.get_pathpilottool_stateframe robot_command.rpl.get_pathpilottool_stateframe robot_command.rpl.
get_pathpilottool_stateframe
(instancename: str = '') -> strOptional[Pose]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
Code Block language pose of a tool frame.
Parameters: name – Name of the tool frame.
Returns: Pose of the user frame or None if it does not exist.
Raises: TypeError – if no tool frame with the name is found
Examples
Code Block language python linenumbers false statepose = get_pathpilot_instance() while get_pathpilot_instance("left_mill") != "ready": sleep(0.1)tool_frame("tool1")
...
Digital I/O
Digital input/output pins can be accessed via their name or by their number.
Anchor robot_command.rpl.set_machinedigital_offsetout robot_command.rpl.set_machinedigital_offsetout robot_command.rpl.
set_machinedigital_offset
(*args, **kwargsout
(nr_or_name: Union[int, str], state: bool) -> None
...
The TRPL supports interactive user notifications displayed in the robot UI.
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
Code Block language python linenumbers false set_digital_out("gripper", True) set_digital_out(2, False)
...
- Examples
Anchor robot_command.rpl.notifyget_digital_in robot_command.rpl.notifyget_digital_in robot_command.rpl.
notify
(message: str, warning: bool = False, error: bool = False, image_path: str = '', timeout: Optional[float] = None) -> Nonemessage – 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.
get_digital_in
(nr_or_name: Union[str, int]) -> boolReturns 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
Code Block language python linenumbers false io_state = get_digital_in("gripper") x = get_digital_in(3)
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: |
...
PathPilot Remote
The PathPilot remote interface can be used to remotely control a PathPilot instance.
Anchor robot_command.rpl.pathpilot_cycle_start robot_command.rpl.pathpilot_cycle_start robot_command.rpl.
pathpilot_cycle_start
(instance: str = '') -> NoneStarts 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
Code Block language python linenumbers false pathpilot_cycle_start() pathpilot_cycle_start("left_mill")
...
Anchor robot_command.rpl.pathpilot_mdi robot_command.rpl.pathpilot_mdi robot_command.rpl.
pathpilot_mdi
(command: str, instance: str = '') -> NoneStarts 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
Code Block language python linenumbers false pathpilot_mdi("G0 X10") pathpilot_mdi("G1 Y-5 F300", "right_mill")
...
Anchor robot_command.rpl.get_pathpilot_state robot_command.rpl.get_pathpilot_state robot_command.rpl.
get_pathpilot_state
(instance: str = '') -> strReturns 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
Code Block language python linenumbers false state = get_pathpilot_instance() while get_pathpilot_instance("left_mill") != "ready": sleep(0.1)
...
Anchor robot_command.rpl.set_machine_frame robot_command.rpl.set_machine_frame robot_command.rpl.
set_machine_frame
(pose: Union[Pose, str], instance: str = '') -> NoneSets the origin frame for the 3D visualization of the PathPilot remote machine model.
Parameters: pose – Pose to use for the machine frame.
instance – Optional machine instance name. If not given, default instance is used.
Examples
Code Block language python linenumbers false set_machine_frame(p[0,0,0,90,0,0], "instance") set_machine_frame(Pose(x=100)) # sets frame for default instance
...
Notifications
The TRPL supports interactive user notifications displayed in the robot UI.
Anchor robot_command.rpl.notify robot_command.rpl.notify robot_command.rpl.
notify
(message: str, warning: bool = False, error: bool = False, image_path: str = '', timeout: Optional[float] = None) -> NoneCreates 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. Theerror
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 messageParameters: 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
Code Block language python linenumbers false notify("Hello World!") notify("No part found, check the palette.", warning=True) notify("This should not happen.", error=True, image_path="./fatal_error.png")
...
Anchor robot_command.rpl.input robot_command.rpl.input robot_command.rpl.
input
(message: str, default: str = '', image_path: str = '') -> floatCreates 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
Code Block language python linenumbers false user_input = input("How many parts should be made?", default="5") n = int(user_input)
...
Program Flow
...
Anchor robot_command.rpl.sleep robot_command.rpl.sleep robot_command.rpl.
sleep
(secs: float) -> NoneThe sleep command pauses the program execution for
t
seconds.Parameters: secs – sleep time in seconds
Examples
Code Block language python linenumbers false sleep(5.0)
...
Anchor robot_command.rpl.pause robot_command.rpl.pause robot_command.rpl.
pause
(optional: bool = False, active: bool = False) -> NoneThe 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
Code Block language python linenumbers false pause() pause(optional=True)
...
Anchor exit exit exit
()The Python builtin
exit
command instantly aborts the program execution.Examples
Code Block language python linenumbers false exit()
...
Loops
The TRPL supports all Python statements, including loops.
Examples
Code Block | ||||
---|---|---|---|---|
| ||||
# 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
Code Block | ||||
---|---|---|---|---|
| ||||
if get_pathpilot_state() != "ready":
notify("PathPilot is not ready", warning=True) |
Subprograms
The TRPL supports subprograms / reusable Python functions.
Examples
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Anchor robot_command.rpl.set_param robot_command.rpl.set_param robot_command.rpl.
set_param
(name: str, value: object) -> NoneSets a user parameter to a the defined value.
Parameters: name – Parameter name.
value – Value to store.
Code Block language python linenumbers false notifyset_param("Hello World!") notify("No part found, check the palette.", warning=True) notify("This should not happen.", error=True, image_path="./fatal_error.png"my_waypoint", waypoint1)
Anchor robot_command.rpl.inputget_param robot_command.rpl.inputget_param robot_command.rpl.
input
get_param
(messagename: str, default: str = '', image_path: str = '' object = None) -> floatobjectCreates 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
ExamplesFetch 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
Code Block language python linenumbers false wp = get_param("my_waypoint", Pose())
...
Anchor robot_command.rpl.delete_param robot_command.rpl.delete_param robot_command.rpl.
delete_param
(name: str) -> NoneRemoves a user parameter
Parameters: name – Parameter name to delete
Code Block language python linenumbers false user_input = input("How many parts should be made?", default="5") n = int(user_input)
...
delete_param("my_waypoint")
Probing
Warning |
---|
Under development |
The probel
command is a simple probing cycle:
...
Anchor robot_command.rpl.sleepprobel robot_command.rpl.sleepprobel robot_command.rpl.
sleep
(secs: float) -> NoneAnchor robot_command.rpl.pause robot_command.rpl.pause robot_command.rpl.
pause
(optionalprobel
(target: Union[Pose, Joints, str], a: float = 0.5, v: float = 0.1, v_retract: float = 0.1, away: bool = False, activecheck_retract_contact: bool = False) -> NoneThe 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
Code Block language python linenumbers false pause() pause(optional=True)
The Python builtin
exit
command instantly aborts the program execution.Examples
Code Block language python linenumbers false exit()
exit
() Loops
- Pose
Simple probing cycle that returns to the initial pose (regardless of the probe result). The sequence is:
Linear move at specified vel / accel scale towards the target position
Stop at probe contact, error condition, or motion end
Retract to original position
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
check_retract_contact – Optionally check for contacts during retract move (to avoid retracting into an obstacle and breaking a probe tip)
Info 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
Code Block language python linenumbers false
...
contact_pose
...
Conditions
Similarly, conditions are also supported.
Examples
= probel(probe_goal_pose, a=0.5, v=0.01, v_retract=0.1, away=False, check_retract_contact=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:
Code Block | ||||
---|---|---|---|---|
| ||||
if get_pathpilot_state() != "ready":
notify("PathPilot is not ready", warning=True) |
Subprograms
The TRPL supports subprograms / reusable Python functions.
Examples
Code Block | ||||
---|---|---|---|---|
| ||||
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.
...
Sets a user parameter to a the defined value.
Parameters: |
|
...
language | python |
---|---|
linenumbers | false |
...
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
Info |
---|
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.
exceptionAnchor robot_command.rpl.get_paramProbeUnexpectedContactError robot_command.rpl.get_paramProbeUnexpectedContactError robot_command.rpl.
get_param
(name: str, default: objectProbeUnexpectedContactError
(error_code=None) -> objectFetch 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
Code Block language python linenumbers false wp = get_param("my_waypoint", Pose())
Probing
Warning |
---|
Under development |
...
exceptionAnchor robot_command.rpl.ProbeContactAtStartError robot_command.rpl.ProbeContactAtStartError robot_command.rpl.
ProbeContactAtStartError
(error_code=None)
...
exceptionAnchor robot_command.rpl.ProbeFailedError robot_command.rpl.ProbeFailedError robot_command.rpl.
ProbeFailedError
(error_code=None)
...
Interrupts
The TRPL supports interrupts from external sources. This is useful for example to abort a program when a button connected to a digital input pin is pressed or to react to a message received from a ROS topic.
classAnchor robot_command.rpl.probelInterruptSource robot_command.rpl.probelInterruptSource robot_command.rpl.
probel
(target: Union[Pose, Joints, str], a: float = 0.5, v: float = 0.1, v_retract: float = 0.1, away: bool = False, check_retract_contact: bool = False) -> PoseLinear move at specified vel / accel scale towards the target position
Stop at probe contact, error condition, or motion end
Retract to original position
Raise any errors from the cycle, or return the probe result
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
check_retract_contact – Optionally check for contacts during retract move (to avoid retracting into an obstacle and breaking a probe tip)
InterruptSource
(value)Interrupt source type.
DigitalInput: React to a change on a digital input pin.
UserIo: React to a change on a user IO pin. (triggered by HAL)
Program: React to a program interrupt. (e.g. a ROS topic)
Simple probing cycle that returns to the initial pose (regardless of the probe result). The sequence is:
Parameters: |
...
Anchor robot_command.rpl.register_interrupt robot_command.rpl.register_interrupt robot_command.rpl.
register_interrupt
(source: InterruptSource, nr_or_name: Union[int, str], fct: Callable) -> NoneRegisters a interrupt function to an interrupt source.
Parameters: source – The interrupt source type.
nr_or_name – Number or name of the interrupt source, e.g. 1 for Digital Input 1.
fct – The function which should be called when the interrupt is triggered, if None is passed, this unregisters and disables the interrupt.
Examples
Code Block language python linenumbers false contact_pose = probel(probe_goal_pose, a=0.5, v=0.01, v_retract=0.1, away=False, check_retract_contact=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:
...
def interrupt_handler(value): if value: exit() # exit program when digital input 1 is high register_interrupt(InterruptSource.DigitalInput, 1, interrupt_handler)
Anchor robot_command.rpl.trigger_interrupt robot_command.rpl.trigger_interrupt robot_command.rpl.
trigger_interrupt
(nr: int, value: Any) -> NoneTriggers a program interrupt.
Parameters: nr – Program interrupt number which should be triggered.
value – Value which is passed along with the triggered interrupt.
Examples
Code Block language python linenumbers false
...
trigger_
...
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
Info |
---|
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.
...
Calibration
The robot_command.calibration
module contains a few useful functions to write custom calibration programs. Note that these functions must be imported manually.
...
Calculate the XYZ coordinates of the tool frame 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 frame pose containing the XYZ tool frame.
Calculates the user frame 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 user frame.
Calculates the user frame 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 user frame.
Returns: Origin waypoint of the constructed user frame.interrupt(2, 342.34)
robot_command.calibration.
calculate_tool_frame_4
(wp1: Pose, wp2: Pose, wp3: Pose, wp4: Pose) -> Pose robot_command.calibration.
calculate_user_frame_3
(origin_wp: Pose, x_axis_wp: Pose, y_axis_wp: Pose) -> Pose robot_command.calibration.
calculate_user_frame_4
(origin_wp: Pose, x_axis_wp: Pose, y_axis_wp: Pose, position_wp: Pose) -> PoseCalibration
The robot_command.calibration
module contains a few useful functions to write custom calibration programs. Note that these functions must be imported manually.
Anchor | ||||
---|---|---|---|---|
|
Anchor robot_command.calibration.calculate_tool_frame_4 robot_command.calibration.calculate_tool_frame_4 robot_command.calibration.
calculate_tool_frame_4
(wp1: Pose, wp2: Pose, wp3: Pose, wp4: Pose) -> PoseCalculate the XYZ coordinates of the tool frame 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 frame pose containing the XYZ tool frame.
...
Anchor robot_command.calibration.calculate_user_frame_3 robot_command.calibration.calculate_user_frame_3 robot_command.calibration.
calculate_user_frame_3
(origin_wp: Pose, x_axis_wp: Pose, y_axis_wp: Pose) -> PoseCalculates the user frame 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 user frame.
...
Anchor robot_command.calibration.calculate_user_frame_4 robot_command.calibration.calculate_user_frame_4 robot_command.calibration.
calculate_user_frame_4
(origin_wp: Pose, x_axis_wp: Pose, y_axis_wp: Pose, position_wp: Pose) -> PoseCalculates the user frame 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 user frame.
Returns: Origin waypoint of the constructed user frame.
...
List of Supported and Deprecated Commands
Info |
---|
New in version 0.1.3. |
Info |
---|
New in version 0.1.4. |
Info |
---|
New in version 0.2.2. |
Info |
---|
New in version 3.0.0. |
Info |
---|
New in version 3.0.2. |
Info |
---|
New in version 3.0.5. |
Info |
---|
New in version 3.1.1. |
Note |
---|
Deprecated since version 3.0.2. |
set_work_offset()
set_tool_offset()
get_work_offset()
get_tool_offset()
change_work_offset()
change_tool_offset()
set_machine_offset()
work_offset()