Files
UniversalTrain-ai/docs/WORKFLOWS.md
T
chenlin c32df70326
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
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

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-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.