Actin®  Version 5.1.0
Software for Robotics Simulation and Control
Motion Library and EcScript

Table of Contents

Introduction

Motion Library and EcScript provide motion primitives, sequences, and a scripting interface for controlling manipulators. The EcScript adopts LISP-like syntax. An EcScript is a list of command token, parameters, and EcScripts:

<motion_script> := ([COMMAND_TOKEN] [<parameter> ...] [<motion_script> ...])

Script commands are handled by corresponding classes, which are all derived from EcMotionScriptObject. Parameters are literals/variables of various types supported by EcScript (see the next section).

There are two ways to use the motion library and EcScript:

The relationship between EcScript, EcMotionScriptObject, and EcBaseControlSystemModifier is illustrated below:

EcScriptObjectModifier.png
The relationship between EcScript, EcMotionScriptObject, and EcBaseControlSystemModifier.

The design concept of the motion planning library is there should be no dynamic memory allocation during runtime of an EcScript.

Variable Types

EcScript supports the following basic types:

EcScript basic types.
Baic Type Description Example
Unsigned Integer (u32) Used for manipulator index, end-effector set index, loop counter, etc. BASE, 0, 0x2
Boolean (bool) Used for condition, digital IO, etc. TRUE, FALSE
Double precision floating-point (real) Used for tolerance, speed factor, etc. 1.0, 1e-3
Note
BASE is a built-in U32 constant that equals to EcFoundCommon::BASEINDEX.

EcScript also supports the following compound types:

EcScript compound types.
Compound Type Description Example
Translation (trans) A list of 3 real values. Used for 3D point. (0.0 1.0 2.0)
Orientation (rot) A list of 3 real values (roll-pitch-yaw using EcOrientation::setFrom123Euler) or 4 real values (quaternion in w-x-y-z). (0.0 1.57 1.57) or (1 0 0 0)
Pose (pose) A list of translation and orientation. Used for pose or coordinate transformation. ((0 0 0.1) (0 1.57 0))
Real vector (real_vec) A list of real values. Usually used for joint position or velocities. (0.1 0.2 0.3 0.4 0.5 0.6)
U32 vector (u32_vec) A list of U32 values. Usually used for link indices. (BASE 0 1 2 3 4 5)

For the real value or the real values in the compound types, users can specify the unit and they can be mixed together. By default, Actin always uses meter and radian internally. By appending a unit to the end of a real value, EcScript parser will multiply the value with corresponding coefficients.

Note
EcScript does NOT check if the provided type of the unit has correct physical meaning. For example, using "rad" and "deg" in translation or using "m" and "mm" in orientation are still valid. The value will simply be multiplied with corresponding coefficients.

The following units are supported:

EcScript units.
Unit Type Description Example
meter (m) This is the default unit for length. (0.0m 1.0 2.0m)
millimeter (mm) The value will be multiplied with 10^-3. (0.0m 1.0mm 2.0mm)
radian (rad) This is the default unit for angle. (0.0 1.57rad 3.14rad)
degree (deg) The value will be multiplied with pi/180. (0.0 1.57rad 180deg)

Motion Primitives

Move Joint

This command is handled by EcEndEffectorMotionMoveJoint. Command format:

1 (move_joint <manip_id:u32> [<ee_set_id:u32> <ee_id:u32>] <cmd_joints:real_vec> <speed_factor:real> <tolerance:real>)

move_joint moves the manipulator of index <manip_id> in joint space to <cmd_joints> with speed factor <speed_factor>. The command returns succeeded if the difference calculated by EcCoordinatedJointEndEffector::difference is smaller than <tolerance>. If the <ee_set_id> and <ee_id> are not provided, the command will use the first end-effector in the joint control end-effector set by default. If the <ee_set_id> and <ee_id> are provided, the set must exist and the end-effector of that set must be a joint control end-effector. Or the command will fail or not run correctly.

Example:

1 (move_joint 0 (0.0 45.0deg 60.0deg 0.0 -90.0deg 0.0) 1.0 1e-3)

Move Pose

Move pose moves the robot in Cartesian space of the end effector. This command is handled by EcEndEffectorMotionMovePose.

Command format:

1 (move_pose <manip_id> <ee_set_id> <ee_id> <cmd_pose> <speed_factor> <blend_r>)

Example command:

