OPENZROB目录
平台使用说明
适用于人和 AI 助手。网站：openzrob.com。当前支持 Bumi、宇树 G1 EDU、R1 EDU、Go2、B2、Go2-W、灵犀 X2、加速进化 K1、T1 和逐际 TRON1，每款提供 5 个连续任务。桥接版本为 0.9.5。更新日期：2026-11-06。
快速开始
- 在网站注册并验证邮箱；已有账号直接登录，未绑定邮箱的先完成绑定。
- 01 下载桥接程序：选择电脑对应的系统与架构，安装并启动，在桥接中选择机器人并点击「连接」。支持自动运控的机型首次需要等待环境准备完成。
- 02 选择机器人 → 03 选择场景：点击「连接并进入场景」，允许浏览器访问本机网络，保持场景页打开。
- 在对应的 SDK 环境中编写并运行本地任务程序，控制虚拟机器人。X2、K1/T1 的自动环境可用
bumi-bridge sdk 你的程序.py运行。外接相机使用下文的独立接口。
桥接连接本地程序与网页中的虚拟机器人。X2、K1、T1、TRON1 支持自动准备运控环境，无需手动填写安装路径。物理仿真、渲染和相机图像在浏览器运行。
| 运行位置 | 职责 |
|---|---|
| 用户 PC 的 Python / SDK 环境 | 安装相应机器人的官方 SDK，编写并执行视觉识别、巡线、跟随、导航和任务状态机 |
| 用户 PC 的桥接程序 | 转发指令、状态和相机数据；为支持机型准备基础运控环境，不代替用户开发任务算法 |
| 浏览器 | 模拟机器人关节和物理运动，呈现场景和相机，并检查任务结果；X2、K1、T1、TRON1 的官方运控或策略在用户 PC 运行 |
| 云端 | 账号、授权、资源分发、任务记录和积分，不执行用户的机器人 SDK 程序 |
浏览器内的黄线、人物和指令卡检测仅用于验收，不生成巡线、跟随或导航指令。正式实训关卡等待用户程序控制；键盘用于调试，不计入任务成绩。关闭账号入口的开发演示模式保留自动行走，与正式关卡不同。各型号只实现开发说明中列明的 SDK 接口，未完整复刻真机固件。
按机器人选择开发说明
网页与桥接应选择相同型号。下表与桥接的机器人配置由同一数据源生成。灵犀 X2 需官方 MC；K1、T1、TRON1 需在用户 PC 运行官方策略，这些型号默认由桥接自动准备运行环境，具体开发接口见对应说明。
| 机器人 | 平台开发说明 | 官方 SDK |
|---|---|---|
| Bumi | 接入说明 | 官方 SDK |
| 宇树 G1 EDU | 接入说明 | 官方 SDK |
| 宇树 R1 EDU | 接入说明 | 官方 SDK |
| 宇树 Go2 | 接入说明 | 官方 SDK |
| 宇树 B2 | 接入说明 | 官方 SDK |
| 宇树 Go2-W | 接入说明 | 官方 SDK |
| 智元灵犀 X2 | 接入说明 | 官方 SDK |
| 加速进化 K1 | 接入说明 | 官方 SDK |
| 加速进化 T1 | 接入说明 | 官方 SDK |
| 逐际 TRON1 | 接入说明 | 官方 SDK |
给 AI 助手的执行顺序
需要在用户电脑上具备浏览器或终端操作能力；仅能联网阅读的聊天模型无法启动本地桥接。
- 确认操作系统、CPU 架构，以及 SDK 是否与桥接位于同一个系统。不要把 Windows、WSL、虚拟机当作同一个网络环境。
- 先读取
http://127.0.0.1:8765/health。已有桥接时复用；端口被其他程序占用时先报告，不启动第二个实例。 - 没有桥接时，选择下表对应安装包。在用户已登录且已验证邮箱的浏览器中下载。注册、邮箱验证和浏览器权限提示需要用户参与时，停在该步骤等待完成。
- 启动桥接，等待
/health中service="bumi-local-bridge"、dds=true，且nonce为非空字符串。 - 在网站选择机器人及已解锁场景，点击「连接并进入场景」。不要自行打开
/sim或伪造网站授权。 - 再检查
sim=true和GET /v1/state返回 HTTP 200；巡线时还需camera=true且相机接口返回有效图像。 - 配置官方 SDK 的 DDS 网络，确认收到硬件状态回调。到这里才算 SDK 接入完成；仅
dds=true不代表 SDK 已连接。 - 向用户报告实际通过和未通过的检查。接入检查本身不需要让机器人运动；运动或巡线按用户后续任务执行。
不要把密码、邮箱验证码、会话 Cookie 或桥接授权票据写入代码、日志或分享给其他服务。
下载与启动
安装包下载需要已登录并验证邮箱；未登录请求返回 HTTP 401。下列地址是实际安装包，不是 SDK。不要把错误页面保存成安装包，也不要假设命令行下载会自动继承浏览器登录状态。
| 系统 | 架构 | 安装包 |
|---|---|---|
| Windows | x64 / AMD64 | Windows 安装包 |
| Linux | x86_64 / amd64 | Linux x86_64 安装包 |
| Linux | aarch64 / arm64 | Linux ARM64 安装包 |
Linux 适用于 Ubuntu 22.04 / 24.04 及兼容的 Debian 系统。ARM64 包已通过指令仿真测试，尚未完成实体 ARM 设备验证。不提供 macOS、Windows ARM 或 32 位安装包。
Windows
运行安装包，从开始菜单打开 擎云机器人仿真实训平台桥接程序，选择与网页一致的 机器人 并点击「连接」。最小化后继续运行；关闭窗口会停止由本窗口启动的桥接。界面可以查看连接状态、运行检查和日志。默认安装目录为 %LOCALAPPDATA%\Programs\BumiBridge。PowerShell 也可以执行：
& "$env:LOCALAPPDATA\Programs\BumiBridge\bumi-bridge.cmd" start
start 会持续运行；在另一个终端检查状态：
& "$env:LOCALAPPDATA\Programs\BumiBridge\bumi-bridge.cmd" status
& "$env:LOCALAPPDATA\Programs\BumiBridge\bumi-bridge.cmd" doctor
Linux
在安装包所在目录执行，按架构只选择一条安装命令：
# 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：
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：
Invoke-RestMethod http://127.0.0.1:8765/health
Linux：
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 开发说明 和 R1 开发说明，不要使用本节的 Bumi 导入路径与主题。
用户自行安装官方 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 配置：
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 分。原来的截图、图像处理、标定、目标检测、测距标定、传感器表格六个独立实验已取消；相关能力由用户在完整任务中自行开发，不再按两个篇章各五课时组织。
用户开发流程
- 下载并启动桥接，安装官方 SDK，登录后选择机器人和任务。
- 保持场景打开，在本地编辑器中创建自己的程序。
- 读取当前任务的原始 RGB 图像、机器人姿态、关节与 IMU 数据。
- 自行实现感知、决策和任务逻辑，通过官方 DDS SDK 发送控制指令。
- 在网页观察机器人，按任务切换道路遮挡、人物显隐或指令卡，验证自己的程序。
- 实际运动达标后自动记录通关和积分。仅打开相机、点击场景按钮或用键盘行走均不算完成任务。
第 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 和 bumi_sim.py，放在同一目录。安装 numpy 后运行：
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 专用开发说明 和 Markdown 说明。五个任务的通关进度分别记录。
宇树 R1 EDU
第三台机器人 R1 EDU 使用 26 自由度模型和宇树原版 R1 SDK2 客户端，包含头部俯仰与偏航关节。请安装 0.9.5 桥接并选择 R1，参阅 R1 专用开发说明 和 Markdown 说明。SDK 和任务程序在用户 PC 上运行，浏览器提供虚拟机器人；当前步态为社区策略，具体来源与接口范围见专用说明。
四足机器人与筛选
选择页可以同时按品牌（松延动力、宇树科技）和种类（四足、人形）筛选。Go2-W 为轮足机器人，归入四足。Go2、B2 为 12 个腿关节；Go2-W 为 12 个腿关节加 4 个轮电机。使用 0.9.5 桥接，按 四足开发说明 安装原版 SDK，并在本地编写、运行任务程序。六款机器人分别保存任务进度。