Files
2026-11-03 19:46:08 +08:00

5.2 KiB

Adding and checking a robot/task

Asset compilation is only the first step. A robot adapter must explicitly define model mechanics, sensors, controls, observations, reset posture and task semantics. There is no automatic conversion of an arbitrary MJCF into a validated walking task.

One-command conformance check

./scripts/uh check-robot --config experiments/g1_smoke.json --output runs/g1-check.json
./scripts/uh check-robot --config experiments/t1_smoke.json --output runs/t1-check.json

The command builds the actual nominal task, then performs a bounded zero-action PD probe (default 32 control steps, one CUDA world). No policy or hardware is loaded. It produces JSON and exits nonzero if any check fails. The report contains these stable check IDs:

Check ID What is actually checked
free_root Exactly one floating root joint
foot_sites Named foot sites exist on declared bodies, with declared local positions/orientations and plausible initial height above flat ground
imu Declared sensor names, types and dimensions; exact reference site, parent body, local position and orientation
joint_order Resolved action joint order and observation joint order match the separately declared lists; no duplicate action names
pd_and_limits One joint-transmission actuator per controlled hinge; enabled torque/joint limits, finite positive stiffness/nonnegative damping, expected gains, gear and ranges
action_transform Resolved action scales/offsets and physics/policy timestep match the declaration
initial_pose Default and actual root/joint pose, nominal +0.02 m reset height, zero initial velocities, hard-limit compliance and upright orientation
initial_penetration Native MuJoCo contact distance at the initialized task pose stays within the declared penetration threshold
contact_configuration Contact sensor resolves the declared foot bodies, filters terrain, requests found/force fields and has enabled collision geometry
contact_response Each declared foot actually reports contact and positive force during the probe
finite_probe Observations/rewards/joints/torques/contact forces stay finite, with no task termination during the bounded probe

Foot force magnitude, initial local site placement, gains, limits, names and timing are retained as evidence. A construction failure is reported rather than converted into a pass; checks that require a successfully constructed environment cannot run after construction fails.

This checks interface consistency and a short contact/control response—not motor identification, long-term balance, mesh realism, convergence, force accuracy or hardware safety. Initial penetration uses native MuJoCo on the compiled model; runtime contacts use the actual Warp task. These are complementary checks, not claims of bitwise physics parity.

Adapter procedure

  1. Inspect assets and licensing. Use inspect-asset PATH. Confirm mesh references, floating root, units, mass/inertia, hinges, limits, actuator transmissions and model variant. Keep new adapters in this project's package; do not silently edit a shared external repository.
  2. Define robot mechanics. Implement an EntityCfg factory, explicit PD/effort settings, reset pose, collisions, foot sites and IMU sensors. Record the source of hardware facts.
  3. Define the task. Provide independent environment/PPO factories following ARCHITECTURE.md. Existing flat-velocity integration expects entity robot, command twist, joint_pos actions, actor/critic groups, and base/joint reset events.
  4. Register metadata. Add a Task in src/universal_humanoid/registry.py and a bounded experiment in experiments/. The CLI itself should not gain robot-specific branches.
  5. Declare independent expectations. Add src/universal_humanoid/robot_specs/<robot>.json, using an existing declaration as a schema example. Review every joint order, gain, limit, site, IMU frame and posture against intended mechanics. Do not auto-generate expected values from the very environment being checked—that would validate a mistake against itself.
  6. Run the gate. Use check-robot --config ... --output NEW.json. During development an explicit --spec FILE.json can be used; it must match the task and schema. Unknown/missing sites, changed PD gains, swapped order or absent contact must remain failures.
  7. Test behavior. Add unit/negative tests, then bounded PPO, randomized/stress evaluation, measured CSV/video replay and ONNX parity. A passing robot gate is not the final acceptance.

The supplied declarations encode the existing adapted G1 and T1 baselines; they are simulation contracts, not certified hardware specifications. Updating an intended control setting requires review of both the adapter and declaration, followed by new tests and run provenance.

Nonstandard robots/tasks

This checker and exporter intentionally target flat-ground humanoids with one position actuator per controlled hinge. Tendons, coupled actuators, prismatic joints, multiple action groups, non-flat terrain or non-velocity tasks need an explicit extension of the contract and tests. Do not relax a check until it passes while continuing to claim the old contract.