Surface gripper can't use & isaacsim twinkle

Omniverse Isaac Sim
1

6.0.0
5.1.0
5.0.0
4.5.0
4.2.0
4.1.0
4.0.0
4.5.0
2023.1.1
2023.1.0-hotfix.1
Other (please specify):

Operating System

Ubuntu 24.04
Ubuntu 22.04
Ubuntu 20.04
Windows 11
Windows 10
Other (please specify):

Isaacsim twinkle issue:

I have already installed the 580.88 driver on my Windows, but unfortunately my IsaacSim 5.1 display still flickers at a high frequency.

surface gripper issue:

Today I added a linear axis and a rotational axis to the gantry, and I also added a D6 joint to the head. I configured the drive, attachment API, etc.

After that, I used the surface gripper controller to perform suction.

However, an issue occurs where the gripper repeatedly switches between attach and detach states (and in some cases cannot grip at all).

This picture is repeatedly switches between attach and detach states:

It cause my cube move up and down.

image
image543×156 7 KB

image
image567×143 22.9 KB

image
image536×590 24.6 KB

This picture is cannot grip at all setting :

image
image506×431 16.8 KB

In this situation, how should I correctly assign Body 0 and Body 1 for the D6 joint?

Also, is there any part that might not have been properly configured or added?

Thank you.

3