1 (move_pose 0 0 0 ((-0.3 0.0 0.6) (0.0 0.0 0.0)) 1.0 0.001)

This command moves the position of Robot 0 to pose (-0.3m 0m 0.6m 0deg 0deg 0deg) with maximum speed with tolerance 0.001.

Speed

Speed moves the robot with joint space or end-effector space velocity if [<ee_set_id> <ee_id>] are provided. This command is handled by EcEndEffectorMotionSpeed.

Command format:

1 (speed <manip_id> [<ee_set_id> <ee_id>] <cmd_speed> <tolerance>)

Example command:

1 (speed 0 (10deg 10deg 10deg 10deg 10deg 10deg) 0.001)

This command drives the joint velocity of Robot 0 to (10deg/s 10deg/s 10deg/s 10deg/s 10deg/s 10deg/s).

Example command:

1 (speed_pose 0 1 0 (0 0.02 0 30deg -5deg 0) 0.001)

This command drives the end-effector velocity of Robot 0 to (0m/s 0.02m/s 0m/s 30deg/s -5deg/s 0deg/s) using End-effector Set 1.

Stop

Stop motion stops the robot using velocity control. This command is handled by EcEndEffectorMotionStop.

Command format:

1 (stop <manip_id> [<ee_set_id>] <tolerance>)

If the <ee_set_id> is not provided, stop will automatically use the current end-effector set. If the <ee_set_id> is provided, the set must exist or the motion will fail.

Example command:

1 (stop 0 0.001)

This command stops the motion of Robot 0. The tolerance to judge whether the robot has stopped is 0.001.

Pose Sequence

Pose sequence moves the robot with a sequence of Cartesian space position commands of end effector. The pose sequence uses Bezier curves to blend between poses. This command is handled by EcEndEffectorMotionMovePoseSequence.

Command format:

1 (pose_seq <manip_id> <ee_set_id> <ee_id>
2  (move_pose ...) [(move_pose ...)] ...
3 )

The sequence is able to include more than one via poses. Via poses are added by appending move_pose commands.

Example command:

1 (pose_seq 0 1 0
2  (move_pose 0 1 0 ((0.1 -0.3 0.1) (0.0 0.0 90.0deg)) 0.3 0.03)
3  (move_pose 0 1 0 ((0.1 -0.4 0.1) (0.0 0.0 90.0deg)) 0.5 0.03)
4  (move_pose 0 1 0 ((0.0 -0.4 0.1) (0.0 0.0 90.0deg)) 0.5 0.03)
5  (move_pose 0 1 0 ((0.0 -0.3 0.1) (0.0 0.0 90.0deg)) 0.3 0.001)
6 )

This command moves the position of Robot 0 with a sequence of Cartesian space commands. It first use 30% speed to move it to (0.1m -0.3m 0.1m), Euler angles (0.0deg 0.0deg 90.0deg) with blending radius 0.03m, then use 50% speed to move it to (0.1m -0.4m 0.1m), then move it to (0.0m -0.4m 0.1m) and finally move it to (0.0m -0.3m 0.1m) with 0.001 tolerance.

On a Cyton Gamma-1500, the path looks like:

MotionScriptPoseSequence.png
The path of a sample pose_seq command.

Move Circular

Circular interpolation. This command is handled by EcEndEffectorMotionMoveCircular.

Command format 1: The first format uses <via_point> and <goal_point> [and <goal_orientation>] to define the arc.

1 (move_circular <manip_id> <ee_set_id> <ee_id>
2  <via_point> <goal_point> [<goal_orientation>]
3  <speed_factor>)

Example command:

1 (move_circular 0 1 0
2  (0.0 -0.3 0.17)
3  (0.0 -0.25 0.05) (0 0 90deg) 0.1)

Command format 2: The second format uses <center_point>, <normal_vec>, <arc_length> [and <goal_orientation>] to define the arc.

1 (move_circular <manip_id> <ee_set_id> <ee_id>
2  <center_point> <normal_vec> <arc_length> [<goal_orientation>]
3  <speed_factor>)

In both formats, if the <goal_orientation> is provided, move_circular will interpolate orientation from the start to the <goal_orientation>. Otherwise, the orientation will be calculated by rotating the start orientation about the circle normal.

On a UR5, given the goal orientation, the path looks like:

MotionScriptMoveCircular.png
The path of a sample move_circular command with given goal orientation.

Without a goal orientation, the path looks like:

