Files
VibemakerSandbox/docs/robots/microban.md
T
chenlin fc5ee4f2c6 feat: release v0.2 multi-robot simulator
Add declarative robot packages, shared simulation lifecycle and Microban ONNX/PD walking with independent head control.

Unify comic UI and chase camera; default robot packages to a 4.5m arena with real collision walls. Include regression tests, asset provenance/licenses and verification evidence.
2026-10-28 14:00:26 +08:00

4.6 KiB
Raw Blame History

Microban 浏览器 Package

首期功能

  • 在工具栏 Robot 中选择 Microban;默认使用平台统一 arena:内部 4.5 × 4.5 m(原场地长宽各扩大 50%),墙高 .25 m、厚 .05 m,四边为真实碰撞盒。
  • 内部仍是平地,无高度场;复用 Microduck 的暗色橙色网格、围墙视觉、comic/CRT 和背后相机。重力、驱动、policy 参数不变;不是用坐标夹紧伪造边界。
  • 有界默认场地的运动验收为三轮各 70 s;另用显式 flat 诊断场地保留三轮各 84 s 原长距离协议,二者不能混称。
  • 导入/切换后默认在机器人背后跟随;鼠标拖拽切换到自由环绕,按 C 恢复背后跟随和默认距离。C 在暂停时也有效,重复按不会关闭跟随。
  • 方向键 / WASD 前后走和转向;H 独立开关转头;Esc 暂停;Space 重置。
  • 按键面板中的转头条目也可点击。转头不会切断行走,暂停时技能计时停止。
  • 跌倒显示 Robot fallen,停止策略更新,使用 Space / Reset 手动重置。没有自动起身或 Placo 下蹲。

资产与来源

app/public/robots/microban/ 包含:

  • model.xml 与它实际声明的 25 个 STL;原模型不修改,运行时组合空地与 timestep。
  • policies/walk.onnx。
  • source-manifest.json:源 remote、HEAD、dirty 标志、逐文件 SHA-256、行为参考代码哈希。
  • SOURCE.md 和 LICENSES/:原项目混合许可文本、XML 的 Apache-2.0 许可文本和归属说明。

源仓库为 https://github.com/Rhoban/microban.git,导入时 HEAD 为 d0a128d180ecfce69eaaf31b295a0fce31280bfd,工作区含未提交修改。因此不能只凭 HEAD 复现参考行为,须同时保留 manifest 的实际文件哈希。导入命令:

python3 app/scripts/import-microban.py /path/to/microban
npm --prefix app run validate:packages

导入是显式离线维护操作,不是运行或构建的依赖;日常运行不读取源仓库、不要求 Python / BAM / Placo。导入后需检查是否有实质变化,不自动接受策略 / 行为更新。

策略接口

项目 数值
输入 obs,float32 [1,63]
输出 actions,float32 [1,18]
模型 / metadata 关节 19,包含 head
actor 关节 18,显式顺序见 robot.json,不含 head
观测 gyro 3 + trunk projected gravity 3 + joint pos rel 18 + joint vel 18 + lastAction 18 + twist 3
时钟 物理 0.005 s;每 4 子步推理一次(50 Hz)
参考相位 当前策略不含额外 cos / sin 项

metadata 的 joint_names/default_joint_pos 按名字筛选,不能直接按 19 项顺序分发给 18 维输出。head 的初始目标为 0,由 overlay 管理,不进入 actor 的 lastAction。

IMU 安装四元数为 (0.5,-0.5,-0.5,0.5)。gyro 保留 MJCF IMU site frame;重力采用 trunk frame,等价于从 orientation sensor 的四元数扣除安装旋转再做重力逆旋转。测试以非零角速度和 45° 倾角验证这两个坐标系没有被错误合并。

head 使用源项目的正弦运动:0.35 Hz、幅值 ±π/4;进入与退出各 0.5 s 插值,关闭后回到 0。计时取仿真时间,不依赖墙钟。

简化执行器

原始 MJCF 的执行器是 <motor>,ctrl 表示力矩,不是目标角。浏览器 actor 输出首先生成关节目标,然后每个物理子步计算:

tau = clamp(0.3 * (target - q) - 0.02 * dq, -0.65, 0.65)

这是实验选择的简化参数,不是 ONNX metadata stiffness 的直接套用,也不是 BAM 或实机等价模型。保留模型原有阻尼与惯性参数;不模拟电压下降、电流限制、非线性摩擦和通信 / 传感器延迟。

默认命令为前进 0.15 m/s、后退 −0.1 m/s、转向 ±0.6 rad/s。这是通过当前验收的默认命令,不保证精确速度或航向跟踪。持续前进仍可能发生航向 / 横向漂移;不能把稳定不跌倒等同于导航精度。

验证与限制

microban-walking.spec.js 从重置状态完成三轮,每轮 84 s 仿真:站立、前后走、左右转、停顿、行走中转头、关闭转头。检查实际位移方向、展开的 yaw、head 幅度 / 回正、无跌倒 / 重置,并记录 PD 饱和统计。另有真实墙钟下近 50 Hz 测试、H 按键、跌倒手动 reset 与 IMU 坐标系测试。

详见 验收记录。只对记录的桌面 Chromium / WASM 组合做过验证;没有实机、移动端、手柄 / 触屏、15 小时耐久或不同浏览器的保证。模型和策略许可按原文件与来源说明分别核对。