# Add surface grippers

> Learn how to use surface grippers in your NOVA simulation.

![Quad Suction Gripper](/assets/nova/omniservice/surface_gripper/surface_gripper.webp)

Configure a surface gripper in a scene.
This guide demonstrates the workflow using a quad suction gripper. Video steps illustrate the process.

Additional information regarding the surface gripper properties can be found in the [Isaac Sim documentation](https://docs.isaacsim.omniverse.nvidia.com/5.1.0/robot_simulation/ext_isaacsim_robot_surface_gripper.html).

### Step 1: Add surface gripper object

> **Info:** The following instructions refer to the surface gripper object that was introduced with Isaac Sim 5.0.

1. Drag and drop the tool via the `Content` browser into the scene.
2. Add the surface gripper object from the menu `Create` → `Isaac` → `Robots` to the tool's Xform.

Video: [/video/omniservice/surface\_gripper/surface\_gripper\_\_create\_surface\_gripper.webm](/video/omniservice/surface_gripper/surface_gripper__create_surface_gripper.webm)

### Step 2: Create action graph

Video: [/video/omniservice/surface\_gripper/surface\_gripper\_\_create\_action\_graph.webm](/video/omniservice/surface_gripper/surface_gripper__create_action_graph.webm)

1. Create an action graph via the menu `Create` → `Visual Scripting` → `Action Graph`.
2. Add a surface gripper node from the menu.
3. In the surface gripper node's `Input` properties, provide the previously created surface gripper object as the surface gripper parameter.

Once you have tested the surface gripper successfully, you can then connect an On IO Change node with the surface gripper node.
For further details refer to [Robot controller IOs](/simulation/omnigraph-nodes/connect-ios#robot-controller-ios).

### Step 3: Create D6 joint

Video: [/video/omniservice/surface\_gripper/surface\_gripper\_\_create\_d6\_joint.webm](/video/omniservice/surface_gripper/surface_gripper__create_d6_joint.webm)

1. Create a D6 joint via the menu `Create` → `Physics` → `Joint` → `D6 Joint` inside the scope of one of the tool's Xforms.
2. Via the menu `Add` → `Edit API Schema`, add the `IsaacAttachmentPointAPI` to the joint.
3. The joint must have `Exclude from Articulation` set to `true` in its properties panel.
4. Set the local position and rotation of the joint coordinate with respect to `Body 0` and `Body 1`.\
   Any prim with rigid body properties can be selected. This defines the contact point for where the workpiece is gripped.
   See what happens if you don't define Body 1 in the [troubleshooting section](#prevent-snapping-of-the-tool-when-moving-it).
   - Switch between the local and world coordinate system display using the toolbar.
   - Rotate the coordinate frame so the z-axis points downwards in the direction where the workpiece
     will be located. The initial rotation of the joint in the video is already pointing downwards.
5. In the properties panel, scroll to the `Raw USD Properties` and define the `Forward Axis` to `Z`.\
   If needed, the clearance offset can also be specified.\
   The clearance offset defines the beginning of the measurement range for the ray casting that
   checks whether an object is ready to pick.
6. Repeat steps 1-5 for all suction cups of the gripper.

### Step 4: Configure surface gripper

1. Configure the `Surface Gripper` properties. Some example parameters are provided in the explanatory video and the table.
   - The force limits must be adapted to the physical gripper's properties.
   - The surface gripper works by sending a raycast from the joint world position in the direction of the forward axis.
   - The max grip distance specifies the length of the ray.
     For detailed information, refer to the [surface gripper documentation](https://docs.isaacsim.omniverse.nvidia.com/5.1.0/robot_simulation/ext_isaacsim_robot_surface_gripper.html) from NVIDIA.
2. Select all created D6 joints as `Attachment Points`.

Video: [/video/omniservice/surface\_gripper/surface\_gripper\_\_configure\_surface\_gripper.webm](/video/omniservice/surface_gripper/surface_gripper__configure_surface_gripper.webm)

| Parameter | Value |
| - | - |
| Retry Interval | 0.0 |
| Max Grip Distance | 0.05 |
| Coaxial Force Limit | 1000.0 |
| Shear Force Limit | 1000.0 |

### Step 5: Test surface gripper

Test the created surface gripper by using the `Close` button in the _SurfaceGripper_ object's property panel.

Video: [/video/omniservice/surface\_gripper/surface\_gripper\_\_test\_surface\_gripper.webm](/video/omniservice/surface_gripper/surface_gripper__test_surface_gripper.webm)

## Troubleshooting

### Prevent snapping of the tool when moving it

If there is no other suitable prim with rigid body properties available and you thus assign only one body for the D6 joint in the surface gripper,
Isaac Sim automatically assigns the second body to world. What's happening then is:

- Without specifying the location of the D6 joint with respect to Body 1, the tool is translated.
- The position and rotation with respect to world prim remain fixed.
- This causes the D6 joint to snap together on simulation start, breaking the tool.

Video: [/video/omniservice/surface\_gripper/surface\_gripper\_\_move\_surface\_gripper.webm](/video/omniservice/surface_gripper/surface_gripper__move_surface_gripper.webm)

#### Define Body 1

Every prim that has rigid properties and a fixed spatial relationship to the D6 joint
can serve as the Body 1 prim in the D6 joint property panel. E.g., if the tool is connected to a robot model,
this could be the robot's flange prim.

The video illustrates this by using a plane mesh with rigid properties to mimic a robot flange.
The plane prim is then connected to the tool via a fixed joint.

Video: [/video/omniservice/surface\_gripper/surface\_gripper\_\_fix\_surface\_gripper.webm](/video/omniservice/surface_gripper/surface_gripper__fix_surface_gripper.webm)

As soon as _Body 1_ is defined, the tool can be moved around without destroying the D6 joint.

Video: [/video/omniservice/surface\_gripper/surface\_gripper\_\_test\_fixed\_surface\_gripper.webm](/video/omniservice/surface_gripper/surface_gripper__test_fixed_surface_gripper.webm)