External Axis with UR arm (v6.2.1)

What you will learn

Note: This tutorial uses the new Actin Viewer design, found in Actin 6.2.1 and later releases.

In this section, you will understand the workflow of integration of an external axis with UR arm, A Robotics Gearbox inspection system is built by extending the UR3 arm to 7-DOF by adding a rotational axis. This tutorial will take you through the process of creating a simulation with Actin Viewer. A separate tutorial (integrating hardware) will demonstrate how to interface to external actuators.

Prequisites

The tutorial we will outline the procedure to add an external axis to a Universal Robots arm. The aim is to build a gearbox inspection system using the UR3 arm. The gearbox on which inspection points are predefined will be mounted on a turntable which can rotate ±360°deg and an Intel RealSense camera mounted on the UR3 wrist will be used to inspect. Coordinated motion sequences are used to inspect the gearbox at multiple inspection points.

In brief, there are three sections: Model Setup, Control System Configuration, and Motion Scripting. The example focuses on simulation mode only, Actin RCF & hardware interface are not covered by this tutorial.

1. Model setup

The tutorial package externalAxisDemo.zip has all the Actin (.ecz) files needed to build this simulation. The package contains:

  • Inspection Table (InspectionTable.ecz) – Table on which the UR3 and turntable are mounted.
  • UR3 Arm model (UR3e.ecx) – Robotic arm to hold the camera.
  • Intel RealSense camera model (realSenseCamera.ecz) – Mounted on the UR3 as inspection tool.
  • Turntable model (Turntable.ecz) - Turntable on which the Gearbox is mounted.
  • Gear Box (GearBox.ecz) – Object to be inspected.

All the models have been converted to Actin format (.ecz) from SolidWorks files. SolidWorks model conversion to Actin format is covered in a separate tutorial.

Model setup involves the following steps:

  1. Fine tune the collision bounding volumes of the manipulators – turntable, gearbox & camera.
  2. Import model files (components): Start with the inspection table Actin file (.ecz) in ActinViewer and the import the UR3e model and the turntable model.
  3. Attachments: Attach the robot & turntable to inspection table and combine the turn table with the robot arm as an external axis.
  4. Attach camera to robot wrist.
  5. Attach gearbox to turntable.
  6. Mount the system on an inspection table.

1.1 Bounding volumes

Actin control system uses bounding volumes that are composed of primitive shapes like box, capsule, lozenge, cylinder etc. for internal collision calculations. The first step is ensuring the manipulators have proper bounding volumes. Use the Model : System : Bounding Volume option to create these from basic shape primitive objects provided by Actin. All the manipulator links should be tightly covered by bounding volumes. Try avoiding shapes like box & cone which are calculation intensive due to their sharp endges. All the models included in the training package have proper bounding volumes.

1.2 Import the Inspection table and Turntable

Let's start building the simulation now. Open the file inspectionTable.ecz in ActinViewer. The table has Named Frames which are used to position the arm and the turntable. Model : System : Named Frames will bring up the dialog to render the frames.

Now import the files UR3e.ecz and Turntable.ecz using Model : System : Import Manipulators into the simulation file. Next, attach the robot to the inspection table for placement using the Model : Configuration : Attachments tool. Add an attachment, set the

Dependent manipulator : robot
Base Manipulator : InspectionTable
Named Frame : PORT_UR3e. 
Yaw : 1.5708 rad.

For the turntable do the same thing, but use PORT_GEARBOX as the Named Frame and orient in Yaw with –1.5708 rad.

1.3 Combining Turntable with UR3

Load the manipualtorCombinationPlugin using Menu : Load Plugin (you can search by typing a partial file name, such as 'manip').

Click the Combine tool (Model Tab, System section of the tool bar), Then set the following:

Dependent Manip : TurnTableBase
Base Manipulator : robot 
Base Link : Mounting [BASE]

Click Use Current to keep the current positions intact.

