Files
chenlin c32df70326
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
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

119 lines
6.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Robot model and calibration inputs
This repository ships synthetic fixtures for simulation checks. A robot
onboarding record comes from the supplied model, mechanical documentation,
and measured control behavior.
## Model facts to establish
| Input | What to verify |
|---|---|
| Units and frames | Model length is in metres. Joint coordinates are in radians or metres. Body-frame velocity commands use +X forward, +Y left, and positive yaw about +Z. |
| Links and dynamics | Validate the parent tree, inertial masses and tensors, joint axes, damping, limits, and collision shape placement. Keep visual and collision geometry identifiable. |
| Support geometry | Name collision geoms or bodies that carry the stance. Identify geoms that incur a penalty or terminate an episode on terrain contact. A support geom cannot serve both purposes. |
| Actuation | Record motor effort limits, position or velocity semantics, gain values, and action scales with the units of the driven joint. Confirm that joint and controller orders are explicit. |
| Wheel controls | Measure radii and wheel directions. A differential mixer needs track width. An omni mixer needs wheel positions and rolling directions in the body frame. |
## Stance calibration
For Tier 3, provide a floating root, named support geoms or bodies, and a
reasonable seed pose. `onboard.py calibrate` searches for coplanar supports
without self penetration, shifts the base vertically, then simulates a PD hold.
When `height_joints` is omitted, the solver adjusts limited scalar joints and
slide joints; unlimited hinges (including wheels) remain at the seed. An explicit
`height_joints` map restricts the search, and an empty map keeps the seed.
`max_adjust` bounds each change (default 0.35 rad or metres, or a per-selected-joint
map). Authored limits retain `minimum_limit_margin`. The objective combines
support-height spread, native self-contact penetration, and seed regularization.
Native collision masks and exclusions remain authoritative.
`stance_attempts` allows 1–32 deterministic starts (default 6), stopping early
when a feasible converged result is found. The solver reports selected joints,
attempts, and seed/final penetration. `initial_self_penetration` independently
requires penetration no deeper than 1 µm, even if the optimizer converged.
This is a bounded local search, not a guarantee that a feasible stance exists;
review failed reports and adjust the seed, search bounds, or model as needed.
Review contact load, base drift and tilt, joint limits, self-contact, and
effort headroom. A collision-free coplanar pose can still fail support or control.
The report carries the proposed home pose and base height, named gains and
effort limits, and fingerprints of the XML and compiled assets. Supply action
scales explicitly when turning that report into a robot specification.
Training owns its terrain, so its MJCF is a robot-only model with a single
free root body and the lowercase `.xml` suffix. Training names for bodies,
joints, and geoms use unqualified names without `/`. Wheel velocity joints
must be unlimited hinges.
## Visual fallback collision hulls
`build-mjcf --visual-fallback` creates collision only where a URDF body has no
authored collision. Mesh fallbacks use separate inline convex hulls sampled in
64 directions; visual meshes and authored collisions remain unchanged. This
reuses the hull algorithm behind `tools/hull_collision.py` and works with any
mesh format MuJoCo can compile. `--collision-hull-dirs 0` keeps the full convex
hull; values of at least 4 select sampling density. Repeat
`--collision-hull-exclude MESH` to preserve selected fallback meshes, especially
sensitive support surfaces. Primitive fallbacks retain their original shape.
The build report's `collision_hulls` records source/hull vertex counts and
maximum inward shrink in metres. Sampling can shrink supports and a single
convex hull fills concavities: review contact geometry and recalibrate before
training. No GPU contact-capacity or performance guarantee follows from vertex
reduction alone; validate the intended environment count separately.
## Verification evidence
`onboard.py verify` compares real native MuJoCo responses with declared
expectations. Check the recorded physics and control stages, including
finite state, command signs and response, and the comparison with actuation
disabled. The initial pose needs enabled contact dynamics, no self penetration
deeper than 1 µm, and a margin to each scalar joint limit. The default
`minimum_initial_limit_margin` is 0.02 of the joint's full travel.
For bounded actuator and joint effort, the report records peak utilization
and the fraction of the final quarter spent near the limit. The defaults are
`effort_saturation_ratio: 0.98` and `max_effort_saturation_fraction: 0.25`.
An early acceleration transient is recorded without causing a failure on
its own. Use a probe long enough to measure the intended response.
For sustained motion, set `evaluation_start_s` on the probe and put
velocity metrics under `expect`. The start defaults to zero and must be
less than the probe duration. Verification measures the authored body
frame after every completed physics step at or after the start time.
```json
{
"evaluation_start_s": 2,
"expect": {
"base_velocity_mean_m_s": {
"target": [0.4, 0, 0],
"tolerance": [0.15, 0.15, null]
},
"base_velocity_tracking_mae_m_s": {
"target": [0.4, 0, 0],
"tolerance": [0.15, 0.15, null]
},
"base_angular_velocity_mean_rad_s": {
"target": [0, 0, 0.3],
"tolerance": [null, null, 0.2]
},
"base_angular_velocity_tracking_mae_rad_s": {
"target": [0, 0, 0.3],
"tolerance": [null, null, 0.2]
}
}
}
```
For each mean metric, the absolute difference between the observed mean
and the target must fit the per-axis tolerance. For each tracking MAE
metric, the mean of the absolute errors must fit the tolerance. A `null`
tolerance still reports that axis and omits it from the gate. At least
one axis per metric needs a numeric tolerance. At least one constrained
window metric must show a response different from the same probe with
actuators disabled. The application reference replay recomputes the
active statistics and checks them against the recorded evidence.
Re-run after changing the model, controller, or bindings. Simulation evidence describes that configuration.
Hardware bring-up requires its own wiring, safety, and motion validation.