正在连接信源…

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,并以无界面模式运行加速度计世界。

常见问题

  • 扰动力必须每个仿真步重新施加,且容易误用 #14
  • 无头执行在启动、显示和多关节配置下不可靠 #3 #5 #6
  • 默认测试框架跟踪可使仿真步慢数百倍 #4
  • wgpu-native 缺失或不受支持会完全阻止渲染 #7 #8
  • Windows 安装报告就绪,但运行时一致性检查失败 #9 #11
  • 控制器握手失败被错误报告为 ABI 不匹配 #15
  • 开箱即用的机器人模型无法稳定悬停或到达指令距离 #10 #17
  • ROS 时间假设可能导致命令和时钟发布停滞 #22 #24

文档