MotionScriptMoveCircular_1.png
The path of a sample move_circular command without goal orientation.

Move Linear

Linear interpolation. This command is handled by EcEndEffectorMotionMoveLinear. The difference between this command and move_pose is:

Command format:

1 (move_linear <manip_id> <ee_set_id> <ee_id> <cmd_pose> <speed_factor>)

Interpolated Pose Sequence

Interpolated pose sequence moves the TCP through a sequence of linear motions and circular motions with desired speed limits configured by speed factors. This command is handled by EcEndEffectorMotionInterpolatedPoseSequence. This command uses a look ahead algorithm to maximize the feedrate within speed and acceleration limits.

Command format:

1 (interp_pose_seq <manip_id> <ee_set_id> <ee_id>
2  [(move_linear ...)]
3  [(move_circular ...)]
4  ...
5 )

Example command:

1 (interp_pose_seq 0 1 0
2  (move_linear 0 1 0 ((-150mm 350mm 100mm)(-180deg 0 0)) 0.1)
3  (move_circular 0 1 0 (-150mm 400mm 100mm) (0 0 1) 90deg 0.1)
4  (move_linear 0 1 0 ((-100mm 500mm 100mm)(0 -90deg -180deg)) 0.1)
5  (move_circular 0 1 0 (-100mm 500mm 50mm) (1 0 0) -90deg 0.1)
6  (move_linear 0 1 0 ((-100mm 550mm 0mm)(0 -90deg -180deg)) 0.1)
7 )

On a UR5, the path looks like:

MotionScriptInterpolatedPoseSequence.png
The path of a sample interp_pose_seq command.

Set Active Control Description

Set the active control description of a manipulator. This command is handled by EcManipulatorMotionSetActiveControlDescription.

Command format:

1 (set_acd <manip_id> <acd_id>)

Example command:

1 (set_acd 0 1)

This command set control description 1 as active control description of manipulator 0.

Set Active Position Control Method

Set the active position control method index for a manipulator. This command is handled by EcManipulatorMotionSetActivePositionControlMethod.

Command format:

1 (set_apcm <manip_id> <apcm_id>)

Example command:

1 (set_apcm 0 1)

This command set control method 1 as active position control method of manipulator 0.

Set Base Speed Factor

Set the base speed factor of a manipulator. This command is handled by EcManipulatorMotionSetBaseSpeedFactor.

Command format:

1 (set_bsp <manip_id> <speed_factor>)

Set Sensed State

Set the sensed state of a manipulator. This command is handled by EcManipulatorMotionSetSensedState.

Command format 1:

1 (set_sensed_state <manip_id> <base_pose> <joint_positions>)

Command format 2:

1 (set_sensed_state <manip_id> <base_pose>)

Command format 3:

1 (set_sensed_state <manip_id> <joint_positions>)

Set Tool Offset

Set the tool offset (TCP) of an end effector. This command is handled by EcEndEffectorMotionSetTcp.

Command format:

1 (set_tcp <manip_id> <ee_set_id> <ee_id> <pose>)

Example command:

1 (set_tcp 0 0 0 ((0.1 0.0 0.0) (0.0 0.0 0.0)))

Attach/Detach Manipulator

To attach a manipulator (dependent) to a link of another manipulator (independent) with the offset calculated using the current state so that the dependent manipulator moves with independent manipulator:

1 (attach_manip <dependent_manip_id> <independent_manip_id> <link_id>)

Example command:

1 (attach_manip 1 0 5)

This will attach manipulator 1 to link 5 of manipulator 0 at the current state, i.e. manipulator 1 will not move after attachment.

To attach a manipulator to a link of another manipulator with a given ofset:

1 (attach_manip <dependent_manip_id> <independent_manip_id> <link_id> <offset>)

Note that offset is a pose.

Example command:

1 (attach_manip 1 0 5 ((0.1 0.0 0.0) (0.0 0.0 0.0)))

This will attach manipulator 1 to link 5 of manipulator 0 with the offset of 0.1 m in X direction. The offset is between the primary frames of link 5 of manipulator 0 and the base link of manipulator 1. This will potentially move manipulator 1 after attachment.

To attach a manipulator to a link of another manipulator such that a named frame of on the base link of the dependent manipulator is aligned with a named frame on the link of the independent manipulator:

