Interacting with a surface gripper#
This tutorial shows how to interact with an articulated robot with a surface gripper attached to its end-effector in the simulation. It is a continuation of the Interacting with an articulation tutorial, where we learned how to interact with an articulated robot. Note that as of IsaacSim 5.0 the surface gripper are only supported on the cpu backend.
The Code#
The tutorial corresponds to the run_surface_gripper.py
script in the scripts/tutorials/01_assets
directory.
Code for run_surface_gripper.py
1# Copyright (c) 2022-2025, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
2# All rights reserved.
3#
4# SPDX-License-Identifier: BSD-3-Clause
5
6"""This script demonstrates how to spawn a pick-and-place robot equipped with a surface gripper and interact with it.
7
8.. code-block:: bash
9
10 # Usage
11 ./isaaclab.sh -p scripts/tutorials/01_assets/run_surface_gripper.py --device=cpu
12
13When running this script make sure the --device flag is set to cpu. This is because the surface gripper is
14currently only supported on the CPU.
15"""
16
17"""Launch Isaac Sim Simulator first."""
18
19import argparse
20
21from isaaclab.app import AppLauncher
22
23# add argparse arguments
24parser = argparse.ArgumentParser(description="Tutorial on spawning and interacting with a Surface Gripper.")
25# append AppLauncher cli args
26AppLauncher.add_app_launcher_args(parser)
27# parse the arguments
28args_cli = parser.parse_args()
29
30# launch omniverse app
31app_launcher = AppLauncher(args_cli)
32simulation_app = app_launcher.app
33
34"""Rest everything follows."""
35
36import torch
37
38import isaacsim.core.utils.prims as prim_utils
39
40import isaaclab.sim as sim_utils
41from isaaclab.assets import Articulation, SurfaceGripper, SurfaceGripperCfg
42from isaaclab.sim import SimulationContext
43
44##
45# Pre-defined configs
46##
47from isaaclab_assets import PICK_AND_PLACE_CFG # isort:skip
48
49
50def design_scene():
51 """Designs the scene."""
52 # Ground-plane
53 cfg = sim_utils.GroundPlaneCfg()
54 cfg.func("/World/defaultGroundPlane", cfg)
55 # Lights
56 cfg = sim_utils.DomeLightCfg(intensity=3000.0, color=(0.75, 0.75, 0.75))
57 cfg.func("/World/Light", cfg)
58
59 # Create separate groups called "Origin1", "Origin2"
60 # Each group will have a robot in it
61 origins = [[2.75, 0.0, 0.0], [-2.75, 0.0, 0.0]]
62 # Origin 1
63 prim_utils.create_prim("/World/Origin1", "Xform", translation=origins[0])
64 # Origin 2
65 prim_utils.create_prim("/World/Origin2", "Xform", translation=origins[1])
66
67 # Articulation: First we define the robot config
68 pick_and_place_robot_cfg = PICK_AND_PLACE_CFG.copy()
69 pick_and_place_robot_cfg.prim_path = "/World/Origin.*/Robot"
70 pick_and_place_robot = Articulation(cfg=pick_and_place_robot_cfg)
71
72 # Surface Gripper: Next we define the surface gripper config
73 surface_gripper_cfg = SurfaceGripperCfg()
74 # We need to tell the View which prim to use for the surface gripper
75 surface_gripper_cfg.prim_expr = "/World/Origin.*/Robot/picker_head/SurfaceGripper"
76 # We can then set different parameters for the surface gripper, note that if these parameters are not set,
77 # the View will try to read them from the prim.
78 surface_gripper_cfg.max_grip_distance = 0.1 # [m] (Maximum distance at which the gripper can grasp an object)
79 surface_gripper_cfg.shear_force_limit = 500.0 # [N] (Force limit in the direction perpendicular direction)
80 surface_gripper_cfg.coaxial_force_limit = 500.0 # [N] (Force limit in the direction of the gripper's axis)
81 surface_gripper_cfg.retry_interval = 0.1 # seconds (Time the gripper will stay in a grasping state)
82 # We can now spawn the surface gripper
83 surface_gripper = SurfaceGripper(cfg=surface_gripper_cfg)
84
85 # return the scene information
86 scene_entities = {"pick_and_place_robot": pick_and_place_robot, "surface_gripper": surface_gripper}
87 return scene_entities, origins
88
89
90def run_simulator(
91 sim: sim_utils.SimulationContext, entities: dict[str, Articulation | SurfaceGripper], origins: torch.Tensor
92):
93 """Runs the simulation loop."""
94 # Extract scene entities
95 robot: Articulation = entities["pick_and_place_robot"]
96 surface_gripper: SurfaceGripper = entities["surface_gripper"]
97
98 # Define simulation stepping
99 sim_dt = sim.get_physics_dt()
100 count = 0
101 # Simulation loop
102 while simulation_app.is_running():
103 # Reset
104 if count % 500 == 0:
105 # reset counter
106 count = 0
107 # reset the scene entities
108 # root state
109 # we offset the root state by the origin since the states are written in simulation world frame
110 # if this is not done, then the robots will be spawned at the (0, 0, 0) of the simulation world
111 root_state = robot.data.default_root_state.clone()
112 root_state[:, :3] += origins
113 robot.write_root_pose_to_sim(root_state[:, :7])
114 robot.write_root_velocity_to_sim(root_state[:, 7:])
115 # set joint positions with some noise
116 joint_pos, joint_vel = robot.data.default_joint_pos.clone(), robot.data.default_joint_vel.clone()
117 joint_pos += torch.rand_like(joint_pos) * 0.1
118 robot.write_joint_state_to_sim(joint_pos, joint_vel)
119 # clear internal buffers
120 robot.reset()
121 print("[INFO]: Resetting robot state...")
122 # Opens the gripper and makes sure the gripper is in the open state
123 surface_gripper.reset()
124 print("[INFO]: Resetting gripper state...")
125
126 # Sample a random command between -1 and 1.
127 gripper_commands = torch.rand(surface_gripper.num_instances) * 2.0 - 1.0
128 # The gripper behavior is as follows:
129 # -1 < command < -0.3 --> Gripper is Opening
130 # -0.3 < command < 0.3 --> Gripper is Idle
131 # 0.3 < command < 1 --> Gripper is Closing
132 print(f"[INFO]: Gripper commands: {gripper_commands}")
133 mapped_commands = [
134 "Opening" if command < -0.3 else "Closing" if command > 0.3 else "Idle" for command in gripper_commands
135 ]
136 print(f"[INFO]: Mapped commands: {mapped_commands}")
137 # Set the gripper command
138 surface_gripper.set_grippers_command(gripper_commands)
139 # Write data to sim
140 surface_gripper.write_data_to_sim()
141 # Perform step
142 sim.step()
143 # Increment counter
144 count += 1
145 # Read the gripper state from the simulation
146 surface_gripper.update(sim_dt)
147 # Read the gripper state from the buffer
148 surface_gripper_state = surface_gripper.state
149 # The gripper state is a list of integers that can be mapped to the following:
150 # -1 --> Open
151 # 0 --> Closing
152 # 1 --> Closed
153 # Print the gripper state
154 print(f"[INFO]: Gripper state: {surface_gripper_state}")
155 mapped_commands = [
156 "Open" if state == -1 else "Closing" if state == 0 else "Closed" for state in surface_gripper_state.tolist()
157 ]
158 print(f"[INFO]: Mapped commands: {mapped_commands}")
159
160
161def main():
162 """Main function."""
163 # Load kit helper
164 sim_cfg = sim_utils.SimulationCfg(device=args_cli.device)
165 sim = SimulationContext(sim_cfg)
166 # Set main camera
167 sim.set_camera_view([2.75, 7.5, 10.0], [2.75, 0.0, 0.0])
168 # Design scene
169 scene_entities, scene_origins = design_scene()
170 scene_origins = torch.tensor(scene_origins, device=sim.device)
171 # Play the simulator
172 sim.reset()
173 # Now we are ready!
174 print("[INFO]: Setup complete...")
175 # Run the simulator
176 run_simulator(sim, scene_entities, scene_origins)
177
178
179if __name__ == "__main__":
180 # run the main function
181 main()
182 # close sim app
183 simulation_app.close()
The Code Explained#
Designing the scene#
Similarly to the previous tutorial, we populate the scene with a ground plane and a distant light. Then, we spawn an articulation from its USD file. This time a pick-and-place robot is spawned. The pick-and-place robot is a simple robot with 3 driven axes, its gantry allows it to move along the x and y axes, as well as up and down along the z-axis. Furthermore, the robot end-effector is outfitted with a surface gripper. The USD file for the pick-and-place robot contains the robot’s geometry, joints, and other physical properties as well as the surface gripper. Before implementing a similar gripper on your own robot, we recommend to check out the USD file for the gripper found on Isaaclab’s Nucleus.
For the pick-and-place robot, we use its pre-defined configuration object, you can find out more about it in the
Writing an Asset Configuration tutorial. For the surface gripper, we also need to create a configuration
object. This is done by instantiating a assets.SurfaceGripperCfg
object and passing it the relevant
parameters.
The available parameters are:
max_grip_distance
: The maximum distance at which the gripper can grasp an object.shear_force_limit
: The maximum force the gripper can exert in the direction perpendicular to the gripper’s axis.coaxial_force_limit
: The maximum force the gripper can exert in the direction of the gripper’s axis.retry_interval
: The time the gripper will stay in a grasping state.
As seen in the previous tutorial, we can spawn the articulation into the scene in a similar fashion by creating
an instance of the assets.Articulation
class by passing the configuration object to its constructor. The same
principle applies to the surface gripper. By passing the configuration object to the assets.SurfaceGripper
constructor, the surface gripper is created and can be added to the scene. In practice, the object will only be
initialized when the play button is pressed.
# Create separate groups called "Origin1", "Origin2"
# Each group will have a robot in it
origins = [[2.75, 0.0, 0.0], [-2.75, 0.0, 0.0]]
# Origin 1
prim_utils.create_prim("/World/Origin1", "Xform", translation=origins[0])
# Origin 2
prim_utils.create_prim("/World/Origin2", "Xform", translation=origins[1])
# Articulation: First we define the robot config
pick_and_place_robot_cfg = PICK_AND_PLACE_CFG.copy()
pick_and_place_robot_cfg.prim_path = "/World/Origin.*/Robot"
pick_and_place_robot = Articulation(cfg=pick_and_place_robot_cfg)
# Surface Gripper: Next we define the surface gripper config
surface_gripper_cfg = SurfaceGripperCfg()
# We need to tell the View which prim to use for the surface gripper
surface_gripper_cfg.prim_expr = "/World/Origin.*/Robot/picker_head/SurfaceGripper"
# We can then set different parameters for the surface gripper, note that if these parameters are not set,
# the View will try to read them from the prim.
surface_gripper_cfg.max_grip_distance = 0.1 # [m] (Maximum distance at which the gripper can grasp an object)
surface_gripper_cfg.shear_force_limit = 500.0 # [N] (Force limit in the direction perpendicular direction)
surface_gripper_cfg.coaxial_force_limit = 500.0 # [N] (Force limit in the direction of the gripper's axis)
surface_gripper_cfg.retry_interval = 0.1 # seconds (Time the gripper will stay in a grasping state)
# We can now spawn the surface gripper
surface_gripper = SurfaceGripper(cfg=surface_gripper_cfg)
Running the simulation loop#
Continuing from the previous tutorial, we reset the simulation at regular intervals, set commands to the articulation, step the simulation, and update the articulation’s internal buffers.
Resetting the simulation#
To reset the surface gripper, we only need to call the SurfaceGripper.reset()
method which will reset the
internal buffers and caches.
# Opens the gripper and makes sure the gripper is in the open state
surface_gripper.reset()
Stepping the simulation#
Applying commands to the surface gripper involves two steps:
Setting the desired commands: This sets the desired gripper commands (Open, Close, or Idle).
Writing the data to the simulation: Based on the surface gripper’s configuration, this step handles writes the converted values to the PhysX buffer.
In this tutorial, we use a random command to set the gripper’s command. The gripper behavior is as follows:
-1 < command < -0.3 –> Gripper is Opening
-0.3 < command < 0.3 –> Gripper is Idle
0.3 < command < 1 –> Gripper is Closing
At every step, we randomly sample commands and set them to the gripper by calling the
SurfaceGripper.set_grippers_command()
method. After setting the commands, we call the
SurfaceGripper.write_data_to_sim()
method to write the data to the PhysX buffer. Finally, we step
the simulation.
# Sample a random command between -1 and 1.
gripper_commands = torch.rand(surface_gripper.num_instances) * 2.0 - 1.0
# The gripper behavior is as follows:
# -1 < command < -0.3 --> Gripper is Opening
# -0.3 < command < 0.3 --> Gripper is Idle
# 0.3 < command < 1 --> Gripper is Closing
print(f"[INFO]: Gripper commands: {gripper_commands}")
mapped_commands = [
"Opening" if command < -0.3 else "Closing" if command > 0.3 else "Idle" for command in gripper_commands
]
print(f"[INFO]: Mapped commands: {mapped_commands}")
# Set the gripper command
surface_gripper.set_grippers_command(gripper_commands)
# Write data to sim
surface_gripper.write_data_to_sim()
Updating the state#
To know the current state of the surface gripper, we can query the assets.SurfaceGripper.state()
property.
This property returns a tensor of size [num_envs]
where each element is either -1
, 0
, or 1
corresponding to the gripper state. This property is updated every time the assets.SurfaceGripper.update()
method
is called.
-1
–> Gripper is Open0
–> Gripper is Closing1
–> Gripper is Closed
# Read the gripper state from the simulation
surface_gripper.update(sim_dt)
# Read the gripper state from the buffer
surface_gripper_state = surface_gripper.state
The Code Execution#
To run the code and see the results, let’s run the script from the terminal:
./isaaclab.sh -p scripts/tutorials/01_assets/run_surface_gripper.py --device cpu
This command should open a stage with a ground plane, lights, and two pick-and-place robots.
In the terminal, you should see the gripper state and the command being printed.
To stop the simulation, you can either close the window, or press Ctrl+C
in the terminal.

In this tutorial, we learned how to create and interact with a surface gripper. We saw how to set commands and query the gripper state. We also saw how to update its buffers to read the latest state from the simulation.
In addition to this tutorial, we also provide a few other scripts that spawn different robots. These are included
in the scripts/demos
directory. You can run these scripts as:
# Spawn many pick-and-place robots and perform a pick-and-place task
./isaaclab.sh -p scripts/demos/pick_and_place.py
Note that in practice, the users would be expected to register their assets.SurfaceGripper
instances inside
a isaaclab.InteractiveScene
object, which will automatically handle the calls to the
assets.SurfaceGripper.write_data_to_sim()
and assets.SurfaceGripper.update()
methods.
# Create a scene
scene = InteractiveScene()
# Register the surface gripper
scene.surface_grippers["gripper"] = surface_gripper