srb real_agent — Sim-to-Real Bridge

srb real_agent generates lightweight hardware environments under srb_real/ from simulated Gymnasium environments, then provides agent commands for hardware. Generated environments do not depend on Isaac Sim.

Sub-Subcommands

srb real_agent <action> [options]

srb real_agent gen

srb real_agent gen --env ENV_ID [options]

The command inspects the Gymnasium spec and writes the counterpart to srb/interfaces/sim_to_real/env/<env_id>.py. Other srb real_agent commands then resolve that --env ID under srb_real/.

When the live action configuration declares command semantics, generation emits optional COMMAND_MAPPING metadata: six device values (translation and rotation XYZ, after gains) and an event mapped to named action slices. The declaration is checked against action order; hardware scaling remains in the downstream adapter.

Older modules keep COMMAND_MAPPING = None; policy actions and raw ROS input retain existing behavior. Custom simulator mappers need an explicit declaration. Native direct teleop and human collection require it and reject unmigrated checked-in profiles before hardware starts. Review regeneration and the robot’s deployment contract before adopting a module.

Example

srb real_agent gen --env waypoint_navigation env.robot=leo_rover \
  --hardware ros_cmd_vel ros_tf ros_mw

If another command’s environment is not registered under srb_real/, the runner generates it in a subprocess and asks you to rerun the command.

--check — the freshness gate

For --env ALL --check, cached environments without generated modules are skipped; drift, orphan modules, an empty cache, or no generated module fails.

Landscaping task IDs

Terrain landscaping has three task IDs. The general task uses per-episode mission manifests; the crater and mound tasks use fixed target manifests.

srb real_agent gen --env terrain_landscaping_crater
srb real_agent gen --env terrain_landscaping

srb real_agent gen --env terrain_landscaping_crater --check
srb real_agent gen --env terrain_landscaping --check

The listed commands run unqualified — no env.particles_height override belongs in them. Generating a bridge module does not make these tasks deployable: construction of the landscaping RealEnv still fails closed on missing hardware capability tags. See Terrain Landscaping Training Readiness.

Shared Options for the Other Sub-Subcommands

The runtime subcommands (zero, rand, teleop, ros, train, eval, collect) accept the same baseline options:

Additional groups depend on the subcommand:

• teleop and human collect accept --teleop_device, --pos_sensitivity, --rot_sensitivity, and --invert_controls. Native devices are ros (default), spacemouse, and haptic; simulator-only keyboard and gamepad are rejected before hardware or input acquisition.
• collect accepts the standard collection arguments (--collector, --num_episodes, --horizon, --success_only). --collector can be human, policy, random, or zero.
• train requires --algo (RL). Supported RL choices include dreamer, tdmpc2, and sbx_ppo; training also supports --continue_training / --model.
• eval requires --algo and/or --model. Evaluation choices include dreamer, tdmpc2, sbx_ppo, robomimic_bc, and robomimic_cql.
• collect accepts --algo and --model for policy rollouts. Native teleop rejects these arguments: it has no declared policy-command interface. Use eval or policy collect to run a policy; simulation-side srb agent teleop retains its policy-command mode.

eval and policy collect accept SRB model artifact directories as --model. Their manifest supplies an omitted --algo, and adapters reuse bundled framework config. Real collection sets split=real and records the controller label; artifact-backed policy collection records both checkpoint and model artifact paths.

Native direct input

Native direct teleop and human collection validate the generated mapping and all devices before session startup. Device commands map to one flat action; hardware scaling runs in the adapter. --invert_controls applies the existing manipulation-only XY inversion. Session cleanup finishes before the environment releases its ROS node and context.

ROS teleop consumes global /cmd_vel (Twist) and /gripper (Bool) device inputs with sensitivity gains. These are not the flat policy actions consumed by real_agent ros. ROS and haptic devices retain existing timeout behavior; they do not use the raw policy source’s selected-sample deadline. Haptic input has no simulator-contact force feedback.

ROS and haptic inputs have no manual save/discard/reset callbacks; collection ends on environment termination or --horizon. SpaceMouse keeps button callbacks, including left-button reset, and the CLI prints available controls. Datasets store observation leaves at contract shape and include a terminal row on completion. SpaceMouse open or cleanup failures are reported as failures.

Real Validation

srb real_agent validate --spec SPEC_PATH [options]

--dry-run never passes. It skips environment and policy instantiation, then finalizes the session with exit_code: 4 (preflight_fail), pass_overall: false, hardware_evidence: false, metrics.n_episodes: 0, and a red badge.json of {"label": "real-eval", "message": "non-hardware evidence", "color": "red"}. All three criteria are reported with status skipped. A dry-run artifact is a wiring smoke test, never a validation result. See Sim-to-Real Transfer for the full exit-code table.

Validation runs the generated real environment, creates telemetry in logs/real_validation/, and calls a policy reset hook at the start of every episode when the loaded policy exposes one. --checkpoint can point to a raw checkpoint or an SRB model artifact; artifact checkpoints reuse the same policy-loading path as eval and collect, including bundled framework config for Dreamer, TD-MPC2, RSL-RL, and SKRL. A raw SKRL or RSL-RL checkpoint recovers its agent config from the training run’s .hydra/config.yaml; a checkpoint without one, or a config restored from a sanitized metadata snapshot, is rejected with a clear error. When the validation spec omits algo or uses REQUIRED_AT_RUNTIME, an artifact checkpoint supplies the algorithm from its manifest; an explicit conflicting spec algorithm is rejected.

srb real_agent rebuild-summary

Rebuild the summary.json and report.md artifacts for an existing real validation session directory. This is useful when the validation spec has changed, or you wish to adjust metrics or post-processing without re-running the physical hardware validation.

srb real_agent rebuild-summary SESSION_DIR

• SESSION_DIR: Path to the validation session directory (which must contain a spec.yaml and logged .jsonl / .rrd telemetry).

srb real_agent replay-twin

Open a local Rerun viewer showing a time-aligned comparison of a real hardware validation rollout side-by-side with a simulated baseline rollout (“sim ghost” vs. “real solid”).

srb real_agent replay-twin --session SESSION_DIR --baseline BASELINE_RRD_PATH

• --session SESSION_DIR: Path to the validation session directory containing rollout.rrd.
• --baseline BASELINE_RRD_PATH: Path to the baseline .rrd file captured from a simulation run.

See Also

• Sim-to-Real Transfer Workflow — end-to-end example, ROS 2 hardware bridges, mission rehearsal
• srb agent — the simulation-side counterparts of the same verbs