1 (attach_manip <dependent_manip_id> <dependent_named_frame> <independent_manip_id> <link_id> <independent_named_frame>)

Example command:

1 (attach_manip 1 "gripper" 0 5 "gripper")

This will attach manipulator 1 to link 5 of manipulator 0 such that the "gripper" named frame on the base link of manipulator 1 is aligned with the "gripper" named frame on link 5 of manipulator 0 and . This will potentially move manipulator 1 after attachment.

To attach a manipulator to a link of another manipulator such that a named frame of on the base link of the dependent manipulator is offseted with a named frame on the link of the independent manipulator:

1 (attach_manip <dependent_manip_id> <dependent_named_frame> <independent_manip_id> <link_id> <independent_named_frame> <offset>)

Example command:

1 (attach_manip 1 "gripper" 0 5 "gripper" ((0.1 0.0 0.0) (0.0 0.0 0.0)))

This will attach manipulator 1 to link 5 of manipulator 0 with the offset of 0.1 m in X direction. The offset is between the "gripper" named frame the base link of manipulator 1 and the "gripper" named frame on link 5 of manipulator 0 and . This will potentially move manipulator 1 after attachment.

These commands are handled by EcManipulatorMotionAttachManipulator. For the base link, use BASE. If the attachment results in a chain, this command will return failed.

To detach:

1 (detach_manip <dependent_manip_id>)

This command is handled by EcManipulatorMotionDetachManipulator. If the dependent manipulator is not currently attached to any manipulator, this command will return failed.

Exclude/Include Collision

To exclude/include collision check between a manipulator and everything else:

1 (exclude_collision/include_collision <manip_id_0>)

To exclude/include collision check between two manipulators:

1 (exclude_collision/include_collision <manip_id_0> <manip_id_1>)

To exclude/include collision check between a manipulator and links of another manipulator:

1 (exclude_collision/include_collision <manip_id_0> <manip_id_1> <link_indices>)

where, <link_indices> is a U32 vector.

To exclude/include collision check between a link of a manipulator and links of another manipulator:

1 (exclude_collision/include_collision <manip_id_0> <link_id> <manip_id_1> <link_indices>)

RRT Path Planning and Execution

Plan a path in joint space using RRT. If a feasible path is found, execute this path. There is also an option to cache the planned path. This command is handled by EcManipulatorMotionRrtPlan.

Command format:

1 (rrt_plan <manip_id> <target_joints> [(<param0_name> <param0_value>) ...])

The command will try to find a path in the joint space that connect the manipulator's (<manip_id>) current position to the target position (<target_joints>). If a feasible path is found, this path will be executed; otherwise, return failed.

Several parameters can be set to further control the planning and the execution. These parameters are optional. For some parameters, if they are absent, default values will be used. For the others, if they are absent, the functionalities won't be used. As shown in the command format, the parameters have to be at the end of the command, but the order within is flexible.

List of Parameters.
Parameter Name Description If Absent
MaxTime Maximum planning time in seconds. 5.0 (default value)
CollisionThreshold Collision threshold in work space in meters during planning. 0.001 (default value)
SpeedFactor Speed factor used in execution. 1.0 (default value)
Tolerance Tolerance used in execution. 0.001 (default value)
AccelerationFactor Acceleration factor used in execution. Acceleration factor won't be used.
CachePath Name of the cached path, and threshold for assertion. Path caching won't be used.

Extra note for path caching While the other parameters need only one <param_value>, there has to be two <param_value>s following CachePath. The first one is the name of the cached path. The command will convert the path into an EcScript string of a series move_joint commands, and will store it into the data map with this name. The second one is the threshold of an assertion. It's only safe to execute the cached path when the robot is near the start position where the planner starts. (Also assume that the environment hasn't change since then.) So an assertion_approx_eq command is inserted before those move_joint commands. And the cached path will be executed, only when the Euclidean distance of the joint positions, where the path is executed, and the joint positions, where the path starts, are smaller than this threshold.

Example command:

1 (rrt_plan 0 (-1.46939 -0.443042 -2.13076 -1.39414 1.56981 -0.190602)
2  (MaxTime 20.0) (CollisionThreshold 0.01)
3  (Tolerance 0.001) (SpeedFactor 0.5) (AccelerationFactor 1.0)
4  (CachePath "path" 0.005)
5 )

Find Joint Solution from an End Effector Set Placement

