82 lines
6.8 KiB
Markdown
82 lines
6.8 KiB
Markdown
# Microban 浏览器 Package
|
||
|
||
## 首期功能
|
||
|
||
- 在工具栏 Robot 中选择 Microban;默认使用平台统一 `arena` 模板,按名义站立高度 0.33 m 相对 Microduck 0.27 m 等比适配:内部 **5.5 × 5.5 m**,墙高约 **0.306 m**、厚约 **0.061 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`。
|
||
- `visuals/*.glb`:用户提供的新版 `microban2.zip` 中 20 个原始 GLB,保留 PBR 材质和 46 张内嵌纹理(45 张法线贴图及 1 张屏幕颜色贴图);替代白模显示,不替换物理网格。
|
||
- `visual-source-manifest.json`:视觉压缩包和逐文件 SHA-256,与原物理 / 策略来源记录分开。压缩包没有许可说明,公开分发前需向资产所有者确认。
|
||
- `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。导入后需检查是否有实质变化,不自动接受策略 / 行为更新。
|
||
|
||
## 带纹理外观
|
||
|
||
刷新页面后选择 Microban 即使用新外观:浅紫外壳、蓝色金属支架、黑色电机及带颜色贴图的屏幕。新版 20 个 GLB 的顶点位置和节点变换与上一版一致,保留现有部件绑定。`render.body_visuals` 将 BASE、LINK1–19 映射到已有的 20 个 MuJoCo body,显式记录米制平移和 xyzw 单位四元数。坐标变换经原几何对齐检查;部件包围盒端点差异最大约 3 mm,包含新外观的螺丝等细节,不是运行时自动猜测比例或改变关节姿态。
|
||
|
||
所有部件每帧读取原 `xpos/xquat`,包括独立转头;原 visual geom 隐藏,碰撞、质量、惯量、关节、策略和 PD 均保留。GLB 加载失败会放弃候选机器人并恢复旧机器人,不会以静默白模掩盖缺失资源。切换时释放几何、材质、纹理和 ImageBitmap。
|
||
|
||
```bash
|
||
python3 app/scripts/import-microban-visuals.py /path/to/microban2.zip
|
||
npm --prefix app run validate:packages
|
||
npm --prefix app run test:e2e -- microban-visuals.spec.js microban-walking.spec.js runtime-leaks.spec.js
|
||
```
|
||
|
||
`microban-visuals.spec.js` 验证 20 个 body 的材质/纹理、原 visual 隐藏、非零根 yaw 和关节角下的对齐、失败回退,以及开关新视觉后 80 个控制周期的 qpos / qvel / ONNX action 逐项完全一致。截图保存于该测试的 `test-results/` 输出目录。行走原有三轮有界 70 s、三轮无界诊断 84 s 和 H / reset / 近 50 Hz 验证通过;20 次跨 Microduck / Microban / RP1 切换后,Microban 的 GPU 纹理数稳定为 48(46 张模型纹理加场景资源),无增长。
|
||
|
||
## 策略接口
|
||
|
||
| 项目 | 数值 |
|
||
|---|---|
|
||
| 输入 | `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);当前场地尺寸与碰撞验证见 [按机器人尺寸缩放场地](../superpowers/verification/2026-10-28-robot-scaled-arena.md)。只对记录的桌面 Chromium / WASM 组合做过验证;没有实机、移动端、手柄 / 触屏、15 小时耐久或不同浏览器的保证。模型和策略许可按原文件与来源说明分别核对。
|