In Isaac Sim 5.1.0 the surface gripper will only work if very specific geometry, joint, and property conditions are satisfied; when the stock example works but your robot does not, it usually means the raycast / attachment joints are misconfigured or the gripper is actually colliding with its own robot instead of the target object.
Below are a few things you can check:
1. Verify attachment joints and schema
The Surface Gripper extension expects properly defined D6 joints and a surface gripper schema on the gripper prim.
Check in your USD:
- The gripper prim has the SurfaceGripper schema applied (via Add → Physics → Surface Gripper in the GUI), and:
Attachment Points relationship lists all your D6 joints (use absolute prim paths, matching what works in the example).Max Grip Distance, Clearance Offset, Forward Axis, Grip Threshold are set to reasonable values (copy values from the working 5.1.0 example as a baseline).
- Each attachment joint:
- Is a D6 joint, enabled, with the correct parent (your robot link) and child (the object to be gripped, or a generic attachment frame) bodies.
- Is located at the tip of the suction area, not inside the finger or way above it (you can inspect in the viewport with the joint gizmos visible).
A very common failure is that the Attachment Points relationship is empty or points to wrong joint paths; in that case the OGN node will never find joints to create constraints from.
2. Check raycast / clearance and self-collision
The surface gripper uses a raycast from each attachment joint along the configured forward axis to detect potential grasp targets within Max Grip Distance, offset by Clearance Offset.
Debug steps:
- In the GUI, enable:
- Physics → Show → Colliders, to see collision shapes for robot and target.
- Confirm that:
- The forward axis points towards the object, not toward the robot link.
Clearance Offset is large enough that the raycast starts outside your own link collider; otherwise the gripper will think it is “hitting” its own robot or never exiting self-collision.- The robot link that holds the gripper does not have a collision mesh intersecting the suction area; if it does, increase
Clearance Offset or trim that collision geometry.
If the raycast keeps hitting the robot, the gripper may stay in an error or “blocked” state and will not close on external objects.
3. Ensure target object is grippable
The object you want to pick must be a rigid body with proper collision and within the gripper search distance.
Check:
- The object prim has:
Physics -> RigidBody enabled.- A valid collider (box, sphere, convex, or SDF), not just visual mesh.
Max Grip Distance is larger than the actual gap between the attachment joint origin and the surface when the robot is in the “closed” pose.- The object is on a different articulation / rigid body from the robot, not another link of the same articulation; surface gripper is designed to attach to other rigid bodies, not your own robot links.
If you can move your robot so that in the example scene the gripper works on the sample cube, but fails on your object, the issue is usually the object’s rigid-body / collider setup.
4. Confirm control signals and state transitions
The Surface Gripper node has a state machine (open → closing → closed / grasped → opening). If you misdrive the inputs, it may never enter closing/grasped state.
When using the node or API:
- Verify that:
- The enable input is true while you expect it to act.
- The close command is asserted for long enough (at least over multiple simulation steps / frames).
- If using Python, ensure you call the relevant surface gripper update/step each frame (similar to the sample scripts in the Isaac Sim docs).
- Watch the Status and Gripped Objects read-only fields on the Surface Gripper schema:
- If Status stays in “Idle” or “Opening” while you try to pick, your close signal is not being seen.
- If Status briefly goes to “Closing” but never “Closed” or “Grasped”, the raycast is not finding any target within thresholds.
Matching the control wiring from the 5.1.0 example exactly (Graph structure, input names, and update frequency) is a good sanity check.
5. Match example physics and parameters
Even if the logic is correct, too small limits will make the gripper appear to “do nothing” or instantly drop the object.
Compare these against the working 5.1.0 example:
- On the D6 attachment joints:
- Limits on translational DOFs and the axial direction.
- Stiffness (
stiffness, damping) high enough to hold the object without excessive sagging.
- Break thresholds (force and torque limits) not set extremely low.
- On the Surface Gripper schema:
Max Grip Distance ~ a few millimeters to centimeters, matching your geometry.Shear Force Limit and Coaxial Force Limit set high enough for your object mass and expected accelerations.
Start with a direct copy of all physics-related parameters from the official 5.1.0 surface gripper example USD and only then adapt to your robot.
6. Minimal isolation test
To narrow down the cause:
- Duplicate the working 5.1.0 surface gripper example scene.
- Replace only:
- The robot articulation with your robot (keep the original object and gripper joints).
- Or, mount the example gripper on your robot end-effector by parenting its link under your EE frame, preserving its surface gripper schema and joints.
- If it works in this hybrid scene, the problem is in your gripper / object USD configuration, not in control or the extension.