Given placements of an end effector set, try to find a joint solution. This command is handled by EcMotionScriptFindSolution.

Command format:

1 (find_solution <manip_id> <ee_set_id> <solution_symbol>
2  (<target_place_0> [<target_place_1> ...])
3  [(<param0_name> <param0_value>) ...])

The command will try to find a joint solution for a manipulator (<manip_id>), given the target placement (<target_place_0>...) of an end effector set (<ee_set_id>). If a feasible joint solution is found, save the result to the solution real vector symbol (<solution_symbol>); otherwise, return failed. A placement should be a mix of pose and real vector variables inside a pair of parentheses.

Example command 1:

1 (motion_seq
2  (def_real_vec rv0 ())
3 
4  (find_solution 0 1 rv0
5  ((-1.4 -0.4 -2.1 -1.4 1.6 -0.2)
6  ((2.0 0.3 -0.8) (1 0 0 0))
7  )
8  )
9 )

Example command 1 shows a script that trys to find a joint solution for manipulator 0. The target placement is for end effector set 1, and it is a mix of real vector and pose, corresponding to the definition of the end effector set. If a feasible joint solution is found, the result will be stored in symbol 'rv0'.

List of Parameters.
Parameter Name Description Default Value
CollisionThreshold Collision threshold in work space in meters. 0.001
AttachPlacement End effector set placement at attachment. N/A
AttachExclusion A vector of manipulator indexes, each pair of which is excluded from collision checking at attachment. N/A

Several parameters can be set to further control the solution finding process. These parameters are optional; if the collision threshold is absent, the default value will be used. As shown in the command format, the parameters have to be at the end, but the order within is flexible.

Example command 2:

1 (motion_seq
2  (def_real_vec rv0 ())
3  (def_pose approach ((0 0 -0.01)(1 0 0 0)))
4  (def_pose attach ((0 0 0.01)(1 0 0 0)))
5  (def_pose part (get_frame 6 BASE))
6 
7  (find_solution 0 1 rv0 ((* part approach))
8  (AttachPlacement ((* part attach)))
9  (AttachExclusion (1 6))
10  )
11 )

Example command 2 shows a script that trys to find a joint solution for manipulator 0, given placements of end effector set 1. The target placement is at the 'approach' pose, which is 0.01m backward along the 'part' base frame's z axis. The command also need validate that the 'attach' pose, which is 0.01m forward along the 'part' base frame's z axis, is reachable. The 'AttachExclusion' gives a set of manipulators, each pair of which is excluded from collision checking during the 'attach' validation. If this 'attach' pose is not reachable, the command will return failed.

Container

Motion Script Sequence

A motion script sequence is a vector of motion scripts that run sequentially. This command is handled by EcMotionScriptSequence.

Command format:

1 (motion_seq <motion_script> [<motion_script>] ...)

Motion Script Parallel

A motion script parallel is a vector of motion scripts that run parallelly. Note that motion_para can be included in motion_seq and vice versa to achieve complex logic. This command is handled by EcMotionScriptParallel.

Command format:

1 (motion_para <motion_script> [<motion_script>] ...)

Variable Definition, Assignment, Assertion and Print

The following commands can define variables of various types. They can ONLY be used within a container. The name of the variable must start with a letter and consist of only letters, numbers, and '_', and cannot be the same as any built-in motion script commands.

A variable is only visible after its definition and within its container, and cannot be defined twice.

Define Boolean

Command format:

1 (def_bool <var_name> <bool>)

Define U32

Command format:

1 (def_u32 <var_name> <u32>)

Define U32 Vector

Command format:

1 (def_u32_vec <var_name> <u32_vec>)

Define Real

Command format:

1 (def_real <var_name> <real>)

Define Real Vector

Command format:

1 (def_real_vec <var_name> <real_vec>)

Define Translation

Command format:

1 (def_trans <var_name> <translation>)

Define Orientation (Rotation)

Command format:

1 (def_rot <var_name> <rotation>)

Define Pose

Command format:

1 (def_pose <var_name> <pose>)

Example command:

1 (motion_seq
2  (def_trans v0 (0.788 -0.032 0.034))
3  (def_rot r0 (0 0 105))
4  (def_pose p0 (v0 r0))
5  (move_pose 0 0 0 p0 1.0 0.001)
6 )

Define String

Command format:

1 (def_string <var_name> <string>)