Click Preview Offset & then Combine.

The combining operation add the turntable as a link to the robot arm and it then becomes part of the kinematic chain, Now click the Model : State : State icon on menu bar to view the joint ranges and settings on the robot. We should now see Turntable as a link after Wrist3 for the robot manipulator.

At this point save the simulation file using Menu : Save As

1.4 Attaching Camera & Gearbox

Click Model : System : Import Manpulator and select the realsenseCamera.ecz file.

This will import the camera into ActinViewer. By default, the model will be placed at the origin.

Click Model : Configuration : Manipulator Attachments which will open the Edit Manipulator Attachments dialog box.

Click the [+] button to add an attachment. The panel below appears. Set the following:

Dependent Manipulator : RealSenseEndEffector
Base Manipulator : robot
Base Link : Wrist3 

The camera will be attached to UR3 Wrist. The orientation and the offset can be tuned if needed.

Similarly import Gearbox.ecz and follow the same steps to attach Gearbox to the turntable:

 Dependent Manipulator : Gearbox
 Base Manipulator : robot
 Base Link : Turntable 
 Named Frame : Mount
 Roll : 1.5708 rad

It might seem a bit strange to attach the gearbox to the robot. But recall that the turntable is now part of the robot as an external axis.

1.5 Excluding Collision Detection Cases

We want to adjust the collision map so that objects that are in constant contact with each other are disregarded during collision detection.

Model : System : Static Collision exclude the following:

  • InspectionTable -> robot: Mounting [BASE]

  • RealSenseEndEffector-Manipulator –> robot: Wrist1, Wrist2, Wrist3

  • GearBox-Manipulator -> robot: Mounting [BASE], TurnTable

  • GearBox-Manipulator -> InspectionTable-Manipulator

At this point, save the simulation file using File -> Save As

2. Control System & Motion Constraints updates

Actin by default enables the control for all the manipulators in the simulation. This should be turned off for the objects which are not manipulated. For example, the table and the camera are not under direct motion control. Click Control : Position Control System and uncheck the Is On checkbox for the Inspection Table, RealSenseEndEffector & GearBox objects.

2.1 Manual process for control system update

The control system for the robot will now have the merged constraints from robot and the turntable. We need remove the uncesseary extra constraints and add relative motion constraints to coordinate motion of turntable with UR3 wrist.

Clean Up the Merged Motion Constraints

When combining two manipulators, the motion constraint sets are also combined. This leads to unnecessary (duplicated) motion constraints which need to be cleaned up. The names of the joint control (default) motion constraint sets are changed to "-1".

Control : Control System, select robot and delete the following items from the right lower panel:

  • Motion constraint set 5
  • -1

Rename the Control Description in left panel (named -1) to something meaningful, such as ControlSystemDesc.

We will add three Motion constraint sets

  • Frame End Effector relative to Turntable
  • FreeSpinInZ End Effector relative to Turntable
  • Coordinated Joint Motion Constraint with a linear constraint on turntable
Edit the Frame End Effector External Motion Constraint
  • Click Control : Contraints
  • Select Wrist3 [0] in Frame End-Effector set External
  • Set Select Link to Wrist3
  • Set Relative to Link as Turntable

Edit the FreeSpinInZ Edit-Effector Set External Constraint
  • Select FreeSpinInZ End-Effector Set External
  • Set Select Link to Wrist3
  • Set Relative link to Turntable
  • Click Apply

Create a Coordinated Joint Motion Constraint
  • Right-click on robot [1] -> Add Motion Constraint Set

This will create a New Motion Constraint Set

  • Right-click on this new set and choose Add Motion Constraint.

Set the following values:

  • Set Select Link to Mounting
  • Set Type to coordinatedJointEndEffector
  • Set Links field to a list of named links : Base,Shoulder,Elbow,Wrist1,Wrist2,Wrist3
  • Update the Max Velocites to 3.14159,3.14159,3.14159,6.28318,6.28318,6.28318
  • Update Accelerations to 40,40,40,40,40,40,5

