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

6.4 KiB
Raw Permalink Blame History

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.