SparkRover Mini 复刻全流程
SparkRover Mini 从采购、打印、组装到装软件、标定和训练的 149 个步骤,附物料表、购买链接与官方出处。
SparkRover Mini 是一个配有机械臂、面孔和摄像头的课堂机器人。其制造发布包包含激光切割和 CNC 零件、3D 打印组件、制造程序、物料清单、接线清单以及分步装配指南。
采购
- 检查操作系统版本与系统配置
将机器与各元素对应的最低(Minimum)、良好(Good)和理想(Ideal)规格表逐一对比;注意 Ubuntu 22.04 的支持已弃用,将在未来版本中移除。
打印与加工
- 将 STL 切片为 G-code
运行 cura_slice.py,将 part.stl 切片为 part.gcode。零件位于床中心;--at x,y 可将其放到其他位置。
- 对 G-code 运行预检
preflight.py 在不启动引擎的情况下检查 G-code:时间、耗材、流量,以及 Klipper 会拒绝的内容。
- 生成打印世界文件
world.py 将仓库相对路径的 part.gcode 转换为 my_print.omniworld,即可打印该零件的世界。
- 用 SV08 配置文件切片 jobs/cube20.stl
使用 cura_slice.py 以 SV08 配置文件切片 jobs/cube20.stl:层高 0.2 mm,首层 0.25 mm,两道墙,10 % 网格填充,5 mm Brim,PLA 220 °C 打印。
- 在打印机双胞胎上无头打印立方体
在 sv08_printer_twin.omniworld 上以 Newton/MuJoCo CPU、2 ms 步长在 RTX 3060 Laptop 机器上无头打印。该打印速度约为实时的 2 倍。
- 选择理想打印机模型
使用 Ideal 进行零件几何、体积、层结构、流量和切片检查,以及长时间打印或多个变体。它与双胞胎打印机的平均外表面差异不超过 0.03 mm,外表面 p05/p95 差异不超过 0.06 mm,占脚印差异不超过 0.11 mm,高度、层数和体积相同。
- 选择双胞胎打印机模型
对于依赖机器运动的内容使用 Twin,包括转角过冲、轴调校和驱动系统对超尺寸的影响。也可使用它观察或拍摄打印过程。
- 仅构建 GUI 模拟器
运行 gui 构建子命令,它只构建 `src/omnisim`。
- 修改模拟器源码后进行重建
当你修改了 `src/omnisim` 下的文件(包括 `src/omnisim/render` 下的渲染代码)且未改动 `src/glad` 时使用此重建。
- 不要使用已废弃的 renderer 构建
该 renderer 配方已随 WREN 于 2026-08-23 被删除,子命令现在会给出说明并以非零退出码退出。请改用 `build core` 或 `build gui` 重建渲染代码。
- 构建控制器库与启动器
运行 controller-libs 子命令只构建控制器库和启动器。当你修改了 `src/controller` 或 `include/controller`,或在迭代控制器 API 与启动器行为时使用。
- 运行打包流程
运行 package 子命令执行打包流程;这不属于正常的快速迭代循环。
- 使用等价的 make 目标
仓库根目录的 Makefile 包装目标包括:`make sim-core`、`make sim-gui`、`make controller-libs`、`make tests-smoke`、`make benchmarks`、`make compile-commands`。不要使用 `make renderer`,它会打印 `Nothing to be done for 'renderer'` 并以 0 退出。
软件与固件
- 确认 Windows 版本
使用 Windows 10 或 11,并为 MSYS2、依赖项和构建产物预留约 10 GB 磁盘空间,另为必需的 Newton 运行时包预留约 1 GB。
- 安装 Windows 版 Git
安装 Windows 版 Git,以便克隆代码仓库。
- 安装 CPython 3.12
从 python.org 下载 Windows 版 CPython 3.12,并安装到默认的当前用户位置。Python 3.10 和 3.11 不可用。
- 设置代码检出路径
将 `OMNISIM_HOME` 设置为本地 OmniSim 检出目录的绝对路径。顶层 Makefile 会导出 `WEBOTS_HOME`,而 `build_omni.bat` 会从自身位置推导该路径。
- 安装 MSYS2
将 MSYS2 安装到 `C:\msys64`,然后打开 MSYS2 MINGW64 终端并更新系统软件包。
- 安装构建依赖
在 MSYS2 MINGW64 终端中安装列出的编译器、构建工具、Qt 6 模块、网络工具和归档工具。文档说明,`scripts/dev/setup_wgpu_native.sh` 使用 `curl` 和 `unzip` 获取并解压 wgpu-native 发行版,因此即使 Windows 的 `curl.exe` 已在 `PATH` 中,也要安装它们。
- 设置嵌套 Qt6 头文件
在 MSYS2 MINGW64 终端中,创建 `include/qt`,并将每个 `/mingw64/include/qt6/Qt*` 目录复制到项目下对应的嵌套目录。
- 克隆并检出 GLM
如果 `src/glm` 为空,将 `glm` 仓库克隆到该目录并检出 1.0.1 版本。GLM 1.0.1 用于兼容 GCC 15。
- 克隆 STB 子模块
使用 `patch-1` 分支将用于图像加载的 `stb` 仓库克隆到 `src/stb`。
- 获取 wgpu-native 渲染器
每次克隆后、首次构建前运行一次安装脚本。它会将 wgpu-native 安装到 `$OMNISIM_HOME/_scratch/wgpu-native`,这是 Makefile 自动发现的路径。
- 使用 MSYS2 构建模拟器
在 MSYS2 MINGW64 终端中,使用全部可用处理器核心构建 release 目标。首次构建所需时间取决于硬件,为 5–25 分钟。
- 使用内置包装脚本构建
在仓库根目录的 `cmd.exe` 中运行内置包装脚本。它会从自身位置推导 `OMNISIM_HOME`,并调用 MSYS2 的 `make`。
- 配置非默认 MSYS2 路径
如果 MSYS2 未安装在 `C:\msys64`,请先将 `MSYS64_HOME` 设置为其安装路径,然后再使用内置包装脚本。
- 覆盖包装脚本的作业数
构建前设置 `MAKE_JOBS=N` 可覆盖包装脚本的作业数。更多作业可能更快,但会占用更多内存,满并行可能导致笔记本电脑卡顿。
- 仅构建核心模拟器
仅在迭代模拟器本身时构建核心模拟器 release 目标。此命令会跳过控制器库和示例项目。
- 仅构建控制器库
以 release 模式构建控制器库,同时向构建过程传入 `OMNISIM_HOME`。
- 设置模拟器运行时依赖
通过在全新构建后运行文档中的设置命令,使所需的 Qt6 插件和 MinGW DLL 在运行时可用。
- 复制 MinGW 运行库 DLL
将所有 MinGW 运行库 DLL 文件复制到 MSYS2 的 MinGW64 二进制目录。
- 安装 Qt6 平台插件
创建 platforms 目录,并复制用于窗口创建的 qwindows.dll 插件。
- 安装 Qt6 图像格式插件
创建 imageformats 目录,并复制加载 JPEG 和 PNG 纹理所需的 Qt6 图像格式插件。
- 安装 Qt6 TLS 插件
创建 tls 目录,并复制 HTTPS 所需的 Qt6 TLS 插件,以避免出现“No TLS backend”警告。
- 打开演示启动器
在仓库根目录运行自带的 launch.bat,不带参数。在演示启动器中,右键单击球形机器人,选择 Show Robot Window,然后从图库中选择一个演示。
- 打开指定世界
向 launch.bat 传入世界文件路径,直接打开指定的世界。
- 从 MSYS2 运行模拟器
导出所需的 PATH 条目,并在 MSYS2 终端中运行 omnisim-bin.exe。
- 构建附加控制台的调试二进制文件
构建受支持的调试目标。它会生成控制台子系统的 `omnisim-bin.exe`,使 stdout 和 stderr 显示在终端中;目标文件写入 `build/debug/`。
- 重新链接独立的控制台二进制文件
要保留 release 目标文件,可使用 Makefile 当前的 Windows `LIBS` 行将它们重新链接为独立的控制台二进制文件。如果重新链接因未定义符号失败,应阅读该 Makefile 行,不要自行猜测。
- 选择受支持的 Ubuntu 版本
使用 Ubuntu 24.04(Python 3.12 是系统解释器)或 Ubuntu 22.04(引导程序通过 deadsnakes 安装 Python 3.12)。
- 运行 apt 安装阶段
全新机器上的文档化流程从 apt 阶段开始。整个流程预计需要 25–45 分钟,其中 apt 阶段需要 2–6 分钟。
- 克隆 OmniSim 仓库
按照文档化安装流程的下一阶段克隆项目仓库。此阶段需要 1–3 分钟。
- 构建发布版本二进制文件
运行 `make release` 构建阶段。在 Ubuntu 22.04 上,构建会嵌入 Python 3.12,并使用 `ldd` 断言生成二进制文件的解释器链接;构建在 4 核上约需 14 分钟,在 24 核上约需 7 分钟。
- 安装 GPU 物理引擎轮子
将物理引擎轮子安装到构建后二进制文件所使用的同一个 Python 解释器中。物理引擎轮子安装阶段需要 2–4 分钟。
- 可选安装 PyTorch
如需 torch,可以安装它;这会为文档化流程增加约 2.5 GB 空间和数分钟时间。
- 在 Linux 上安装 OmniSim
运行引导脚本以安装并构建项目。
- 安装 apt 前置依赖
安装约 35 个 apt 软件包,包括 libdbus-1-dev、libvulkan1、mesa-vulkan-drivers、libxcb-* 软件包组和 python3-dev。不要安装 Qt6 开发包,因为构建会内置自己的 Qt 6.5.3。
- 提供 Python 3.11 或更高版本
确保引擎能够嵌入 Python 3.11 或更高版本。在 24.04 上无需操作;在 22.04 上,从 deadsnakes PPA 安装 Python 3.12,并通过 ensurepip 安装 pip。
- 获取源代码和子模块
克隆项目,获取固定为 1.0.1 版本的 glm 和 omichel 的 patch-1 分支中的 stb,并重新为 scripts/**/*.sh 设置可执行权限。
- 安装 wgpu-native 渲染器
运行 scripts/dev/setup_wgpu_native.sh 安装 wgpu-native。渲染器链接取决于 WGPU_NATIVE_HOME,并且构建结果必须包含 lib/webots/libwgpu_native.so。
- 构建发布版本
使用 make 和配置的 JOBS 数量构建发布版本。构建会通过 aqtinstall 自动获取 Qt 6.5.3,JOBS 默认设为 min(nproc, 32)。
- 安装固定版本的物理引擎栈
安装固定版本的物理引擎栈,并将其链接到 Python 解释器。
- 运行所有安装阶段
按顺序运行所有安装阶段;这是引导脚本的默认模式。
标定与测试
- 设置打印机轴的加速度前馈
加速度前馈等于轴的有效惯量除以刚度,而有效惯量并不是质量;world.py 计算该值并传给控制器。牛顿伺服电枢界限给出轻量位置伺服的电枢上限为 dt × kd,因此在 1 ms 子步和 kd = 10 kN·s/m 时,每个打印机轴都表现得像 10 kg,即使用于 0.65 kg 的工具头。
- 不做速度超前量修整
CNC 会按其 2 ms 子步的一半修整速度超前量,但在打印机的 1 ms 子步下实测该修整并不比不做更好,因此打印机不做超前量修整。驱动器保持对目标的速度与加速度前馈,并在静止时保留用于 Z 轴龙门重量的积分修整。
- 对比计划路径检查喷嘴误差
比较实测喷嘴位置与计划喷嘴位置之差,采样间隔 50 ms;短程运行中不计入以 30 mm/s 打印的首层。Z 轴全程保持在 0.010 mm 以内。
- 估算部件尺寸时考虑挤出道宽度
切片软件按矩形(线宽 × 层高)计量塑料,但实际挤出道是圆角,因此同样的体积会宽出 0.035 mm(每侧 0.017 mm)。轴的剩余误差和逐步宽度变化解释了其余的尺寸偏大。
- 应用挤出道修正后重新打印立方体
在挤出道修正之前,inspect_print.py 的层表显示首层偏宽 +3.2 mm,原因是慢速首层起始处的宽挤出道,而非 Brim;修正后首层为 +0.17 / +0.13 mm,与上层相当。使用临时引擎 omnisim-bin-v10beads 重新打印:铺设塑料 2850.27 mm³,0 次崩溃,27,128 个挤出道其中 721 个为团块,墙钟时间 532 s。
- 设置立方体和打印板偏移
将双胞胎打印机的喷嘴在立方体和打印板每侧向外偏移 0.02–0.03 mm。
- 设置外壳长壁偏移
在外壳的长壁上将喷嘴向外偏移 0.003 mm;外壳在 Y 轴方向长 0.06 mm。
- 验证测试工具变更
仅更改测试工具或世界文件时通常不需要重新构建。适当时直接使用 `--nomake` 运行验证。
- 运行渲染器测试循环
先构建 GUI,然后使用 `--nomake` 测试法线渲染世界。
- 运行运行时冒烟测试
使用 `--nomake` 构建 GUI 并运行冒烟测试。对于广泛更改,或影响物理或控制器同步的更改,改用核心构建。
- 运行控制器 API 测试循环
先构建控制器库,然后使用 `--nomake` 运行 API 测试组。
- 运行加速度计世界
构建 GUI,然后运行加速度计世界。
- 检查 OmniSim 日志
启动后,检查项目根目录中的 `omnisim_log.txt` 以诊断警告和错误。
- 验证 Newton 物理后端
通过 backend-verdict sidecar 确认 Newton 物理引擎。配备 NVIDIA/CUDA GPU 时,批处理配置使用 `newtonSolver "mujoco_warp"`;没有 GPU 时,默认的 `SolverMuJoCo` 仍可通过 CPU 运行物理模拟。
- 运行无界面冒烟测试
在 Xvfb 无界面模式下运行应用程序,并检查 sidecar。
- 在 Xvfb 下运行加载检查
在 Xvfb 下运行加载检查,因为即使使用 --no-rendering 也会创建 Qt/XCB 上下文。使用 --until-finalized,在 Newton 完成初始化且 sidecar 存在时立即停止,避免等待猜测的 --duration 或过早结束。
- 避免无害的 root 警告
以 root 身份运行时,每次都会打印警告。这在云端 Pod 和默认使用 root 的 WSL 环境中很正常且无害;可以添加非 root 用户来消除警告。
- 捕获诊断输出
运行诊断命令并保留其输出作为证据。
- 截图并检查加载
截取屏幕截图,并包含用于证明编辑后世界能够加载的加载检查命令。
- 在实现前定义成功标准
在实现机器人或任务之前,以物理单位或可观察状态定义成功。
- 说明成功和失败标准
说明成功运行和失败运行的标准。
- 运行制动评估测试
复现包含48个网格案例、12个细化案例和4次新确认的64案例测试,使用0.6 m/s目标和16 ms采样,并在CPU求解器上运行。
- 检查立即制动后的行驶距离
在5°下坡并安装10 kg负载时,检查STOP后2.5秒内的行驶距离;μ=0.10时测得1.13 m,μ=0.20时测得0.166 m。
- 调试时关闭轻量模式
以 `{"light": false}` 加载世界,使被静默的五种事件类型保持可用。`/sim/contacts` 在两种模式下均可响应。
- 检查无头运行中的失控物理
当测试结果需要证明物理行为,而不只是证明无头运行结束时,请添加 `--duration N --fail-on-runaway`。
- 定位并启用展示相机
使用 `controllers/showcase_camera` 作为携带一个 Camera 的运动学监督器。每次拍摄时等待 `at_s`,对于孪生机器人还要等待触发文件;然后移动到拍摄位置,以 +x 向前、+z 向上的方式瞄准目标且不产生滚转,并保存画面。
- 仅在拍摄期间启用相机
仅在每次拍摄前后短暂启用 Camera。近距离拍摄使用 `far` 值 2.5–3,因为 `far` 平面还决定相机阴影贴图的大小。
- 运行声明真实性检查
从 tests/benchmarks 运行声明测试以执行真实性检查。
采数据与训练
- 运行 Husky 评估扫描
运行 Husky 扫描,使用 12 次细化、2 次确认和 2 个工作线程,将结果写入 `.tmp/husky-assessment`。测试 0–20° 下坡、4 种摩擦设置和 0/10/20 kg 负载,目标速度为 0.6 m/s,并全程立即制动。
- 检查停车行为与证据
检查报告、逐步轨迹、原生捕获数据和精确测试条件。停车要求为 0.25 m,失败类型包括制动失败、无法达到速度、打滑或倾覆。
- 构建并验证 Husky 交付包
构建并验证 `projects/assessments/packages/husky/SCOPE.md` 描述的 100 美元 Husky 交付包。其中包括 64 个参考控制器制动评估回合、报告、原始证据、可复用测试和离线 Windows 运行环境。
- 认证 Jackal 评估配置
使用 1 个工作线程,在新的输出目录中启动 Jackal 配置。其他机器人类别需要任务专用适配器。
- 创建机器人专用评估包
使用共享评估包工厂选择模型的速度、负载夹具、要求和声明。运行认证活动并检查 Windows 交付包。
- 运行 Go2 和 G1 评估
运行 17 个 Go2 行走/站立/行走回合和 14 个 G1 站立回合。选定的 G1 站姿通过 32 秒测试以及留出的 48/60 秒站立检查。
- 运行 Husky 混合表面评估
在物理刚性摩擦片上运行 Husky 制动和 90 度转弯评估。冻结研究包含 76 个回合,比较 0.6 m/s 巡航与 0.35 m/s 的映射表面速度上限。
- 运行轮式模型覆盖测试
将制动适配器用于Husky、Jackal、ROSbot、ROSbot XL、TurtleBot3 Burger、Waffle或Waffle Pi,并运行35个空载和负载覆盖案例。
- 列出机器人清单和任务覆盖情况
运行机器人评估命令,查看完整的URDF清单及每个机器人的任务覆盖情况。
- 记录确切提示或命令
记录编辑演示时使用的准确提示或命令。
- 提供更改后的世界
提供包含可见编辑的更改后世界或小型补丁。
- 记录模型和资产来源
提供贡献内容中使用的模型和资产的来源信息。
- 运行正面案例和负面对照
提供一次正面运行和一次有意义的负面对照。
- 记录已知限制
记录已知限制,包括任何仅在视觉上有效的内容。
- 披露提供的评估资源
披露贡献者提供的任何资产、模型或评估数据。
- 运行打印世界
使用 omnisim run-world 命令运行生成的 my_print.omniworld。
- 以无界面方式导出打印珠粒
引擎在被要求时会写出其打印珠粒:设置 OMNISIM_PRINTED_PART_DUMP=part.beads,并以 duration 300 无界面运行。
- 对照 STL 检查打印珠粒
inspect_print.py 将导出的 part.beads 与原始 part.stl 对比,以测量打印结果。
- 显示 BuildBench 矩阵
从 tests/benchmarks 运行该命令以显示可表达性矩阵。
- 列出已注册的任务
从 tests/benchmarks 运行该命令以显示任务列表。
- 导出任务注册表
从 tests/benchmarks 运行该命令,以 JSON 格式输出完整注册表。
- 渲染并降采样展示画面
以 3200 x 2000 渲染画面,并使用 Lanczos 将其降采样为 1600 x 1000。画面上不绘制任何内容。
- 保存审阅画面但不发布
将原始画面、日志和备选角度保存到被 gitignore 的 `.tmp_showcase/` 目录。使用 `--review` 运行会将每个画面放入该目录,并且不会发布任何内容。
- 在 Linux 上运行强化学习训练器
强化学习训练器可在 Linux 上运行,包括 projects/policies/training/run_walk_rl.sh 等训练器。早期停止看门狗仅支持 MSYS,但训练本身可以正常工作。
用起来
- 打开 Warehouse Husky 世界
使用 OmniSim 打开 warehouse Husky 示例世界。
- 以无界面方式运行演示世界
使用支持的无界面运行契约运行 warehouse Husky 演示世界,并以结构化方式退出。
- 列出程序化世界配方
在生成世界之前,列出可用的程序化世界配方。
- 生成火星世界
使用种子 42 生成程序化火星世界,并写入 `my_mars.omniworld`。
- 启动生成的世界
启动生成的 `my_mars.omniworld` 世界。世界扩展名为 `.omniworld`;生成和创作的世界都使用此扩展名。
- 运行 G1 递送箱子演示
运行旗舰级 G1 递送箱子运动演示直至完成,以此端到端检查 Linux 安装。
- 在 Linux 上运行策略演示启动器
在 Linux 上按原样使用 Bash 策略演示启动器。自 v5.1 起,PowerShell 部署启动器也有对应的 Bash 版本。
- 运行 OmniSim Husky 演示
打开链接中的演示,观察 OmniSim 接收实时 AI 指令、回答后续问题,并让 Husky 返回基地。录制的结果是仿真,而不是硬件演示。
- 连接 OmniLink 账户
连接 OmniLink 账户,以获取 OmniKey 和模型连接。模型使用需要单独计费,Free 套餐也不例外。
- 在 OmniSim 中仿真机器人
使用 Newton 物理仿真刚体、接触、织物、软体和 CUDA 颗粒介质。OmniSim 提供 52 个演示世界和一个程序化世界生成器。
- 构建机器人的数字孪生
使用原生 URDF 导入或从 STEP 格式导入 CAD 来导入机器人。可使用 projects/robots/ 目录下的 20 多个厂商机器人软件包。
- 使用智能体编程和调试
将 Claude Code 或 Cursor 连接到第一方 MCP 服务器,以访问运行中仿真的 46 个工具。当机器人运行异常时,询问智能体实际发生了什么。
- 查看报告与重跑说明
打开 OmniLink 服务页面,获取评估报告、原生对比视频和公开重跑说明。
- 在 Husky 上运行 Nav2 规划
在 Husky 上使用 Nav2 进行端到端规划和目标执行,并采用真值里程计。该验证案例不是 SLAM、AMCL 或避障基准测试。
- 选择一个贡献方向
开始前,从首次编辑、机器人或任务、代理基准测试中选择一个方向。
- 添加机器人或任务
向 OmniSim 添加一个机器人、传感器、控制器行为或有界任务。
- 无界面运行世界
构建 GUI,并以无界面模式运行加速度计世界。