222 lines
15 KiB
Markdown
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.
|