Assign New Value

Once a variable is defined, it can be assigned a new value. The new value must be of the same type of the variable. Or there will be a parse error.

Command format:

1 (:= <var_name> <new_value>)

Assert Approximate Equal

This command asserts whether the Euclidean distance of two real vectors is smaller than the threshold. It succeeds, only when the two real vectors have the same dimension, and the distance is small than the threshold.

Command format:

1 (assert_approx_eq <real_vec1> <real_vec2> <threshold>)

Print Variables

The print script can print any number of variables to the console window. "\n" will be printed automatically at the end of each print.

Command format:

1 (print <variable> [<variable>...])

Example command:

1 (motion_seq
2  (def_bool b TRUE)
3  (def_trans t (0 1 2))
4  (print "b = " b)
5  (print "t = " t)
6 )

If a console window is open, the output should be:

MotionScriptPrintVariable.png
Console window output of printing variables.

Data Storage

The first two sections include commands can store/lookup different kinds of variables in/from the data map. And the commands in the third section are used to get/set digital inputs/outputs.

Store(Set) Variables

Set U32 to Data Map

Command format:

1 (set_dm_u32 <var_name> <var_u32>)

Example command:

1 (set_dm_u32 "u0" 100)

This command will store a u32 variable named "u0" to the data map, with a value of 100.

Set U32 Vector to Data Map

Command format:

1 (set_dm_u32_vec <var_name> <var_u32_vec>)

Set Real to Data Map

Command format:

1 (set_dm_real <var_name> <var_real>)

Set Real Vector to Data Map

Command format:

1 (set_dm_real_vec <var_name> <var_real_vec>)

Set String to Data Map

Command format:

1 (set_dm_string <var_name> <var_string>)

Lookup(Get) Variables

Get Real from Data Map

Please see Get Real from Data Map.

Get Real Vector from Data Map

Please see Get Real Vector from Data Map.

Get U32 from Data Map

Please see Get U32 from Data Map.

Get U32 Vector from Data Map

Please see Get U32 Vector from Data Map.

Get String from Data Map

Please see Get String from Data Map

Digital Inputs/Outputs

Set Digital Input

Command format:

1 (set_di <board_id> <var_u32>)

Set Digital Output

Command format 1:

1 (set_do <board_id> <var_u32>)

Command format 2:

1 (set_do <board_id> <channel_id> <var_bool>)

Get Digital Input

Please see Get Digital Input.

Type-Specific Script

The following commands can only be used where certain type is expected and cannot be used stand-alone.

Boolean

Get Digital Input

Command format:

1 (get_di <board_id> <port_id>)

Example command:

1 (motion_seq
2  (def_bool b_0_31 (get_di 0 31))
3 )

This script will create a boolean variable b_0_31 with initial value the digital input of Board 0 Port 31.

Get Hit Joint Limit Flag

This script gets the hit joint limit flag given the manipulator index. If any joint of the manipulator hits joint limit, this script will return TRUE.

Command format:

1 (hit_joint_limit <manip_id>)

Comparison Operators

Less Than: <

Command format:

1 (< <var_u32> <var_u32>)
Note
This command only supports U32 variables, for now.

Greater Than: >

Command format:

1 (> <var_u32> <var_u32>)
Note
This command only supports U32 variables, for now.

Not Equal: !=

Command format:

1 (!= <var_u32> <var_u32>)
Note
This command only supports U32 variables, for now.

Logic Operators

Logic AND: &&

Command format:

1 (&& <var_bool> <var_bool> [<var_bool> ...])

Example command:

1 (motion_seq
2  (def_bool b0 (&& (< 1 2) (< 3 2) (get_di 0 31)))
3 )

After running this script, b0 will be FALSE. Also since (< 3 2) is false, the third command get_di will not be evaluated.

Logic OR: ||

Command format:

1 (|| <var_bool> <var_bool> [<var_bool> ...])

Logic NOT: !

Command format:

1 (! <var_bool>)

Orientation

Get Orientation from Pose

Command format:

1 (get_rot <var_pose>)

This command is used to extract the orientation part from a pose variable.

Transformation

Command format:

1 (* <var_rot> <var_rot> [<var_rot> ...])

This command multiplies the orientations in the argument list.

Inverse

Command format:

1 (inv <var_rot>)

This command calculate the inverse of the given orientation.

Pose

Get Frame