Right-click and Add Motion Constraint to the same set and

  • Set Select Link to TurnTable
  • Set Type to linearConstraintEndEffector
  • Tune the Max. Constraint Velocity : 2.5,
  • Max. Constraint Acceleration : 5
  • Max. Constraint Deceleration : 5

2.2 Loading control system file

The tuned control System file (robotControlSystem.xml) is provided with the training package and can be imported, click

Control : Control System, select the robot from Manipulator list. Click Import and then select the robotControlSystem.xml file. This will populate the control system with required motion constraint sets.

For reference, the final simulation file after model tuning is also provided in the traning package. Look for file: UR3WithTurnTable.ecz

3. Motion Scripting

The training package includes couple of motion scripts, which show the typical inspection sequence.

Click Simulation : Script and open the files to run the scripts

  1. moveTurntable.ecs shows the simple path planning using RRT.
(motion_seq
  # Robot manipulator index in stated system
  (def_u32 ROBOT_MANIP (get_manip_id "robot"))

  # Robot Joints (constraint 0) and Turntable (constraint 1) motion constraint set (for ROBOT_MANIP)
  (def_u32 RJT_CONSTRAINT_SET 4)

  # move to home position
  (def_real_vec homeJoints (-90deg -80deg -70deg -90deg -250deg 300deg 0deg))
  (def_string plannedPath "")
  (rrt_plan ROBOT_MANIP homeJoints plannedPath
    (CollisionThreshold 0.001) (MaxTime 20.0) (SpeedFactor .4) (AccelerationFactor .1) (Tolerance 0.001)
  )
  (if (!= (size_of plannedPath) 0)
    (motion_seq
      (print "Moving along planned path to home.")
      (eval plannedPath)
    )
    (motion_seq
      (print "Failed to find path to home.")
      (return)
    )
  )

  # loop forever moving between two positions...
  (while TRUE
    (wait 1)

    (motion_para
      (move_joint ROBOT_MANIP RJT_CONSTRAINT_SET 0 (-90deg -80deg -70deg -90deg -250deg 300deg) 0.5 1e-6)
      (move_pose ROBOT_MANIP RJT_CONSTRAINT_SET 1 ((0 0 0) (0 0 0)) 1 1e-3)
    )

    (wait 1)

    (motion_para
      (move_pose ROBOT_MANIP RJT_CONSTRAINT_SET 1 ((0 0 4) (0 0 0)) 1 1e-3)
      (move_joint ROBOT_MANIP RJT_CONSTRAINT_SET 0 (-180deg -51deg -75deg -124deg -300deg 155deg) 0.5 1e-6)
    )

    (wait 1)
  )
)
  1. inspectGearCase.ecs - Uses the Relative frame motion constraint to inspect the gearbox at multiple inspection points defined as Named Frames. The script moves to each of these inspection points.
