Files
chenlin d5e9004f6c
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
docs: add AI agent workflow guide and clean up residual single-robot references
2026-11-05 11:52:07 +08:00

222 lines
15 KiB
Markdown

# Generic platform refactor — development record
Work began 2026-11-04 17:51 China time. The authorized autonomous window ends
2026-11-05 08:51 China time. This record distinguishes implementation checks,
measured simulation behavior, and hardware qualification.
The implementation and validation snapshot was finalized at 20:54 China time
on 2026-11-04. All training runs started for this snapshot have finished.
## Implemented architecture
- `scripts/onboard.py` performs inspection, URDF/MJCF/mesh normalization, stance
calibration, policy adaptation, controller setup, task scaffolding, and native
verification. Asset/physics/scaffolding operations are public Python APIs in
`mjrl.onboarding`; policy adaptation is `mjrl.adapter.adapt_policy`, and
controller setup is `mjrl.controllers.setup_controller`.
- `mjrl.controllers` implements DLS IK with mocap targets, joint sliders,
interpolated trajectories, differential/omni wheel mixing, and PD/CPG motion.
The training and native runtimes share validated operator vocabulary/bindings.
- `mjrl.adapter` wraps ONNX or TorchScript from explicit metadata, including
named permutations, normalization, observation history, and per-joint scales.
Interactive policies receive validated bindings; fixed actors expose no
imaginary command channels.
- Four templates define biped, quadruped, wheeled-biped and multipod training.
Hash gates cover their algorithms and shared behavior dependencies. Robot
onboarding creates only a literal `tasks/<robot_id>/robot_spec.py` in the task
tree. Mixed wheel/leg targets and passive observed joints preserve their
physical semantics in the versioned native export contract.
- Native `.app` bundles contain models and dependencies, contracts, policies or
trajectories, licenses, English/Chinese manuals, measured references, and a
portable Python implementation. Python and third-party packages remain host
requirements. The legacy Rust browser/board bundle is a distinct supported
format; native hybrid contracts are not silently passed to a legacy reader.
- Verification checks initial contact and limits, finite dynamics, root stability,
effort saturation and requested physical response. It measures endpoint and
body-frame mean/MAE responses, with an actuation-disabled counterexample.
Velocity capability requires independent nonzero probes of each enabled axis;
success while combining forward, sideways and yaw commands does not establish
that each direction works on its own.
Bundling fingerprints inputs, rejects missing gates, and reruns the packaged
response before publication. The reader uses its own trusted schema.
- Original exclusive robot assets/tasks were removed after shared mechanisms were
extracted. Historical ignored exports under `out/` were removed during
workspace cleanup, while training logs, failure reports and user applications
were retained. Scene dimensions are explicit nominal parameters.
## Measured evidence
The final example collection is `out/platform_release_20261104/`. Each application
has a checked Chinese manual. `reference-checks.json` records package replay.
| Example | Evidence | Scope |
|---|---|---|
| `mesh_viewer.app` | OBJ to MJCF, isolated portable replay | Display only; no control claim |
| `planar_arm.app` | IK endpoint error 5.14 micrometres; slider error 6.42e-10 rad; trajectory error 8.92e-7 rad | Three separately verified modes |
| `differential_drive.app` | At .35 m/s and .3 rad/s for 4 s: forward MAE .00799 m/s, yaw MAE .0284 rad/s; zero warnings | Native wheel dynamics and WASD bindings |
| `cpg_stance.app` | 10.4 s stance: .01086 rad tracking error, 8.30 mm translation, .04089 rad tilt change | Stationary oscillatory stance, not walking |
| `tier1_jit.app` | TorchScript adapter numerical error 0; final native joint error 1.17e-8 rad | Synthetic fixed-target actor, not a trained gait |
| `go1_example.app` | Seven 12 s native response probes plus full-range keyboard ramps; packaged references reproduce exactly | Learned quadruped control on a flat floor |
| `wheeled_biped_example.app` | Five isolated velocity/idle probes, full-range WASD, pad and release; eight-second .4 m/s packaged replay has .0450 m/s MAE and zero warnings | Four position-controlled leg joints and two velocity-controlled wheels |
| `g1_example.app` | Seven isolated native probes and full-range W/S/A/D/J/L with release; packaged .25 m/s replay averages .257 m/s with .0220 m/s MAE and zero warnings | Learned 29-joint biped control on a flat floor |
All four templates completed one PPO iteration on native CPU and Warp GPU using
synthetic fixtures (four environments, 24 steps each): eight execution checks.
A hybrid-wheel smoke checkpoint passed export and native replay parity but failed
velocity tracking. That failure remains recorded and was not published as accepted
locomotion. A separate passive-joint policy applied zero passive effort and matched
checkpoint final position within 8.25e-8 rad.
The registered `multipod_example` and `wheeled_biped_example` add independent
primitive-geometry models for the remaining families. Both passed native stance
calibration: six supports carried the 5.14 kg multipod with 8.77 mm peak drift;
two tires carried the 7.62 kg wheeled biped with 2.12 mm settling and no auxiliary
supports. Neither hold produced self contacts or MuJoCo warnings. Their learning
and policy-response results are measured separately from those static holds.
The selected wheeled-biped checkpoint completed 201 Warp updates across 1,024
environments (4,939,776 steps). Checkpoint 200 passed both stages with forward,
reverse, left yaw, right yaw and idle commands. Its saved curriculum level is 1,
with ranges of ±.91 m/s and ±.77 rad/s. Full-range WASD and pad tests confirmed
these directions, a zero lateral channel, and immediate command release. The
packaged policy matched its five references exactly. These are capabilities of
the selected checkpoint; a later curriculum range may exceed this sample's
wheel-speed limit and is not part of its published contract.
The multipod completed 1,000 Warp updates across 1,024 environments: 24,576,000
steps with no logged constraint overflow. Its final ONNX actor passed all 13
control probes, including the full-range keyboard directions. However, 11 probes
failed physical support checks because one or both middle feet had no load during
the final three seconds. Eight evaluated checkpoints failed to satisfy both
stages, so there is no published multipod application. The report and diagnostic
video in `out/multipod_example/` preserve that distinction; no template or
acceptance threshold was changed to turn this failure into a pass.
### Go1 learning and selection
The licensed vendored Go1 model passed a two-second native stance hold using
inertia-scaled gains: 16.1 mm maximum root displacement, .0562 rad maximum joint
error, and 20.0% peak effort utilization, supported on all four feet.
A Warp/RTX 5080 run used 2,048 environments, 24 steps per PPO update and 1,000
updates: 49,152,000 environment steps. Checkpoint 900 was selected because its
four feet remained loaded during the final three seconds of a 12-second idle
probe. Checkpoint 999 tracked movement but unloaded the front-right foot.
The selected checkpoint is:
`logs/go1/go1_example/2026-11-04_18-51-49/model_900.pt`
At a +.400 m/s command over 18 s on Warp, it averaged +.401 m/s with .022 m/s
mean absolute forward error and zero resets. The initial checkpoint was nearly
stationary with .400 m/s error. Native checkpoint and standalone ONNX tests
covered forward, reverse, both lateral directions, both yaw directions, and idle,
with no resets/warnings. ONNX worst translational MAE across those scenarios was
.0309 m/s; worst yaw MAE was .0395 rad/s. The full evidence and hashes are in
`out/go1_example/training-summary.json`; source provenance and repeatable commands
are in `assets/go1_example/README.md`.
### G1 learning and selection
The original G1 configuration completed 7,800 valid Warp updates across 1,024
environments: 191,692,800 environment steps. Rejected overflow runs and the
incorrect early-resume promotion are excluded. The selected checkpoint is
`logs/g1/g1_example/2026-11-04_20-25-00/model_7796.pt`.
It passed physics and control on all seven isolated 12-second native ONNX
probes. Its published command ranges are ±.28 m/s forward/reverse, ±.14 m/s
lateral and ±.32 rad/s yaw. Actual full-range keyboard tests had maximum
per-axis MAE of .0231 m/s, .0375 m/s and .102 rad/s, no MuJoCo warnings and
.0674 rad peak root tilt. Escape released commands; the measured post-release
residuals were at most .00321 m/s, .00402 m/s and .0104 rad/s. All seven packaged
references reproduced exactly. The shipped runtime was also executed from a
fresh directory outside the checkout for its eight-second preview.
The gait uses short, low steps on the training plane. This does not establish
obstacle clearance, robustness on other terrain or hardware readiness. The
separate `g1_compliant_example` kept the same mechanical model and locked
template but reduced hip/knee gains from 14 to 10 Hz and capped effort-derived
action scales by available joint travel. It passed static calibration and
learned forward movement earlier, but its 1,200-update policy failed lateral
tracking and fell during a yaw probe. That trial is unpublished. Its task
specification and source asset directory were removed so discovery no longer
advertises it as a supported example. Both its failure and the accepted original
configuration are preserved in their training summaries under `out/`.
## Authorized locomotion template revision: regularization and history
The shared template now retains the six deployable actor channels but stacks
four frames per term (oldest first, 20 ms control interval). The critic retains
its single-frame privileged inputs. This changes actor input dimensions: old
single-frame checkpoints must not be resumed or replayed against this template.
Use fresh training runs; existing exported policy bundles retain their own
observation contract and are not rewritten by this revision.
The revision adds mean position-joint HOME deviation (excluding wheel angles,
three times stronger at rest), vertical linear and roll/pitch angular velocity
costs, and contact-gated tangential support-speed cost. Slip cost is omitted for
wheeled bipeds because wheel-center translation is legitimate rolling, not
necessarily slip. A support-coverage cost penalizes missing contacts at rest and
supports airborne for more than 0.5 seconds in motion, without requiring all feet
to contact during a normal gait. Swing bonuses are paid only on landing using
bounded air duration, not continuously while a foot remains raised. Both support
terms are normalized by support count. These are morphology-independent starting
weights, not a measured optimum or a prescribed gait/clearance guarantee.
Startup randomization adds base density scaling in [0.9, 1.1] (mass and inertia
together via pseudo-inertia), and independent PD gain scales in [0.9, 1.1].
Existing COM offsets, friction, encoder bias and pushes remain. Play mode disables
these randomizations. No vendored implementation was changed. The lock gains the
PD randomization dependency; only the two revised shared implementation hashes
are refreshed after behavioral review and regression testing.
Validation includes negative controls for permanently raised middle supports,
hovering versus landing, airborne versus sliding feet, wheel-angle exclusion,
and nonzero body damping. Native execution checks verify actual randomized mass,
inertia and gains, four-frame observation ordering/reset, and exported history
metadata. All four registered morphology examples completed one native CPU PPO
update with four environments (96 transitions each). Multipod additionally
completed one Warp/CUDA update with four environments (96 transitions), with
finite losses and no logged contact/constraint overflow. Synthetic multipod and
wheel models still emit their existing MjSpec option-attachment warnings.
These are execution checks only: no convergence, 13-probe support acceptance,
improved G1 gait, large-batch GPU capacity, or hardware result is claimed.
The earlier failed multipod and short-step G1 evaluations above remain unchanged;
full retraining, replay, and identical physics/control gates are still required.
## Verification record and known limits
- Baseline before refactoring: 1,214 passed, 24 skipped, two failures. Many removed
tests belonged to the deleted exclusive tasks; shared mechanisms now use
independent fixtures and meaningful negative controls.
- Most recent complete suite after the endpoint/resource and mobility additions:
923 passed, one board-runtime test skipped. Current Rust controller core:
162 passed, one documentation example ignored. Browser tests compile current
wasm and exercise deterministic ONNX reference vectors instead of scanning
historical applications in `out/`.
- Focused endpoint, packaging, adapter, template, and wheel-install regressions
passed. The portable runtime rejects a bundle that weakens its own schema.
Installed-wheel application creation and isolated replay were exercised.
Velocity-controlled modes require measured body response on every enabled
axis; spinning wheels on an immobilized chassis cannot satisfy that gate.
A policy cannot receive nonzero commands on undeclared training ranges.
- On this host, use `env -u PYTHONPATH PYTEST_DISABLE_PLUGIN_AUTOLOAD=1` when
running pytest: unrelated ROS plugins otherwise interfere with discovery.
- G1 provides a second real-morphology integration. Its calibrated stance
passed after selecting coupled free-body inertia for gain sizing. Its initial
Warp allocation was inadequate: a 64-environment smoke exited successfully
despite constraint-overflow warnings, so that run is invalid. Explicit Warp
allocation is now recorded/restored by train, replay and export. Overflow
raises before the affected observations reach PPO. A 300-row allocation
completed 29,491,200 training steps without overflow. Forward and reverse
tracking improved, but lateral/yaw acceptance failed and prevented publication.
A subsequent resume exposed startup episode ages being mistaken for earned
curriculum evidence. That continuation was rejected. Restored runs now wait
a fresh episode horizon before collecting promotion evidence; regression tests
cover repeated loads as well as the first resume. The corrected continuations
reached the accepted checkpoint described above. Details are in
`out/g1_example/training-summary.json`.
- The full suite and lint pass after the runtime changes; the eight accepted
archives were refreshed and their references replayed. Actual board operation,
Windows/macOS execution, and live Colab were
not performed. The native Python format requires host runtime dependencies;
it is not a bundled operating system or a hardware-ready board executable.