119 lines
6.4 KiB
Markdown
119 lines
6.4 KiB
Markdown
# 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.
|