This command can be used to get the primary frame or a named frame from any link of a manipulator or a named frame from the EcManipulatorSystem in the world frame.

To get a named frame from the EcManipulatorSystem:

1 (get_frame <frame_name>)

Example command:

1 (motion_seq
2  (def_pose p0 (get_frame "p0"))
3 )

This command will get the named frame "p0" from EcManipulatorSystem. If the named frame does not exist, it will return failed.

To get the primary frame of a link of a manipulator:

1 (get_frame <manip_id> <link_id>)

The <link_id> is the index of the link. For the base link, use BASE.

Example command:

1 (motion_seq
2  (def_pose p0 (get_frame 0 BASE))
3 )

This command will get the primary frame of the base link of Manipulator 0. If the manipulator index or the link index does not exist, it will return failed.

To get a named frame from a link of a manipulator:

1 (get_frame <manip_id> <link_id> <frame_name>)

Example command:

1 (motion_seq
2  (def_pose p0 (get_frame 0 5 "tool_attachment"))
3 )

This command will get the named frame "tool_attachment" from Link 5 of Manipulator 0. If the manipulator index or the link index or the named frame does not exist, it will return failed.

Inverse

Command format:

1 (inv <var_pose>)

This is command inverts <var_pose>.

Transformation

Command format:

1 (* <var_pose> <var_pose> [<var_pose> ...])

This command multiplies the poses in the argument list which is equivalent to pose transformation.

Example command:

1 (motion_seq
2  (def_pose p0 (get_frame 0 ""))
3  (def_pose p1 (get_frame 1 ""))
4  (def_pose p2 (* (inv p0) p1))
5 )

This command gets the base primary frame of Robot 0 in the world frame to p0 and the base primary frame of Robot 1 in the world frame to p1. It then calculates \( p2 = p0 ^ {-1} p1 \) which is the base primary frame of Robot 1 in the base primary frame of Robot 0 and stores it to p2.

Convert Real Vector to Pose

Command format:

1 (real_vec_to_pose <var_real_vec>)

This command is used to convert a real vector into a pose.

Note
Only the real vector with a size of 7 can be converted into a pose.

Real

Get Real from Data Map

Command format:

1 (get_dm_real <var_name>)

This command is used to get a real from the data map by <var_name>.

Example command:

1 (motion_seq
2  (def_real r0 (get_dm_real "r0"))
3 )

This command will get the real named "r0" from data map; this will return failed, if the named real does not exist.

Real Vector

Get Real Vector from Data Map

Command format:

1 (get_dm_real_vec <var_name>)

This command is used to get a real vector from the data map by <var_name>.

Example command:

1 (motion_seq
2  (def_real_vec rv0 (get_dm_real_vec "rv0"))
3 )

This command will get the real vector named "rv0" from data map; this will return failed, if the named real vector does not exist.

Get Current Joint Positions

Command format:

1 (get_joint_positions <manip_id>)

This command is used to get the current joint positions of manipulator <manip_id>.

Example command:

1 (motion_seq
2  (def_real_vec rv0 (get_joint_positions 5))
3 )

This command will get the joint positions of manipulator 5; this will return failed, if manipulator 5 does not exist.

Translation

Get Translation from Pose

Command format:

1 (get_trans <var_pose>)

This command is used to extract the translation part from a pose variable.

Convert Real to Translation

Command format:

1 (real_to_trans <index> <var_real>)

This command is used to convert <var_real> into a translation variable, whose direction is based on <index>. If <index> is 0, 'x' or 'X', the output is along x axis; if <index> is 1, 'y' or 'Y', the output is along y axis; if <index> is 2, 'z' or 'Z', the output is along z axis; otherwise, this command returns failed.

Example command:

1 (motion_seq
2  (def_trans t0 (real_to_trans 2 1.23))
3 )

After running this script, t0 will be (0 0 1.23), which is along the z axis.

Convert Real Vector to Translation

Command format:

1 (real_vec_to_trans <var_real_vec>)

This command is used to convert <var_real_vec> into a translation variable.

Multiplication of Translation

Command format for scalar multiplication:

1 (* <var_real> <var_trans>)

Command format for orientation multiplication:

1 (* <var_rot> <var_trans>)

Command format for pose multiplication:

1 (* <var_pose> <var_trans>)

This command is used to calculate multiplication between a real (or rotation, or pose) variable and a translation variable.

