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

5.5 KiB
Raw Permalink Blame History

机器人模型和标定输入

仓库中的合成模型用于仿真检查。实际机器人的接入数据来自模型、机械资料和实测控制行为。

核对模型事实

输入 需要核对的事项
单位与坐标系 模型长度为米,关节坐标为弧度或米。机体系速度为 +X 向前、+Y 向左,绕 +Z 的偏航为正。
连杆与动力学 验证树结构、质量和惯量、关节轴、阻尼、限位和碰撞位置。区分可视与碰撞几何。
支撑几何 指定承载站姿的碰撞几何或物体,以及与地面接触时扣分或终止的几何。支撑几何不可同时属于扣分或终止组。
执行器 记录位置或速度语义、增益、力或扭矩上限与动作尺度,并确认单位及关节顺序。
轮式控制 测量轮半径和方向。差速还需要轮距,全向需要各轮在机体系的位置与滚动方向。

站姿标定

第 3 层级需要浮动根、已命名的支撑和合理的初始姿态。 onboard.py calibrate 搜索无自穿透且支撑共面的姿态,沿竖直方向移动机身,再仿真 PD 保持。省略 height_joints 时,自动调整有限位的标量关节及滑动关节; 不限位的转动关节(包括轮关节)保持初始值。显式提供 height_joints 可限制 搜索关节,空映射则保留初始姿态。max_adjust 限制各关节变化量,默认 0.35 弧度或米,也可按选中的关节逐项设置。搜索在原有限位内保留 minimum_limit_margin,目标函数结合足端高度差、自碰撞穿透和初始姿态正则项。 碰撞掩码及模型声明的排除规则保持有效。

stance_attempts 允许 1–32 个确定性起点(默认 6);找到收敛的可行结果后 提前停止。报告记录调整关节、尝试次数及初始/最终穿透深度。 即使优化器收敛,独立的 initial_self_penetration 检查仍要求穿透不超过 1 µm。 这是有界局部搜索,不保证一定找到可行站姿;失败时应检查报告并调整初始姿态、 搜索范围或模型。检查支撑载荷、漂移、倾角、限位、自碰撞和力矩裕量。 无碰撞且足端共面时,仍需实际支撑和控制检查。

报告给出初始关节姿态、站立高度、各关节增益与力矩上限,并记录 XML 和编译后 资产的指纹。生成机器人规格时另行提供动作尺度。训练环境自带地形,所以机器人 MJCF 应只有一个带自由关节的根物体,并使用小写 .xml 后缀。训练使用的物体、 关节和几何名称不含 /。轮速关节须为不限位的转动关节。

可视几何回退的碰撞凸包

build-mjcf --visual-fallback 仅为未声明碰撞几何的 URDF 物体生成碰撞。 网格回退使用独立的内嵌凸包,默认采样 64 个方向;可视网格和已声明的碰撞不变。 它复用 tools/hull_collision.py 的凸包算法,支持 MuJoCo 可编译的网格格式。 --collision-hull-dirs 0 保留完整凸包,至少为 4 的值指定采样密度。 重复使用 --collision-hull-exclude MESH 可保留指定回退网格,特别是敏感的 支撑表面。基本几何体回退保留原形状。

构建报告中的 collision_hulls 记录原始/凸包顶点数及以米计的最大内缩量。 采样可能缩小支撑,单凸包也会填充凹陷;训练前须检查接触几何并重新标定。 顶点减少不代表 GPU 接触容量或性能已验证,仍须单独验证目标并行环境数量。

验证证据

onboard.py verify 比较原生 MuJoCo 实际响应和声明的预期。分别检查动力学与 控制阶段,包括有限状态、命令方向、响应及禁用执行器的对照。初始姿态需要启用接触动力学, 自穿透深度不超过 1 µm,各标量关节与限位之间保留裕量。 minimum_initial_limit_margin 默认是关节全行程的 0.02。

对于有界的执行器及关节作用力,报告记录峰值利用率和最后四分之一时段内接近 上限的时间比例。默认 effort_saturation_ratio: 0.98, max_effort_saturation_fraction: 0.25。早期加速瞬态会记录,本身不会 导致检查失败。探测时长应覆盖预期响应。

对于持续运动,在探测配置中设置 evaluation_start_s,并在 expect 中 指定速度指标。起始时间默认为零,须小于探测总时长。从该时间起,每个完成的 物理步都在模型定义的机体坐标系中采样。

{
  "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]
    }
  }
}

均值指标检查实测均值与目标值之差的绝对值,跟踪 MAE 指标检查绝对误差的 平均值,均按轴比较容差。null 容差仍报告该轴数值,但不参与判定。每个 指标至少有一个轴须提供数值容差。至少一个受约束的时间窗口指标须区别于禁用 执行器时的同一探测。应用的基准回放重新计算启用执行器时的统计值,并与记录 的证据比较。

模型、控制器或绑定改变后重新验证。仿真证据仅对应本次配置。实际硬件还需要 独立的接线、安全和运动验证。