(motion_seq
  # Manipulator indices in stated system
  (def_u32 ROBOT_MANIP (get_manip_id "robot"))
  (def_u32 GEARBOX_MANIP (get_manip_id "GearBox"))
  (def_u32 CAMERA_MANIP (get_manip_id "RealSenseEndEffector"))

  # Link indices of Robot manipulator in stated system
  (def_u32 WRIST3_LINK 5)
  (def_u32 TURNTABLE_LINK 6)

  # Frame motion constraint set (for ROBOT_MANIP)
  (def_u32 FRAME_CONSTRAINT_SET 2)

  # Set the tool center point (TCP) to the camera pose
  (def_fun SetTcpToCamera ((def_string cameraFrameName))
    (def_pose wrist3Pose (get_frame ROBOT_MANIP WRIST3_LINK))
    (def_pose cameraPose (get_frame CAMERA_MANIP BASE cameraFrameName))
    (def_pose cameraPoseInWrist3 (* (inv wrist3Pose) cameraPose))

    (set_tcp ROBOT_MANIP FRAME_CONSTRAINT_SET 0 cameraPoseInWrist3)
  )

  # move to inspect a point at the named frame (direct move, not planned)
  (def_fun InspectTurntableFrame ((def_string frameName))
    (def_pose framePose (get_frame GEARBOX_MANIP BASE frameName))
    (:= framePose (* framePose ((0 0 .1)(0 0 0))))
    (def_pose turntablePose (get_frame ROBOT_MANIP TURNTABLE_LINK))
    (def_pose framePoseInTurntable (* (inv turntablePose) framePose))

    (move_pose ROBOT_MANIP FRAME_CONSTRAINT_SET 0 framePoseInTurntable (.4 .1) 1e-06)
  )

  # plan a path to move to the inspection point at the named frame
  (def_fun InspectTurntableFrameWithRRT ((def_string frameName))
    (def_pose framePose (get_frame GEARBOX_MANIP BASE frameName))
    (:= framePose (* framePose ((0 0 .1)(0 0 0))))
    (def_pose turntablePose (get_frame ROBOT_MANIP TURNTABLE_LINK))
    (def_pose framePoseInTurntable (* (inv turntablePose) framePose))

    (print "Planning path to '" frameName "' frame...")

    (def_real_vec goalJoints ())
    (def_string plannedPath "")
    (find_solution ROBOT_MANIP FRAME_CONSTRAINT_SET goalJoints (framePoseInTurntable))
    (rrt_plan ROBOT_MANIP goalJoints plannedPath
      (CollisionThreshold 0.001) (MaxTime 20.0) (SpeedFactor .4) (AccelerationFactor .1) (Tolerance 0.001)
    )

    (if (!= (size_of plannedPath) 0)
      (motion_seq
        (print "Moving along planned path.")
        (eval plannedPath)
      )
      (motion_seq
        (print "Failed to find path.")
        (return)
      )
    )
  )

  # plan a collision-free path to move the robot home position (a set of joint positions)
  (def_fun MoveToHome ()
    (def_real_vec homeJoints (-90deg -80deg -70deg -90deg -250deg 300deg 0deg))

    (def_string plannedPath "")
    (rrt_plan ROBOT_MANIP homeJoints plannedPath
      (CollisionThreshold 0.001) (MaxTime 20.0) (SpeedFactor .4) (AccelerationFactor .1) (Tolerance 0.001)
    )

    (if (!= (size_of plannedPath) 0)
      (motion_seq
        (print "Moving along planned path to home.")
        (eval plannedPath)
      )
      (motion_seq
        (print "Failed to find path to home.")
        (return)
      )
    )
  )

  (print "Starting sequence...")
  (SetTcpToCamera "Camera2")
  (MoveToHome)

  # the inspection points are imported from CAD as named frames
  (InspectTurntableFrameWithRRT "Inspect1")
  (InspectTurntableFrame "Inspect2")
  (InspectTurntableFrame "Inspect3")
  (InspectTurntableFrame "Inspect4")

  (InspectTurntableFrame "Inspect5")
  (InspectTurntableFrame "Inspect6")
  (InspectTurntableFrame "Inspect7")
  (InspectTurntableFrame "Inspect8")

  (InspectTurntableFrame "Inspect9")
  (InspectTurntableFrame "Inspect10")

  (InspectTurntableFrame "Inspect11")
  (InspectTurntableFrame "Inspect12")
  (InspectTurntableFrame "Inspect13")
  (InspectTurntableFrame "Inspect14")

  (InspectTurntableFrameWithRRT "Inspect15")
  (InspectTurntableFrame "Inspect16")
  (InspectTurntableFrame "Inspect17")
  (InspectTurntableFrame "Inspect18")

  (MoveToHome)
  (print "Finished sequence.")
)

Demo of the inspection Script