Hi, for the Surface Gripper issue:
For your D6 attachment joint, here are the requirements the Surface Gripper Manager expects (see the
Surface Gripper Extension Doc:

  • Body 0 must be the gripper-side rigid body (the D6 head mounted to your gantry). All attachment joints under the same gripper must share the same Body 0.
  • Body 1 should be left empty in the USD authoring. The manager dynamically assigns the target rigid body at runtime when the raycast detects a valid object to grip.
  • The joint must have Exclude From Articulation set to True (the manager will force this at runtime, but setting it explicitly avoids a first-frame hiccup).
  • The joint must be enabled.

The repeated attach/detach behavior (the cube bouncing up and down) is almost always one of these:

  1. Missing ClearanceOffset — the raycast origin is inside the gripper’s own collider, so it alternates between hitting itself and the target. Select the D6 joint, add the AttachmentPointAPI schema (Properties panel → + Add → Edit API Schema → search AttachmentPointAPI), and set ClearanceOffset to a value just beyond the gripper body’s surface (e.g. 0.01–0.05 m depending on your units).
  2. Wrong Forward Axis — defaults to X. Make sure this matches the joint’s local axis that points toward the cube.
  3. Shear Force Limit / Coaxial Force Limit too low — the constraint forms, instantly exceeds the limit, breaks, and the manager immediately retries. Try increasing both by 10×–100× as a sanity check.
  4. Max Grip Distance too small — if the raycast never finds the cube, the gripper never attaches; if it’s only barely in range, small contact jitter can cause cycling.

I’d suggest loading the shipped example (Window → Examples → Robotics Examples → Manipulation → Surface Gripper) and comparing its D6 joint configuration against yours — that example uses exactly the gantry + D6 pattern you described and is a known-good reference.

4

Hi Peter

I tried the steps you suggested, but I’m still having trouble implementing the Surface Gripper.

I even matched my parameters with the official example, but the issue persists.

(Now it can’t open/close the surface gripper controller successfully.)

Please see the attached screenshots for my joint setup and parameter configurations.

image
image1601×966 154 KB

image
image849×457 18.8 KB

image
image863×681 27.6 KB

Thanks.

5

Hi, if the surface gripper still can’t open/close, here’re some suggestions how you can debug it:
Inside the extension, a “close” call drives the prim through Open → Closing → Closed only if the per-attachment-point raycast finds a foreign rigid body within MaxGripDistance along ForwardAxis. If nothing is found, the gripper sits in Closing for RetryInterval seconds and silently flips back to Open — there is no error log on a failed grip, which is what makes this look like “the controller does nothing.” So the first job is to figure out which transition is failing.

Please run the scene with the timeline playing and check:

  1. The Status attribute on your SurfaceGripper prim, sampled before and right after you trigger close. (Property panel → physxSurfaceGripper:status,
    or prim.GetAttribute("status").Get() in script.) The possible outcomes can tell you very different things:

    • Stays Open → your open/close call is not reaching the manager (wrong prim path, sim not playing, action value within the dead-band of [-0.3, 0.3], or the gripper prim isn’t registered with the manager).
    • Goes Closing and stays there ~RetryIntervals, then back to Open` → the raycast isn’t hitting the cube. This is by far the most common failure after the gantry rework and is usually one of:
      • Forward axis is no longer pointing at the cube. The forward axis is in the joint’s local frame. After you added linear+rotational gantry axes and re-parented the D6 head, the joint’s local X (default forward) likely no longer points down toward the part. Fix by either rotating the joint’s local frame so the chosen axis points at the target, or by changing forwardAxis to whichever local axis now points at the cube.
      • MaxGripDistance is too short. The shipped example uses 0.011 m because the gripper sits flush against the cube. If there is any standoff between your D6 head and the cube at the moment you press Close, raycasts of 11 mm will miss. Bump it to something generous (e.g. 0.05 or 0.1) just to confirm.
      • Target cube has no PhysX collider, or it’s filtered out. Verify the cube has PhysicsCollisionAPI applied and is not in a collision group excluded from the gripper body.
      • Raycast is self-hitting the gripper. The manager auto-grows ClearanceOffset when the ray hits Body 0, but only if Body 0 is actually the gripper-side rigid body. If Body 0 is set to the gantry root or another link, this self-detect doesn’t trigger and you get an immediate fail. Confirm Body 0 on every attachment-point joint points at the gripper head rigid body.
    • Goes Closing → Closed and immediately back to Open → grip is succeeding but force limits are tripping. Raise coaxialForceLimit and shearForceLimit by 10× and retry; the example’s coaxial=0.005 is intentionally tight for the lightweight example cube and is often too low for heavier parts.

  2. How you’re triggering open/close. If you’re calling the Python interface directly:

   from isaacsim.robot.surface_gripper import _surface_gripper
   iface = _surface_gripper.acquire_surface_gripper_interface()
   iface.close_gripper("/World/SurfaceGripper")  # returns False if path invalid

Check the return value — False means the prim path didn’t resolve to a registered gripper. If you’re using set_gripper_action(path, value), remember value > 0.3 closes, value < -0.3 opens, and anything in [-0.3, 0.3] is a no-op.

6

Hi Peter
Thank you so much for the detailed debugging guide! It’s very helpful for understanding how the state machine works under the hood.

I used the surface gripper UI to control the gripper’s open/close!

I’ve followed the steps to check the status attribute, and it seems my issue falls into the first category: the status stays “Open” even after I trigger the close command. It appears the call isn’t reaching the manager or the prim isn’t being registered correctly, despite the timeline playing.

To help me cross-reference my setup, would it be possible for you to provide a simple, working example (a minimal USD stage or a script snippet) where the surface gripper opens and closes successfully? Having a “known-good” baseline would be immensely helpful for me to identify what’s missing in my current gantry/D6 head hierarchy.

Thanks again for your time and expertise!

image
image563×519 88.2 KB

image
image557×401 37.8 KB

7

Hi, I have attached a minimal example to control the surface gripper. For more information on the surface gripper, you can check out the Surface Gripper Example.

surface_gripper_demo.py_ (12.3 KB)

8

Hi Peter,

I opened the file and ran it,

but it seems that this example does not address the build steps I wanted to ask about.

In the official example, there are no clear instructions on how to build the d6 joint that I mentioned before, so I would like to ask if you could make an example that is not a Python file.

Thank you.

9

Hi, D6 joints set up is described in Attachment Joints . And you can load the Surface Gripper example (Window->Robotics Examples->Surface Gripper) to check the D6 joints properties.