Files
VibemakerSandbox/docs/robots/microban.md
T
chenlin fa089d5f0c 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

66 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 的实际文件哈希。导入命令:
```bash
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 输出首先生成关节目标,然后每个物理子步计算:
```text
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 坐标系测试。
详见 [验收记录](../superpowers/verification/2026-10-27-multi-robot-platform.md)。只对记录的桌面 Chromium / WASM 组合做过验证;没有实机、移动端、手柄 / 触屏、15 小时耐久或不同浏览器的保证。模型和策略许可按原文件与来源说明分别核对。