73 lines
5.2 KiB
Markdown
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.
|