OnRobot Gripper Device Integration

What you will learn

In this section, you will understand the workflow of integrating gripper with a UR arm. The steps will take you through of process of creating a simulation in ActinViewer that will be deployed in Robot Control Framework (RCF)



Demo video of OnRobot RG2 v1 Gripper with UR arm:

The high level workflow of gripper integration:

The blocks are color coded to represent diffrent sections of the tutorial

1. Model Gripper in SolidWorks and Export to Actin

This part is optional, since we've already converted the model into Actin format for you.

A SolidWorks compatible 3D model of the gripper is used to convert to an Actin model. That model is then processed through the Actin SolidWorks Addin module to output the Actin Simulation file.

1.1 Open Assembly

Assemblies must be used if you are defining a kinematic chain. The SolidWorks assembly model is provided in the project file with all of the reference geometry defined. Reference geometry can be added on the assembly, subassembly , or part level. Open the RG2 Gripper 3DModel.SLDASM in SolidWorks.

Make sure you have SolidWorks 2020 and the Actin SolidWorks Addin installed. Note that the gripper model consists of 2 four-bar linkages, which is what makes this conversion a little tricker that a straight linear actuator.

1.2 Define any Axes of Rotation/Translation

Axes are defined in SolidWorks to create Revolute or Prismatic Joints for the Actin model. Add axes to the SolidWorks model at center of rotation of the joints.

1.3 Define Coordinate Systems at link origins, tool offsets, and poses

Coordinate Systems in SolidWorks are used in Actin. The coordinate systems here are used to define primary frames (system and links) and gripper tool center points (TCP). The gripper has a moving TCP. This is due to the fourbar linkage. If the gripper is completely open, the TCP location is lower. As the gripper closes, the TCP moves away from the gripper. So, a coordinate system is defined at the grasp location for the object and the distance between the fingers is 3 inches.

1.4 Go to Actin Plugin Manipulator Tree

The SolidWorks Actin Addin is an intuitive graphical panel that is used to construct a robot manipulator.

1.5 Add and Define Manipulator

Right click on the panel and Add Manipulator. Name the Manipulator OnRobot RG2 v1. Accept all default changes for now and rename the base link Ground.

Right click the Ground Link and Edit Base Link. Select all of the Components that make up the base link.

In the Advanced tab, input the Coordinate Frames and Bounding Volumes. Now accept.

1.6 Add and Define Links

Additonal links are added to to the Ground link to build up the manipulator and there are four branches off that link. Create the first branch by right clicking the Ground link and select Add Link. Name it Crank 1. Select the Components, Joint Type, Joint Axis, input the Joint Limits, and reverse the joint directions if needed.

In the Advanced tab, input the Coordinate Frames and Bounding Volumes.

Repeat the the steps for all the other links [ Coupler 1, Crank 2, Coupler 2, Rocker 1, Rocker 2]

Refer to the model tree in RG2 Gripper 3DModel.SLDASM for more details.

Export the model.

Select the Tessellation Quality and save the file as OnRobot RG2 v1.ecz

2. Tune and Create Motion Constraints for Gripper Model

The model must be tuned and motion constraints must be created for correct motion control.

2.1 Open in Actin Viewer

Open the Gripper model file OnRobot RG2 v1.ecz in Actin Viewer.

2.2 Modify Collision Exclusion Map

The Collision Exclusion Map is used to configure which links/manipulators are allowed to collide with each other. The mechanism of the gripper does not allow any of the links to collide with each other and the limits were defined in SolidWorks. In this case, every link can be excluded with each other. Learn more about Collision Exclusion maps here.

Configure the Static Collision Map as in the screen shot below.

2.3 Create Motion Constraints to Control Gripper

Motion constraints are used to control the opening and closing of the gripper as well as constrain the closed chains. Go to Edit -> Advanced ->Motion Constraints and create a motion constraint set by right clicking the On Robot RG2 v1 -> Add Motion Constraint Set. Name the motion constraint set X End Effector Set. Create 4 motion constraints by right clicking X End Effector Set -> Add Motion Constraint. The links selected:

  • Coupler 1
  • Rocker 1
  • Rocker 2
  • Crank 1

Copy over the motion constraints to Joint control motion constraint set:

  • Rocker 1
  • Rocker 2
  • Crank 1

