Files
chenlin ceca51b0d8
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
Improve generic robot onboarding, walking controls and end-effector interaction
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.
2026-11-06 10:54:58 +08:00

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-tier1 to review upstream YAML, JSON or static Python configs, or supply complete adapter metadata. Then run adapt-tier1 and verify the actual controller against the exact model before packaging. Follow the extraction example.
  • For Tier 2, run onboard.py setup-tier2 with a controller config. Run onboard.py verify on 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 calibrate and review measured contacts, limits, drift, and effort headroom. Pass the matching report to scaffold-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.