Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

ControlKeys
ResetL
GainO decrease; P increase
EventR / K
TranslateW / S: +X / −X; A / D: −Y / +Y; Q / E: +Z / −Z
RotateZ / 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_ui hides 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_tracking shares terrain by default (other tasks may differ). Set env.stack=false for unique terrain geometry and materials per robot. Set SF_BAKER=0 to 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+, or manipulator+) 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]'
OverrideDefaultLimit 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.0For cameras without an authored period, negative selects the agent rate.
env.camera_clipping_rangeNoneNear/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