# 平台使用说明

适用于人和 AI 助手。网站：[openzrob.com](https://openzrob.com/)。当前支持 Bumi、宇树 G1 EDU、R1 EDU、Go2、B2、Go2-W、灵犀 X2、加速进化 K1、T1 和逐际 TRON1，每款提供 5 个连续任务。桥接版本为 0.9.5。更新日期：2026-11-06。

## 快速开始

1. 在网站注册并验证邮箱；已有账号直接登录，未绑定邮箱的先完成绑定。
2. **01 下载桥接程序**：选择电脑对应的系统与架构，安装并启动，在桥接中选择机器人并点击「连接」。支持自动运控的机型首次需要等待环境准备完成。
3. **02 选择机器人 → 03 选择场景**：点击「连接并进入场景」，允许浏览器访问本机网络，保持场景页打开。
4. 在对应的 SDK 环境中编写并运行本地任务程序，控制虚拟机器人。X2、K1/T1 的自动环境可用 `bumi-bridge sdk 你的程序.py` 运行。外接相机使用下文的独立接口。

桥接连接本地程序与网页中的虚拟机器人。X2、K1、T1、TRON1 支持[自动准备运控环境](/automatic-runtime.html)，无需手动填写安装路径。物理仿真、渲染和相机图像在浏览器运行。

| 运行位置 | 职责 |
| --- | --- |
| 用户 PC 的 Python / SDK 环境 | 安装相应机器人的官方 SDK，编写并执行视觉识别、巡线、跟随、导航和任务状态机 |
| 用户 PC 的桥接程序 | 转发指令、状态和相机数据；为支持机型准备基础运控环境，不代替用户开发任务算法 |
| 浏览器 | 模拟机器人关节和物理运动，呈现场景和相机，并检查任务结果；X2、K1、T1、TRON1 的官方运控或策略在用户 PC 运行 |
| 云端 | 账号、授权、资源分发、任务记录和积分，不执行用户的机器人 SDK 程序 |

浏览器内的黄线、人物和指令卡检测仅用于验收，不生成巡线、跟随或导航指令。正式实训关卡等待用户程序控制；键盘用于调试，不计入任务成绩。关闭账号入口的开发演示模式保留自动行走，与正式关卡不同。各型号只实现开发说明中列明的 SDK 接口，未完整复刻真机固件。

## 按机器人选择开发说明

网页与桥接应选择相同型号。下表与桥接的机器人配置由同一数据源生成。灵犀 X2 需官方 MC；K1、T1、TRON1 需在用户 PC 运行官方策略，这些型号默认由桥接自动准备运行环境，具体开发接口见对应说明。

| 机器人 | 平台开发说明 | 官方 SDK |
| --- | --- | --- |
| Bumi | [接入说明](https://openzrob.com/guide.html) | [官方 SDK](https://github.com/Noetix-Robotics/noetix_sdk_bumi/tree/20750fda734da0ef4c2fe28226b0d506a1f32273) |
| 宇树 G1 EDU | [接入说明](https://openzrob.com/g1-guide.html) | [官方 SDK](https://github.com/unitreerobotics/unitree_sdk2_python) |
| 宇树 R1 EDU | [接入说明](https://openzrob.com/r1-guide.html) | [官方 SDK](https://github.com/unitreerobotics/unitree_sdk2_python) |
| 宇树 Go2 | [接入说明](https://openzrob.com/quadruped-guide.html) | [官方 SDK](https://github.com/unitreerobotics/unitree_sdk2_python) |
| 宇树 B2 | [接入说明](https://openzrob.com/quadruped-guide.html) | [官方 SDK](https://github.com/unitreerobotics/unitree_sdk2_python) |
| 宇树 Go2-W | [接入说明](https://openzrob.com/quadruped-guide.html) | [官方 SDK](https://github.com/unitreerobotics/unitree_sdk2_python) |
| 智元灵犀 X2 | [接入说明](https://openzrob.com/vendor-guide.html) | [官方 SDK](https://x2-aimdk.agibot.com/) |
| 加速进化 K1 | [接入说明](https://openzrob.com/booster-limx-guide.html) | [官方 SDK](https://github.com/BoosterRobotics/booster_robotics_sdk) |
| 加速进化 T1 | [接入说明](https://openzrob.com/booster-limx-guide.html) | [官方 SDK](https://github.com/BoosterRobotics/booster_robotics_sdk) |
| 逐际 TRON1 | [接入说明](https://openzrob.com/booster-limx-guide.html) | [官方 SDK](https://github.com/limxdynamics/limxsdk-lowlevel) |

## 给 AI 助手的执行顺序

需要在用户电脑上具备浏览器或终端操作能力；仅能联网阅读的聊天模型无法启动本地桥接。

1. 确认操作系统、CPU 架构，以及 SDK 是否与桥接位于同一个系统。不要把 Windows、WSL、虚拟机当作同一个网络环境。
2. 先读取 `http://127.0.0.1:8765/health`。已有桥接时复用；端口被其他程序占用时先报告，不启动第二个实例。
3. 没有桥接时，选择下表对应安装包。在用户已登录且已验证邮箱的浏览器中下载。注册、邮箱验证和浏览器权限提示需要用户参与时，停在该步骤等待完成。
4. 启动桥接，等待 `/health` 中 `service="bumi-local-bridge"`、`dds=true`，且 `nonce` 为非空字符串。
5. 在网站选择机器人及已解锁场景，点击「连接并进入场景」。不要自行打开 `/sim` 或伪造网站授权。
6. 再检查 `sim=true` 和 `GET /v1/state` 返回 HTTP 200；巡线时还需 `camera=true` 且相机接口返回有效图像。
7. 配置官方 SDK 的 DDS 网络，确认收到硬件状态回调。到这里才算 SDK 接入完成；仅 `dds=true` 不代表 SDK 已连接。
8. 向用户报告实际通过和未通过的检查。接入检查本身不需要让机器人运动；运动或巡线按用户后续任务执行。

不要把密码、邮箱验证码、会话 Cookie 或桥接授权票据写入代码、日志或分享给其他服务。

## 下载与启动

安装包下载需要已登录并验证邮箱；未登录请求返回 HTTP 401。下列地址是实际安装包，不是 SDK。不要把错误页面保存成安装包，也不要假设命令行下载会自动继承浏览器登录状态。

| 系统 | 架构 | 安装包 |
| --- | --- | --- |
| Windows | x64 / AMD64 | [Windows 安装包](https://openzrob.com/downloads/擎云机器人仿真实训平台桥接程序-0.9.5-Windows-x64.exe) |
| Linux | x86_64 / amd64 | [Linux x86_64 安装包](https://openzrob.com/downloads/擎云机器人仿真实训平台桥接程序-0.9.5-Linux-x86_64.deb) |
| Linux | aarch64 / arm64 | [Linux ARM64 安装包](https://openzrob.com/downloads/擎云机器人仿真实训平台桥接程序-0.9.5-Linux-ARM64.deb) |

Linux 适用于 Ubuntu 22.04 / 24.04 及兼容的 Debian 系统。ARM64 包已通过指令仿真测试，尚未完成实体 ARM 设备验证。不提供 macOS、Windows ARM 或 32 位安装包。

### Windows

运行安装包，从开始菜单打开 **擎云机器人仿真实训平台桥接程序**，选择与网页一致的 机器人 并点击「连接」。最小化后继续运行；关闭窗口会停止由本窗口启动的桥接。界面可以查看连接状态、运行检查和日志。默认安装目录为 `%LOCALAPPDATA%\Programs\BumiBridge`。PowerShell 也可以执行：

```powershell
& "$env:LOCALAPPDATA\Programs\BumiBridge\bumi-bridge.cmd" start
```

`start` 会持续运行；在另一个终端检查状态：

```powershell
& "$env:LOCALAPPDATA\Programs\BumiBridge\bumi-bridge.cmd" status
& "$env:LOCALAPPDATA\Programs\BumiBridge\bumi-bridge.cmd" doctor
```

### Linux

在安装包所在目录执行，按架构只选择一条安装命令：

```bash
# x86_64
sudo apt install ./擎云机器人仿真实训平台桥接程序-0.9.5-Linux-x86_64.deb
# ARM64
sudo apt install ./擎云机器人仿真实训平台桥接程序-0.9.5-Linux-ARM64.deb
```

有桌面环境时，从应用菜单打开擎云机器人仿真实训平台桥接程序或执行 `bumi-bridge gui`，再选择与网页一致的 机器人 并点击「连接」。界面依赖 X11 与中文字体，正常使用 apt 安装会安装推荐的图形库；中文缺字时安装 `fonts-noto-cjk`。

无桌面环境或 AI 自动接入，以普通用户运行，不使用 sudo：

```bash
bumi-bridge start
```

保持该终端运行。在另一个终端使用 `bumi-bridge status` 查看状态、`bumi-bridge doctor` 检查运行库；完成后用 `bumi-bridge stop` 或原终端 Ctrl+C 停止。`doctor` 通过不等于场景或 SDK 已连通。

桥接界面显示本地 IP、机器人 DDS IP 和真机参考 IP；当前同机模式双方使用 `127.0.0.1`，不创建虚拟网卡。Bumi 真机运控默认地址为 `192.168.55.102`，只作参考，不代表当前连接真机。官方 SDK 与开发文档可从桥接界面直接打开。

点击连接后先显示「等待网页接入」；网站进入场景且 DDS 在线时，网页和桥接均显示「已连接」。关闭场景或断开桥接后，两端会在数秒内更新状态。「已连接」不代表用户 SDK 已启动，仍需下面的硬件状态回调检查。

## 连接检测

默认地址：`http://127.0.0.1:8765`。这里的 127.0.0.1 指运行桥接的电脑和操作系统，不是云服务器。

Windows PowerShell：

```powershell
Invoke-RestMethod http://127.0.0.1:8765/health
```

Linux：

```bash
curl --fail --max-time 3 http://127.0.0.1:8765/health
```

| 检查项 | 通过条件 | 未通过时 |
| --- | --- | --- |
| 桥接服务 | HTTP 200，service 为 bumi-local-bridge | 检查启动终端和端口 8765 |
| 网站授权支持 | nonce 为非空字符串 | 使用当前 0.9.5 安装包，关闭旧桥接 |
| DDS 适配器 | dds=true | 查看 dds.log，运行 doctor |
| 网页场景 | sim=true | 登录网站并点击「连接并进入场景」 |
| 新鲜状态 | GET /v1/state 返回 200 | 保持场景页运行，检查网页加载错误 |
| 巡线相机 | camera=true，GET /v1/camera 返回 BCAM 图像 | 检查场景加载与相机画面 |
| 官方 SDK | Bumi 收到 subscribe_robot_hardware_status 回调；G1 / R1 收到 rt/lowstate 状态 | 检查 DDS domain、网卡、peers 和 SDK 环境 |

`/health` 的 `version=2` 是桥接协议版本，不是安装包版本。刚启动时 `sim=false`、`camera=false` 正常。场景连接后 nonce 仍属于当前桥接进程，重启后会变化。一次只打开一个仿真场景。

## 官方 SDK 与 DDS

本节为 Bumi 官方 SDK 3.1.0，固定参考提交 `20750fda734da0ef4c2fe28226b0d506a1f32273`。G1 与 R1 使用各自的 Unitree SDK2 客户端，分别参阅 [G1 开发说明](/g1-guide.html) 和 [R1 开发说明](/r1-guide.html)，不要使用本节的 Bumi 导入路径与主题。

- [官方使用文档](https://web.noetixrobotics.com/docs/)
- [对应版本 SDK](https://github.com/Noetix-Robotics/noetix_sdk_bumi/tree/20750fda734da0ef4c2fe28226b0d506a1f32273)

用户自行安装官方 SDK 及匹配的 Python/C++ 环境。Python 使用官方 `highcontrol_py` / `lowcontrol_py`，不要创建同名替代模块。Windows 桥接安装包不包含 Windows 版官方 SDK；SDK 在 Linux、WSL 或虚拟机中运行时需单独打通 DDS 网络。

默认 DDS domain 为 **0**。先启动桥接、连接场景，再启动 SDK。桥接配置和日志位置：

| 系统 | 配置目录 |
| --- | --- |
| Windows | `%LOCALAPPDATA%\BumiBridge` |
| Linux | `${XDG_DATA_HOME:-$HOME/.local/share}/bumi-bridge` |

目录中有 `bridge.json`、`dds.xml`、`bridge.log`、`dds.log`。设置 `BUMI_HOME` 时以指定目录为准。当前网站使用固定端口 8765，不应单独更改桥接端口。

SDK 与桥接在同一 Linux 系统时，启动 SDK 前可使用桥接的 DDS 配置：

```bash
export CYCLONEDDS_URI="$(cat "${BUMI_HOME:-${XDG_DATA_HOME:-$HOME/.local/share}/bumi-bridge}/dds.xml")"
python3 your_program.py
```

将 `your_program.py` 替换为自己的程序。若官方示例自行读取或覆盖 `config/dds.xml`，也需把该配置改为仿真网络。默认仿真配置使用 127.0.0.1、UDP、关闭组播，并将 peer 指向 127.0.0.1；不要沿用真机默认 peer 地址。

跨 WSL、虚拟机或电脑时，双方 DDS 配置的网卡和 peers 必须互通，且 domain 一致。不要依靠 localhost 端口转发代替 DDS UDP 网络，也不要把桥接 HTTP 服务直接改成公网监听。最简单的部署是浏览器、桥接和 SDK 在同一系统中运行。

| DDS topic | 方向 |
| --- | --- |
| Control_Cmd_Topic | SDK → 仿真 |
| Control_Mode_Topic | SDK → 仿真 |
| Motor_Cmd_Topic | SDK → 仿真 |
| Robot_Status_Topic | 仿真 → SDK |

高层控制通过 `HighController.instance()`、`init()`、`subscribe_robot_hardware_status(callback)`、`publish_cmd(x,y,z,action,index)`。按状态完成 START（需要时）→ SWITCH → WALK，分别等待 workmode 0 → 1 → 2，再持续发送 DEFAULT。x/y/z 为 [-1,1] 归一化值，正方向为前进、左移、左转，不是直接输入 m/s。

支持 WALK、DEFAULT、START、SWITCH、SWING、SHAKE、CHEER、21 关节底层控制及硬件状态回调。舞蹈、示教、起身和官方媒体接口尚未实现。高层指令间隔超过 500 ms 会停车；建议持续控制使用 10–15 Hz 或更高且符合官方文档的频率，结束时主动发送零指令。底层控制由用户负责平衡，停止调用 set_joint 不代表官方 SDK 后台线程停止发送。

## 本地接口与外接相机

实际能力先查询 `GET http://127.0.0.1:8765/v1/capabilities`。以下为平台接口，不是官方 SDK API；迁移真机时不能只替换 URL。

| 方法与路径 | 用途 |
| --- | --- |
| GET /health | 桥接、DDS、场景及相机在线状态 |
| GET /v1/capabilities | 当前支持能力 |
| GET /v1/state | 仿真状态，响应包含 state 和 ageMs |
| GET /v1/camera/info | 外接相机标定与图像信息 |
| GET /v1/camera | 最新一帧 BCAM RGB8 二进制图像 |
| WS /v1/camera | 订阅图像，每条二进制消息为一帧 |
| POST /v1/control | 仿真扩展 reset / estop / pause / resume |

场景或图像不可用时，状态/相机接口返回 HTTP 503。使用官方 SDK 做运动控制；上述仿真控制接口不能替代官方动作，也不能用于冒充 SDK 通关。第 1 关需通过 SDK 行走至少 2 米、转向 30° 并主动停稳 1 秒；第 2 关巡线、第 3 关跟随还需要完成目标丢失后的停车与恢复。

相机是用户增配的下视相机，不是官方相机，不使用 MediaController。当前画面 320×240、最高 15 fps。相机 WebSocket 地址为 `ws://127.0.0.1:8765/v1/camera`。

BCAM v1 头部固定 32 字节，数值为 little-endian：

| 偏移 | 类型 | 值或含义 |
| --- | --- | --- |
| 0 | char[4] | BCAM |
| 4 | uint8 | version=1 |
| 5 | uint8 | encoding=1（RGB8） |
| 6 | uint16 | headerBytes=32 |
| 8 | uint32 | sequence |
| 12 | uint16 | width |
| 14 | uint16 | height |
| 16 | uint64 | timestamp_us，仿真时间，非 Unix 时间 |
| 24 | uint32 | payloadBytes=width×height×3 |
| 28 | uint32 | rowStride=width×3 |
| 32 | uint8[] | RGB 图像，左上角开始，逐行排列 |

当前完整帧为 230432 字节。不要把它当作 JPEG、PNG 或 BGR；OpenCV 需按 RGB 处理或先转 BGR。sequence 相同表示重复帧。真机使用实际外接相机驱动和重新标定的数据。

## 常见问题

- **下载返回 401**：在网站登录并验证邮箱后重新下载。说明文档公开，安装包不匿名开放。
- **/health 无法访问**：桥接未启动，或检测命令与桥接不在同一个系统。先检查运行终端及端口。
- **dds=false**：查看 dds.log 和 doctor 输出；不要把网页已打开当成 DDS 就绪。
- **sim=false**：尚未连接场景、登录已过期，或另一场景占用连接。返回网站重新连接。
- **页面不能访问本机网络**：检查浏览器对 openzrob.com 的本机网络权限。
- **SDK 没有状态回调**：核对官方 SDK 版本、domain 0、双方 dds.xml、网络接口和 UDP 可达性。
- **相机 503**：等待场景加载，保持页面运行，检查右上角实时画面。
- **迁移真机**：运动 API 仅在已支持范围内保持兼容；更换真实 DDS 网络、相机驱动与标定。仿真动作轨迹、速度缩放及占位硬件数据不等于真机。

## 文档地址

- 网页版：https://openzrob.com/guide.html
- 同内容 Markdown：https://openzrob.com/guide.md
- AI 文档索引：https://openzrob.com/llms.txt

这些地址无需登录。网站登录态、场景授权和机器人控制仍按正常流程执行，不因 AI 阅读说明而跳过。

## 桥接程序在线更新

0.3.2 起可在桥接窗口点击「检查更新」，查看版本和更新说明。使用平台用户名、密码下载新版，密码不保存，下载结束注销该下载会话；不会退出浏览器中原有登录。安装包通过文件大小和 SHA-256 校验后，点击「安装升级」，确认断开当前连接。配置和日志保留。Windows 按安装向导完成；Linux 请求系统管理员权限，安装结束重新打开程序。没有 pkexec 时按提示执行 apt 安装命令。较早版本需先从网站手动安装一次 0.3.2。

## 积分与机器人进度

每台机器人每个场景首次通关获得 10 分，重复练习不重复计分，当前可用任务的通关记录计入总分，已取消任务的历史记录保留但不计入当前积分。头部「积分榜」展示排名和总积分，同分并列。榜单仅显示用户名、通关场景数与积分，不展示邮箱。

各机器人独立记录进度：换到未训练过的机器人，必须从第一关开始，完成后逐关解锁。切回已训练的机器人会保留它自己的通关进度。




## 五个完整机器人开发任务

平台提供虚拟机器人、物理仿真、任务场景、原始相机与状态接口，并根据用户程序驱动的实际运动验收。识别、标定、测距、控制决策和状态机全部由用户在本地实现。网页不提供一键识别、图像处理、模型推理或自动标定。

### 任务顺序

| 关卡 | 完整任务与验收 |
|---|---|
| 1 · 起步、转向与停车 | 编写运动控制程序，让机器人前进至少 2 米、转向至少 30°，最后主动停稳 1 秒。 |
| 2 · 沿线巡航与断线停车 | 编写视觉巡线程序，沿黄线连续行走 5 米；道路被遮挡后主动停车，恢复道路后继续巡线。 |
| 3 · 人物跟随与丢失恢复 | 编写人物跟随程序，连续跟随 5 米并保持 1～3 米距离；目标消失后停车，重新出现后恢复跟随。 |
| 4 · 看懂指令卡并行动 | 编写视觉指令程序，看见开始卡后行走至少 0.25 米，看见停止卡后主动停稳 1 秒，完成两轮。 |
| 5 · 检测、报信与自主返航 | 编写完整任务状态机，从 HOME 出发，在 A 站停车确认人物，在 B 站停车确认 ID 2 路标，最后自主返回 HOME 停稳。 |

五关依次解锁，每关首次完成 10 分，当前一台机器人共 50 分。原来的截图、图像处理、标定、目标检测、测距标定、传感器表格六个独立实验已取消；相关能力由用户在完整任务中自行开发，不再按两个篇章各五课时组织。

### 用户开发流程

1. 下载并启动桥接，安装官方 SDK，登录后选择机器人和任务。
2. 保持场景打开，在本地编辑器中创建自己的程序。
3. 读取当前任务的原始 RGB 图像、机器人姿态、关节与 IMU 数据。
4. 自行实现感知、决策和任务逻辑，通过官方 DDS SDK 发送控制指令。
5. 在网页观察机器人，按任务切换道路遮挡、人物显隐或指令卡，验证自己的程序。
6. 实际运动达标后自动记录通关和积分。仅打开相机、点击场景按钮或用键盘行走均不算完成任务。

第 2、3 关在机器人已行走后分别遮挡道路、隐藏人物，等待用户程序主动停车，再恢复目标并继续运动。第 4 关每轮需在 ID 1 卡下通过 SDK 行走至少 0.25 米，然后在 ID 2 卡下主动停稳 1 秒。第 5 关的任务路线为 HOME（0,0）→ A（2,0）→ B（5,0）→ HOME，各站主动停稳 1 秒；A 站需人物处于前方相机可见范围，B 站需 ID 2 路标可见。导航、识别与状态切换由用户编写。

网页右侧相机是原始观察画面。网页只调整测试条件，不向用户程序返回识别答案、目标距离或任务状态机阶段。姿态、IMU、关节状态来自机器人状态接口；平衡与行走策略属于虚拟机器人底层能力，不替用户完成巡线、跟随或导航任务。

### 开发起点

下载 [student_task.py](/starter/student_task.py) 和 [bumi_sim.py](/starter/bumi_sim.py)，放在同一目录。安装 numpy 后运行：

```sh
python -m pip install numpy
python student_task.py --duration 10
```

模板只连接和读取原始数据，不执行任务、不让机器人自主运动。用户自行添加视觉算法与官方 SDK 控制代码。运动 SDK 接入及相机协议见使用说明前文。

`GET /v1/camera` 返回当前任务相机的 RGB8 帧，`GET /v1/camera/info` 返回内参和安装信息，`GET /v1/state` 返回机器人状态。任务选择前视或下视相机；不需要在网页加载 ONNX 模型。

### 人体检测与骨骼关键点

当前平台没有内置人体骨骼关键点识别。场景人物的关节摆动只是三维动画。旧版本实验台曾使用 YOLOv8 人体检测框，该网页推理功能已移除。

用户可在自己的程序里选择人体检测框、骨骼关键点或其他适合任务的方法；模型由用户程序加载和运行。平台不强制使用特定模型，不向程序提供人物骨骼坐标。内部验收仍通过位置与可见性观测检查实际行为，不会用这些观测结果替用户控制机器人，也不能据此证明用户采用了某一种算法。

### 记录兼容

五个保留任务的场景 ID 不变，旧通关记录可继续使用。六个取消关卡的历史记录不删除，但不再出现在目录、当前总分或排行榜中。管理员自动解锁当前可用任务并获得当前任务积分，重复访问不会重复加分。

## 宇树 G1 EDU

第二台机器人 G1 EDU 使用宇树原版 SDK2，与 Bumi 的 SDK 接口不同。请安装 0.9.5 桥接并选择对应机器人，参阅 [G1 专用开发说明](/g1-guide.html) 和 [Markdown 说明](/g1-guide.md)。五个任务的通关进度分别记录。

## 宇树 R1 EDU

第三台机器人 R1 EDU 使用 26 自由度模型和宇树原版 R1 SDK2 客户端，包含头部俯仰与偏航关节。请安装 0.9.5 桥接并选择 R1，参阅 [R1 专用开发说明](/r1-guide.html) 和 [Markdown 说明](/r1-guide.md)。SDK 和任务程序在用户 PC 上运行，浏览器提供虚拟机器人；当前步态为社区策略，具体来源与接口范围见专用说明。

## 四足机器人与筛选

选择页可以同时按品牌（松延动力、宇树科技）和种类（四足、人形）筛选。Go2-W 为轮足机器人，归入四足。Go2、B2 为 12 个腿关节；Go2-W 为 12 个腿关节加 4 个轮电机。使用 0.9.5 桥接，按 [四足开发说明](/quadruped-guide.html) 安装原版 SDK，并在本地编写、运行任务程序。六款机器人分别保存任务进度。