Dot Product of Translation

Command format:

1 (dot <var_trans> <var_trans>)

This command is used to calculate the dot product between two translation varibles.

Cross Product of Translation

Command format:

1 (cross <var_trans> <var_trans> [<var_trans> ...])

This command is used to calculate the cross product of multiple translation varibles.

Note
Only the real vector with a size of 3 can be converted into a translation.

U32

Get U32 from Data Map

Command format:

1 (get_dm_u32 <var_name>)

This command is used to get a u32 from the data map by <var_name>.

Get U32 Vector from Data Map

Command format:

1 (get_dm_u32_vec <var_name>)

This command is used to get a u32 vector from the data map by <var_name>.

Example command:

1 (motion_seq
2  (def_u32_vec uv0 (get_dm_u32_vec "uv0"))
3 )

This command will get the U32 vector named "uv0" from data map; this will return failed, if the named real vector does not exist.

Get String from Data Map

Command format:

1 (get_dm_string <var_name>)

This command is used to get a string from the data map by <var_name>.

Example command:

1 (motion_seq
2  (def_string str0 (get_dm_u32_vec "str0"))
3 )

This command will get the string named "str0" from data map; this will return failed, if the named real vector does not exist.

Get Manipulator Index

Command format:

1 (get_manip_id <manip_label>)

This command is used to get manipulator index by <manip_label>.

Example command:

1 (motion_seq
2  (def_u32 u0 (get_manip_id "primary_arm_right")
3 )

If the manipulator named "primary_arm_right" exists, u0 will be its index; otherwise returns failed.

Arithmetic Operators

Add: +

Command format:

1 (+ <var_0> <var_1> [<var_2> ...])
Note
This command now supports Real, Translation and U32 variables.

Example command:

1 (motion_seq
2  (def_bool b0 (< (+ 1 1) 2))
3 )

After running this script, b0 will be FALSE.

Subtract: -

Command format:

1 (- <var_0> [<var_1> ...])
Note
If only <var_0> available, the substraction is the same with negate operation. This command now supports Real, Translation and U32 variables.

Multiply: *

Command format:

1 (* <var_0> <var_1> [<var_2> ...])
Note
This command only supports Real and U32 variables. Please refer to vector variable for multiplication operation of translation variables.

Divide: /

Command format:

1 (/ <var_0> [<var_1> ...])
Note
This command only supports Real variables.

Control Logic

if

The if command will check the condition first, and if it is true, it will run <motion_script>. Otherwise, it will run <else_motion_script> if it is provided.

Command format:

1 (if <condition>
2  <motion_script>
3  [<else_motion_script>]
4 )

Example command:

1 (if (get_di 0 31)
2  (move_joint 0 (0 0 90deg 0 0 0) 1.0 0.001)
3  (move_joint 0 (0 0 0 0 0 0) 1.0 0.001)
4 )

This script will check digital input Board 0, Port 31. If it is high, move the joints to (0 0 90deg 0 0 0), otherwise, move the joints to (0 0 0 0 0 0).

while

The while command starts a while-loop by checking the condition first, and if it is true, it will run <motion_script>, and then start another loop until the condition is false.

Command format:

1 (while <condition>
2  <motion_script>
3 )

Example command:

1 (motion_seq
2  (def_u32 ii 0)
3  (while (< ii 10)
4  (motion_seq
5  (move_joint 0 (0 0 90deg 0 0 0) 1.0 0.001)
6  (move_joint 0 (0 0 0 0 0 0) 1.0 0.001)
7  (:= ii (+ ii 1))
8  )
9  )
10 )

This script will move the joints to (0 0 90deg 0 0 0) then to (0 0 0 0 0 0) and repeat the motion for 10 times.

wait

Command format:

1 (wait <time:real>)

This command is used to suspend motion script for <time> seconds. If <time> is less than or equal to 0, the motion script will not be suspended.

Comment

Use # to lead a line of comment.

Example:

1 # A motion sequence
2 (motion_seq
3  # Home
4  (move_joint 0 (0 0 0 0 0 0) 1.0 0.001)
5  # Third joint goes to 30 deg
6  (move_joint 0 (0 0 30deg 0 0 0) 1.0 0.001)
7 )
Created by Energid Technologies www.energid.com
Copyright © 2016 Energid. All trademarks mentioned in this document are property of their respective owners.