Default humanoid intake to command-following gait and support bounded Cartesian target dragging for arms. Carry model and actuator semantics through calibration, native verification and packaging. Document reusable intake decisions and cover them with regression tests.
6.6 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.
For a humanoid, the default delivery goal is walking under operator control. Use a compatible walking policy when available or calibrate and train the biped. A standing or upper-body demonstration can verify an intermediate capability. Accept walking after measuring forward and reverse travel, left and right turns, stopping, and alternating support on the final policy. For an interactive arm, use a measured end-effector point and a draggable IK target. An explicit task request takes precedence over these defaults.
Use the common diagnosis, verification and closeout procedure throughout the selected route.
| 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 control intent takes precedence over the humanoid default. For the
default walking route, check that the candidate policy accepts both signs of
forward speed and yaw before choosing adaptation. A scene that includes a
floor may need its robot-only model before calibration. 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.
Assets without weights or training configs
A robot description can provide geometry, contact pairs, servo parameters and keyframes without a learned controller. Select the scene wrapper explicitly when it supplies the floor and contact pairs. For a reviewable evidence-only extraction, run:
python scripts/onboard.py extract-tier1 --model scene.xml --output out/model-draft
This writes metadata.json and manifest.json and exits 1 because policy
semantics remain unknown. The manifest's model_evidence includes the compiled
model fingerprint, named joints, actuator parameters and keyframes; it never
fills policy channel orders, scales, observation history or rate from these
physical facts. Supply matching configs and an actor to resume Tier 1.
Meanwhile, Tier 0 or a measured Tier 2 controller can produce an application.
Synthetic actors are separate adapter test fixtures, never recovered weights
or evidence of learned locomotion.
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.