6.4 KiB
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.
{
"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.