4.9 KiB
Robot onboarding workflow
The intake tier describes what the supplied inputs support. A robot can use a lower tier for visualization or deterministic control even if it also qualifies for policy adaptation or training.
| Route | Required inputs | Verification and output |
|---|---|---|
| Tier 0 · Model viewing | Mesh, URDF, or MJCF and its dependencies | Compiled MJCF and viewer app |
| Tier 1 · Policy adaptation | Supported ONNX or TorchScript actor, matching robot model, and policy semantics from metadata or upstream training configs | Reviewed adapter metadata, numerical parity, then native model and policy response |
| Tier 2 · Deterministic control | Complete MJCF, known joint or wheel kinematics, selected controller | Native physics and command probes, then controlled app |
| Tier 3 · Training | Floating-base legged MJCF, named supports, explicit control intent and stance calibration | Literal robot spec, PPO checkpoint, measured replay, and policy export where supported |
Inspect the intake
python scripts/onboard.py inspect assets/my_robot --profile robot-profile.json --report intake.json
The profile is optional. Without it, morphology_candidates reports a tentative
family (biped, quadruped, wheeled_biped, multipod, arm, or null),
base body, support bodies/geoms, wheel joints, joint DOF count, and terminal
joint chains from the compiled topology and names. These are review candidates,
not measured stance or control facts. Multiple contact geoms on one branch do
not count as multiple legs; direct-drive wheels alone are not legs. Unrecognized
names or ambiguous topology can leave the family unknown.
A recognized floating-base legged MJCF (or a legged URDF awaiting a floating-base
build) can recommend Tier 3 with status: needs_profile and
next_step: review-profile without entering Tier 3 in eligible_tiers.
Review the candidates, declare the profile and control intent, resolve the
reported prerequisites, then calibrate. Missing URDF actuation/effort data
remains an explicit prerequisite, not an inferred motor specification. An
explicit profile takes precedence over automatic routing; policy adaptation
retains its existing priority. No directory watcher or automatic training is
started by inspection.
Select --policy and --metadata when the directory
has more than one candidate. Inspection lists upstream files under
training_config_candidates and unified adapter documents under
adapter_metadata_candidates. The policy_metadata_candidates list combines
both. A compatible model and actor can receive a Tier 1 recommendation with
recommendation.status set to needs_metadata. Read metadata_extraction
when inspection attempted an extraction. A needs_selection status asks you
to choose the matching actor or metadata. Tier 1 appears in eligible_tiers
once the model, actor selection and metadata have passed intake checks.
Resolve missing meshes and inertias, ambiguous model selection, incompatible
actuator semantics, and unresolved metadata before building an application.
Normalize the model
Use MJCF directly when it compiles and has the required geometry, frames, limits, and collision. For URDF or a standalone mesh:
python scripts/onboard.py build-mjcf assets/my_robot/robot.urdf \
--output assets/my_robot/robot.xml --floating-base --report build.json
Request a floating root only when the robot needs it. A standalone STL, OBJ, or MSH builds a visual model. Visual fallback for URDF is explicit and generates collision approximations. Review them in simulation before using the result for control or training.
Choose the next gate
- For a viewer app, run
scripts/deploy.py --robot <id> --model <mjcf>and verify that it loads and replays headless. - For Tier 1, use
onboard.py extract-tier1to review upstream YAML, JSON or static Python configs, or supply complete adapter metadata. Then runadapt-tier1and verify the actual controller against the exact model before packaging. Follow the extraction example. - For Tier 2, run
onboard.py setup-tier2with a controller config. Runonboard.py verifyon the generated model, controller, and operator bindings. A controlled native app requires passing physics and control evidence. Review the initial pose's contact and joint margins, finite-state checks, and sustained effort utilization in each probe. The verification defaults explain the gates. - For Tier 3, run
onboard.py calibrateand review measured contacts, limits, drift, and effort headroom. Pass the matching report toscaffold-tier3. Build through the discovered template, then replay the checkpoint with the training command ranges and recorded measurements.
See Usage for command forms, Tutorial for a worked verification flow, and Hardware for asset requirements.