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

73 lines
5.2 KiB
Markdown

# 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
```bash
./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](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.