fa089d5f0c
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.
66 lines
4.6 KiB
Markdown
66 lines
4.6 KiB
Markdown
# 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 小时耐久或不同浏览器的保证。模型和策略许可按原文件与来源说明分别核对。
|