Change the properties of the motion constraints by referring to OnRobot RG2 v1.ecz model located in the project zip folder. Refer here for more information about motion constraints.

2.4 Constrain Passive Joints

It is always good practice to constrain passive joints after the motion constraints are created. Go to Edit -> Advanced -> Joint Configuration and check all of the constrained joints. Find more information about joint configurations here.

2.5 Save

Changes to model must be saved. It will be imported in the next sections.

3. Prepare Model and Scripts for ActinUR Projects

Flow Description:

3.1 Open in Actin Viewer

Open a UR5 CB5 model in Actin Viewer. The model can be found in the project zip file. The model is UR5.xml.

3.2 Merge Gripper Model

Merge the gripper model with the UR model. Colored cubes are used for the pick and place application and must be merged also.

Click File -> Merge ->

Then merge these files into the current model file:

OnRobot RG2 v1.ecz

Learn more about file merging here.

Notice the gripper is at the origin overlapping the UR5.

Go to Edit -> Position Control System -> Position Control System Parameters and uncheck the position controller for the RedCube. This disengages the motion control from the Cube - it will be controlled by attaching and un-attaching from the gripper.

3.3 Attach Manipulator

Attach the Gripper model to the end of the wrist of the UR model. Go to Edit -> Manipulator Attachments -> Add Attachment. Select the following parameters and press OK. Find more information about manipulator attachments here

Move the RedCube and BlueCube to reachable areas that are apart from each other. To move, right-click the cube, select Manipulator->Move

3.4 Modify Collision Exclusion Map

The Collision Exclusion Map is used to exclude collsion between the gripper and the UR model. Go back into the Collision Exclusions and properly exclude the Static and Dynamic collision maps between the OnRobot gripper, UR5, and the cubes. Use UR5-OnRobotGripperSCE.ecz in the project zip file as a reference. Find more information about collision exclusions here.

Hint: You want to exclude objects that are in constant contact with each other (gripper and wrist ) or objects that can't possibly collide.

3.5 Develop EcScript

EcScript is a programming language used by Actin to create robot motion. Open the Motion Script GUI and load the script file gripperMoveBlocks.ecs. Play the simulation and observe the system in motion. More information about Ecscript can be found here.

3.6 Export

Export the system control executive. Got to File -> Export -> Save as UR5-OnRobotGripperSCE.ecz.

4. Create ActinUR Project

If you do not have an ActinUR project with a UR5, follow the guide here to create project and name it ur5cb.

Make sure the robot ip address is correct within the file workspace.json within your newly created project.

4.1 Place System Control Executive file in the Project

Place the .ecz file you created earlier in the folder ~/<ur project>/rcf/system_control_executive

The System Control Executive has all the data required to control the robot system. It includes the model, the control system, the collision map, the bounding volumes, and graphical information.

4.2 Place EcScript file file in the Project

Places the script files (.ecs) into the folder ~/<ur project>/scripts

This is the folder that ActinViz searches when you load scripts.

4.3 Edit the System Controller XML File

Edit the file system_controller.xml and update controlExecutiveFileName tag to point to your model (.ecz) file. See line 3 of the XML file. Once edited, save the file.

4.4 Edit the Manipulator Controller (XML) File

Edit ur_manipulator_controller.xml and update the manipLabels tag.

An additional manipLabel must be added for the Gripper to control it in RCF process.

<manipLabels size="2">
    <element>OnRobot RG2 v1</element>
4.5 Update scripts to work with Data Store hardware

The scripts in ~/<ur project>/scripts should list:

  • gripperMoveBlocks.ecs
  • gripper_viewer.ecs
  • gripper_viz.ecs

Edit gripperMoveBlocks.ecs to comment the simulation script and uncomment the updated script. The reason that we do this is that the ActinViewer script does not talk to hardware. ActinViz does talk to hardware, and so switching this include will allow ActinViz to send digital I/O commands to the gripper.

#(include "/home/actin/projects/ur5cb/scripts/gripper_viewer.ecs")   
(include "/home/actin/projects/ur5cb/scripts/gripper_viz.ecs") 

More information about that can be found here.

4.6 Run simulation and control the robot

Startup the project and run gripperMoveBlocks.ecs. Starting up the project means starting Actin RCF (run_rcf.sh) and then Actin Viz (run_viz.sh)

Learn how to startup a project here.