Simple Scripting Example

What you will learn

In this section you will learn about EcScipt and how to use it to control manipulators in ActinViz.


Programming EcScript

At this point, you should have three processes running:

  1. actinUrRcf (Actin Robot Control Framework)
  2. actinViz (Actin Visualization)
  3. URSim (Univeral Robots Simulator)

It should look like this:

URSim and ActinViz

ActinViz is divided into pages, with each page having specialized set of controls. The list below shows the 3D Model page of the Actin Viz UI.

3D Model Page in ActinViz
3D Model Page in ActinViz
  1. 3D Model Page - Display the simulated robot. Run scripts from here.
  2. Scripting Page - Load and edit scripts.
  3. Render Bounding Volumes - Show/Hide
  4. Render Axis Overlay - Show/Hide
  5. Camera View Reset
  6. RCF Connection Page - Connect to ActinRCF
  7. Robot Connection Page - Connect to UR robot controller
  8. Select Script File - Choose script file to run
  9. Speed Slider - Adjust the play speed
  10. Play/Pause Button - Affects script playback
  11. Stop Button - Stops script playback
  12. Mode Selection - Sim: Simulation, Servo: live robot control; Free: free drive manual move robot
  13. Script Output Tab - Display printed output from the running script.

Let's jump right into writing some EcScript to make the UR5e move. Click on the Scripting Page (left navigation bar)

Script Page Toolbar

These are the options available on the top tool bar on the Scripting Page:

  1. Open File
  2. New File
  3. Save File
  4. Save File As
  5. Script Command Options

Tip: A new default script is loaded with a print statement for "hello world".

Save the script by pressing the Save As button and name the file HelloWorld.ecs.

Select the 3D Model Page and the UR5e model render should appear.

Let's load the script you just created. On the bottom left in ActinViz, click on the folder icon, then select the previously saved file HelloWorld.ecs.

Change the Mode Selection to Sim on the bottom right. Click the Play Button.

Note: This can be done in Servo, but we suggest that you always check your script in Sim mode first.

Expand the Script Output tab (bottom right) by clicking it and you should see a "hello world" print message.

Move Joint

Actin Docs : move_joint

Let's go back to the Scripting Page and command the joints of the UR5e. We will command the robot joints to a desired placement. Paste the following script into the tab:

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

The first 0 after the move_joint command is the robot manipulator index. In this system control executive, there is only 1 robot, so the index is 0. The next part is a vector of reals (0.0 45.0deg 60.0deg 0.0 -90.0deg 0.0). The suffix deg indicates degrees. Otherwise the units are radians. Every number in the vector is a command of desired placement of the joint. The first number 0.0 corresponds to the first joint of the UR5e. The second, which is 45deg corresponds to the second joint of the robot. The rest follows respectively. The (1.0 1.0) tuple contains the speed factor and acceleration factor, respectively. Lastly, 1e-3 is the tolerance.

To make the code more readable, let's assign variables in the script instead of hard-coding the move_joint arguments:


    # Manipulator Index
    (def_u32 manip_idx 0)

    # Vector of reals for joint positions
    (def_real_vec desired_joints (0.0 -60.0deg -120.0deg -90deg 90.0deg 0.0))

    # Speed Factor
    (def_real speed_factor 1.0)

    # Acceleration Factor
    (def_real accel_factor 1.0)

    # Tolerance
    (def_real tolerance 1e-3)

    (move_joint  manip_idx desired_joints (speed_factor accel_factor) tolerance)

Tip: Assigning variables makes it easier to read and allows them to be used elsewhere in the program.

Save As SimpleMoveJoint1.ecs

Go back to the 3D Model Page, select SimpleMoveJoint1.ecs, and click the Play Button. The robot's final pose should be like this:

Let's have the robot move back to the home position. The joint angles are:

(def_real_vec home_joints (0.0 -90.0deg -90.0deg -90deg 90.0deg 0.0))

Run the motion command again, this time with the home_joints argument:

(move_joint  manip_idx home_joints (speed_factor accel_factor) tolerance)
Move Pose

Actin Docs: move_pose

While move_joint controls the joint angles direction we often want to position the end-effector (EE) and let Actin figure out the joint angles. This is referred to as Inverse Kinematics (IK). The move_pose command wil move the robot's end effector to a known pose in Cartesian space.

Here's the basic move_pose command:

    (move_pose 0 1 0 ((-.013 -.152 .510) (-.316 .632 -.632 .316)) (1.0 1.0) 1e-06)

Let's look at the arguments:

0 0 0 :  (manipulator_index  end_effector_set_index  end_effector_index)

This model is created so that the end_effector_set_index is the constrained as a Frame End-Effector Set. Having a Frame End-Effector means the end effector will obey all 6 degrees-of-freedom motion, which gives it no extra degree of freedom for motion optimization. The effector index for this model is Wrist3 of the UR53, so the constraint will ba applied to this link (the last link). and it was configured to have the motion constraint on Wrist3 of the UR5e.

((-.013 -.152 .510) (-.316 .632 -.632 .316)) : ((x y z) (w x y z))

The pose (above) represents a translation in (x y z) and a rotation as a quaternion (w x y z).

(1.0 1.0) : (speed_factor  acceleration_factor)

1e-3 :  end position tolerance

Actin will continue to keep solving until the position (and orientation) are within the tolerance.

Paste the following script into the editing panel on the Scripting Page:

    # Manipulator Index
    (def_u32 manip_idx 0)

    # Motion Constraint Set
    (def_u32 motion_constraint_set 1)

    # Motion Constraint
    (def_u32 motion_constraint 0)

    # Desired Pose
    (def_pose desired_pose ((-.013 -.152 .510) (-.316 .632 -.632 .316)))

    # Speed Factor
    (def_real speed_factor 1.0)

    # Acceleration Factor
    (def_real accel_factor 1.0)

    # Tolerance
    (def_real tolerance 1e-3)

  (move_pose manip_idx motion_constraint_set motion_constraint  desired_pose (speed_factor accel_factor) tolerance)

Go back to the 3D Model Page, select SimpleMovePose1.ecs, and click the Play Button.

The move_pose command should leave the UR5e in this state:

Please refer to our documentation here for more information about EcScript.

Next: Collision Maps