Basic Usage
After installation, list registries and run an environment:
Native installation: If srb is unavailable, run:
"$ISAACSIM_PYTHON" -m srb --help
1. List Assets, Actions & Environments
Reference:
srb ls— List Assets and Environments
srb ls --live
Use --live for headless Isaac Sim discovery and cache refresh; plain srb ls prints cached names. See the CLI reference for categories and options.
Live tables list assets (scenery, objects, robots), action groups, hardware interfaces, and environments. Hardware interface examples are not validated on hardware.
1. Assets (click to expand)
Scenery asset (automatically registered as “mars_surface” scenery/terrain)
class MarsSurface(Terrain):
## Scenario - The asset is suitable for the Mars domain
DOMAINS: ClassVar[Sequence[Domain]] = (Domain.MARS,)
## Source selector — opt in to real DEMs by passing `source="real"`.
source: Literal["procedural", "real"] = "procedural"
site: str = "jezero"
## Model - filled in model_post_init
asset_cfg: AssetBaseCfg | None = None # type: ignore[assignment]
def _build_procedural_asset_cfg(self) -> AssetBaseCfg:
return AssetBaseCfg(
prim_path="{ENV_REGEX_NS}/mars_surface",
## Spawner procedurally generates SimForge models
spawn=SimforgeAssetCfg(
assets=[simforge_foundry.MarsSurface()],
collision_props=CollisionPropertiesCfg(),
# Static triangle-mesh collision is required; otherwise
# particles and objects fall through the SimForge mesh.
mesh_collision_props=MeshCollisionPropertiesCfg(
mesh_approximation="none"
),
),
)
def model_post_init(self, __context):
# Build first so the parent forwards density, scale, and texture
# settings to the newly constructed spawner config.
self.asset_cfg = resolve_surface_asset_cfg(
surface_name=self.__class__.__name__,
body="mars",
site=self.site,
source=self.source,
build_procedural_asset_cfg=self._build_procedural_asset_cfg,
build_real_asset_cfg=build_real_terrain_asset_cfg,
)
super().model_post_init(__context)
Object asset (automatically registered as “sample_tube” object/common)
class SampleTube(Object):
## Model - Rigid object affected by physics
asset_cfg: RigidObjectCfg = RigidObjectCfg(
prim_path="{ENV_REGEX_NS}/sample",
## Spawner loads a static USD file
spawn=UsdFileCfg(
usd_path=(
SRB_ASSETS_DIR_SRB_OBJECT.joinpath("sample_tube.usdc").as_posix()
),
collision_props=CollisionPropertiesCfg(),
mesh_collision_props=MeshCollisionPropertiesCfg(
mesh_approximation="convexDecomposition"
),
rigid_props=RigidBodyPropertiesCfg(),
mass_props=MassPropertiesCfg(density=1500.0),
),
)
Robot asset (automatically registered as “franka” robot/manipulator)
class Franka(SerialManipulator):
## Model - Articulation with several links connected by joints
asset_cfg: ArticulationCfg = ArticulationCfg(
prim_path="{ENV_REGEX_NS}/franka",
## Spawner loads a static USD file
spawn=UsdFileCfg(
usd_path=SRB_ASSETS_DIR_SRB_ROBOT.joinpath("manipulator")
.joinpath("franka_arm.usdz")
.as_posix(),
...
),
## Initial joint configuration of the robot
init_state=ArticulationCfg.InitialStateCfg(
joint_pos={
"panda_joint1": 0.0,
"panda_joint2": 0.0,
"panda_joint3": 0.0,
"panda_joint4": radians(-90.0),
"panda_joint5": 0.0,
"panda_joint6": radians(90.0),
"panda_joint7": radians(45.0),
},
),
...
)
## End effector - The default hand is separate to allow for easy replacement
end_effector: Tool | None = FrankaHand()
## Action modes — coded-in alternatives selectable via
## `env.robot.action_mode=<key>`. The first entry is the default.
action_modes: ClassVar[dict[str, ActionGroup]] = {
"diff_ik": InverseKinematicsActionGroup(
DifferentialInverseKinematicsActionCfg(
asset_name="robot",
joint_names=["panda_joint[1-7]"],
base_name="panda_link0",
body_name="panda_link7",
controller=DifferentialIKControllerCfg(
command_type="pose",
use_relative_mode=True,
ik_method="dls",
),
scale=0.1,
body_offset=DifferentialInverseKinematicsActionCfg.OffsetCfg(),
),
),
"osc_fixed": OperationalSpaceControlActionGroup(
OperationalSpaceControllerActionCfg(
asset_name="robot",
joint_names=["panda_joint[1-7]"],
body_name="panda_link7",
controller_cfg=OperationalSpaceControllerCfg(
target_types=["pose_rel"],
impedance_mode="fixed",
motion_stiffness_task=100.0,
motion_damping_ratio_task=1.0,
nullspace_control="position",
inertial_dynamics_decoupling=True,
),
nullspace_joint_pos_target="center",
position_scale=0.1,
orientation_scale=0.1,
body_offset=OperationalSpaceControllerActionCfg.OffsetCfg(),
)
),
"osc_var_stiffness": OperationalSpaceControlActionGroup(
OperationalSpaceControllerActionCfg(
asset_name="robot",
joint_names=["panda_joint[1-7]"],
body_name="panda_link7",
controller_cfg=OperationalSpaceControllerCfg(
target_types=["pose_rel"],
impedance_mode="variable_kp",
motion_stiffness_limits_task=(10.0, 250.0),
motion_damping_ratio_task=1.0,
nullspace_control="position",
inertial_dynamics_decoupling=True,
),
nullspace_joint_pos_target="center",
position_scale=0.1,
orientation_scale=0.1,
stiffness_scale=120.0,
body_offset=OperationalSpaceControllerActionCfg.OffsetCfg(),
)
),
"osc_var_full": OperationalSpaceControlActionGroup(
OperationalSpaceControllerActionCfg(
asset_name="robot",
joint_names=["panda_joint[1-7]"],
body_name="panda_link7",
controller_cfg=OperationalSpaceControllerCfg(
target_types=["pose_rel"],
impedance_mode="variable",
motion_stiffness_limits_task=(10.0, 250.0),
motion_damping_ratio_limits_task=(0.5, 2.5),
nullspace_control="position",
inertial_dynamics_decoupling=True,
),
nullspace_joint_pos_target="center",
position_scale=0.1,
orientation_scale=0.1,
stiffness_scale=120.0,
damping_ratio_scale=1.0,
body_offset=OperationalSpaceControllerActionCfg.OffsetCfg(),
)
),
"joint_pos_rel": JointPositionRelativeActionGroup(),
}
...
## Frames - Relevant frames for attaching the robot and mounting tool/sensors
frame_base: Frame = Frame(prim_relpath="panda_link0")
frame_flange: Frame = Frame(
prim_relpath="panda_link7",
offset=Transform(
pos=(0.0, 0.0, 0.107),
rot=rpy_to_quat(0.0, 0.0, -45.0),
),
)
2. Teleoperate a Robot
Reference:
srb agent teleop— Teleoperate Agent
Collect Mars Sample Return tubes in sample_collection with the Franka manipulator:
srb agent teleop --env sample_collection
Isaac Sim opens; focus its window to use the terminal controls.
| Control | Keys |
|---|---|
| Reset | L |
| Gain | O decrease; P increase |
| Event | R / K |
| Translate | W / S: +X / −X; A / D: −Y / +Y; Q / E: +Z / −Z |
| Rotate | Z / X: ±X; T / G: ↻ / ↺ about ±Y; C / V: ↺ / ↻ about ±Z |
Note: Direct teleoperation uses high-level actions. Low-level joint tasks (e.g.,
locomotion_velocity_tracking) need a policy to map commands to actions; see Teleoperation via Policy.
Move to a Different Domain
Reference: Environment Configuration
Reference: Environment Configuration — Domain
Collect procedural moon_rock samples on the Moon with Hydra overrides:
srb agent teleop --env sample_collection env.domain=moon env.sample=moon_rock
3. Run Random Actions
Reference:
srb agent rand— Random Agent
Run locomotion_velocity_tracking with random actions (default Spot):
srb agent rand --env locomotion_velocity_tracking
Hint:
--hide_uihides most of the Isaac Sim UI.
Change the Robot
Reference: Environment Configuration — Robot
Set env.robot to a legged robot or humanoid such as Unitree G1:
srb agent rand --env locomotion_velocity_tracking env.robot=unitree_g1
Simulate Multiple Robots
Reference: Environment Configuration — Parallelism
Run 16 Cassie instances in parallel:
srb agent rand -e locomotion_velocity_tracking env.robot=cassie env.num_envs=16
Hint:
locomotion_velocity_trackingshares terrain by default (other tasks may differ). Setenv.stack=falsefor unique terrain geometry and materials per robot. SetSF_BAKER=0to skip texture baking and speed generation; unbaked surfaces render with a magenta placeholder material:SF_BAKER=0 srb agent rand -e locomotion_velocity_tracking env.stack=false env.num_envs=16
4. Customize Environment Templates
Reference: Assets
Reference: Environment Configuration — Robot
Start custom scenarios from a robot-category template; sample_collection and locomotion_velocity_tracking are goal-oriented tasks.
Try _ground_manipulation with the Spot quadruped and Franka manipulator:
srb agent rand -e _ground_manipulation
Diversify Robot Configurations
Randomize Unitree quadrupeds (random_unitree_quadruped) and Universal Robots manipulators (random_ur_manipulator, UR3e–UR30); select mobile-manipulator parts via env.robot.mobile_base and env.robot.manipulator.
srb agent rand -e _ground_manipulation env.robot.mobile_base=random_unitree_quadruped env.robot.manipulator=random_ur_manipulator env.num_envs=6 env.stack=true
Customize Payloads & End Effectors
Reference:
srb agent zero— Zero Agent
Use + in env.robot or its mobile-base/manipulator fields to attach Cargo Bay to Anymal D and pair Unitree Z1 with Shadow Hand:
srb agent zero -e _ground_manipulation env.robot.mobile_base=anymal_d+cargo_bay env.robot.manipulator=unitree_z1+shadow_hand
Hint: Both sides of
+are required (for example,anymal_d+cargo_bay); omitting either side (+payload,+end_effector,mobile_robot+, ormanipulator+) raises an error.
Task and domain determine supported combinations; sensor poses and action-space dimensions adjust automatically.
srb agent zero -e _aerial_manipulation env.robot.mobile_base=ingenuity env.robot.manipulator=franka+scoop
srb agent zero -e _orbital_manipulation env.robot.mobile_base=gateway env.robot.manipulator=canadarm3
5. Enable Cameras
Most tasks disable visual sensors for performance; some enable them by default. Where supported, add visual to env.active_sensors.
View the Ingenuity helicopter on Mars:
srb agent teleop -e _aerial 'env.active_sensors=[proprioception,contact,transform,visual]'
| Override | Default | Limit or meaning |
|---|---|---|
env.camera_resolution | (64, 64) | Width and height; tasks may override. |
env.camera_data_types | ("rgb", "depth") | Task configuration determines available types and may override RGB and depth defaults. |
env.camera_update_period | -1.0 | For cameras without an authored period, negative selects the agent rate. |
env.camera_clipping_range | None | Near/far planes in metres; near must be positive, far greater than near and below 1000 m. Fills missing ranges or ranges with render-default far planes; preserves camera-authored ranges with far planes below 1000 m. |
Next: Workflows