# 灵犀 X2：官方运控验收与本地开发

更新：2026-11-06。X2 基础运控已通过原生 MuJoCo 和浏览器两轮验收。SDK、官方 MC 和 ROS 2 适配器在用户电脑上运行，浏览器只运行虚拟机器人、物理仿真和摄像头。

## 自动连接

桥接 0.9.5 默认自动准备 ROS 2、AimDK 消息与官方 MC，再启动运控。选择 X2 后点击“连接”，无需填写目录。Windows 首次可能需要安装系统运行组件并重启，详情见[自动运控环境](/automatic-runtime.html)。下文手动命令供“高级设置”的自定义环境使用。

## 验收结果

使用官方 X2 Ultra v1.3 模型（31 个驱动关节）、MC `mc-x86-v1.0.0-20260522`、`lx2501_3_t2d5` 配置和原版 `aimdk_msgs`。通过原生 ROS 2 服务注册控制源、切换运动模式，再通过官方速度话题控制机器人。没有修改官方运控二进制、替换步态或直接移动机器人根节点。

| 浏览器验收项目 | 实测结果 |
| --- | --- |
| 稳定站立 8 秒 | 机身高度约 0.654 m，保持直立 |
| 前进 8 秒 | 平面位移 3.20 m |
| 首次停车 | 最终平面速度 0.0052 m/s |
| 前进并转向 6 秒 | 航向变化约 111°，保持直立 |
| 最终停车 | 最终平面速度 0.0087 m/s |

完整采样在 [浏览器验收数据](x2-browser-acceptance.json) 和 [原生验收数据](x2-native-acceptance.json)。浏览器各阶段仿真时间/墙钟时间约为 0.85～0.90，原生测试约为 0.99；本次通过的是功能闭环验收，不代表浏览器达到硬实时控制器的时序保证。输入速度与实际速度存在跟踪偏差，不能把设定值当作实测速度。

X2 已接入统一机器人列表、五个实训场景、账号授权与积分流程。桥接 0.7.0 增加 X2 选项和运控设置。Python 和 C++ 用户程序均使用原版 ROS 2 消息与服务。

## 五个完整任务

X2 使用与其他机器人相同的顺序解锁规则：起步、转向与停车 → 沿线巡航与断线停车 → 人物跟随与丢失恢复 → 看懂指令卡并行动 → 检测、报信与自主返航。每关首次完成获得 10 分，进度按账号与机器人分别保存；管理员自动解锁。每关有独立场景与封面。

平台提供物理机器人、头部摄像头、场景和结果验收。巡线、跟随、指令识别和任务规划由用户在电脑上的 Python/C++ 程序实现。官方 MC 负责实际关节运控。适配器同步官方 MC 当前选中的控制源速度指令，关卡依据真实位移、姿态和停车结果验收，不以发送指令替代运动结果。

头部前缘向前 5 cm 处保留前视和下视镜头。X2 下视镜头向前倾斜 36°，避免胸口和黄色脚部遮挡巡线视野；标定信息包含实际方向。暂停时相机仍持续采样，便于测试道路遮挡、人物显隐和指令卡切换。

第一关已通过原版 SDK、官方 MC、签名桥接和真实浏览器的完整验证：通关加 10 分、解锁第二关、刷新保留进度，其他机器人的进度保持独立。详见 [关卡验收记录](x2-course-acceptance.json)。这项记录验证第一关完整闭环，其余任务仍由用户编写算法完成。

## 本次修复

- QEMU 默认 CPU 未暴露 AVX，官方库在 `vmovdqu` 处触发非法指令；启动器改为 `-cpu max`。
- 官方 MC 需要可写的 `/agibot/data/var`；缺少权限会导致初始化失败。
- 官方包的监控插件在本机退出时崩溃；本地启动脚本通过官方开关禁用该监控插件，原版 MC 已验证可启动、退出。
- 物理步长恢复为官方 1 ms，关节状态、躯干/胸部 IMU 和里程计从真实仿真数据生成。
- 高频链路改用 C++ 原生 ROS 2 适配器；Python 适配器保留用于底层调试。原 Python 链路在本机实测仅约 80 Hz，不用于本次行走验收。
- 官方策略的 PD 位置目标可能超出关节机械限位，此前整帧拒收造成失稳。现在保留目标，由 MuJoCo 的关节约束与执行器力矩限幅执行。
- 零力矩待机不提前放开机器人；收到实际驱动指令才开始仿真。后续显式暂停不会被持续到来的指令解除。

## 准备电脑上的 SDK 与适配器

环境：Ubuntu 22.04、ROS 2 Humble、支持 AVX 的 x86_64 CPU。将官方 X2 SDK 的 `aimdk_msgs` 放入 ROS 工作空间并按官方说明编译。推荐原生 Linux；本项目 Windows 验收使用 QEMU/WHPX，分配 8 个虚拟 CPU。

```bash
source /opt/ros/humble/setup.bash
source /path/to/x2_workspace/install/setup.bash
sudo apt install libwebsocketpp-dev nlohmann-json3-dev libboost-system-dev
cmake -S native -B .runtime/x2-native -DCMAKE_BUILD_TYPE=Release
cmake --build .runtime/x2-native -j2
sudo install -d -o "$(id -un)" -g "$(id -gn)" /agibot/data /agibot/data/var
```

项目 Windows VM 启动器支持环境变量 `OPENZROB_VM_CPUS=8`。该变量只对新启动的 VM 生效；已运行的 VM 需要关闭后重新启动。默认 Bumi 环境仍为 2 个虚拟 CPU。

## 安装包启动与进入关卡

1. 手动模式：安装当前桥接，选择「智元灵犀 X2」。官方 AimDK 工作空间与 MC 需按上文提前安装在用户电脑上，基础安装包不内置，自动模式会按需获取。
2. 打开「高级设置」，选择自动启动，填写已编译工作空间与 MC 根目录。Linux 直接运行；Windows 使用已安装 ROS 2 Humble 的 WSL Ubuntu，并填写 WSL 内的 Linux 路径。Windows 的桥接仍在主机上运行，建议 WSL 镜像网络以访问 `127.0.0.1`，也可填写可达的主机地址。
3. 启动桥接。首次启动会编译 C++ 传输适配器，再启动适配器与官方 MC。若已有 QEMU、其他 VM 或自己的启动脚本，可选择「外部启动」，手动运行下面两个 Linux 进程，连接设置中的桥接地址。
4. 登录网页，选择「智元灵犀 X2」和已解锁关卡，点击「连接并进入场景」。网页使用账号签发的授权连接本机桥接。
5. 下载场景中的 `x2_student.py` 到自己的 ROS 环境。默认只读取状态；在自己的任务程序中调用 `enable_control()` 与 `set_velocity()`，并实现该关的感知和控制逻辑。也可直接使用官方 Python/C++ 示例。

官方公开 MC 本次验证使用 x86_64 包；ARM64 桥接可作为传输端，但不能直接运行这个 x86_64 运控二进制，需要可用的匹配架构 MC 或外部运控电脑。

## 外部启动与开发调试

日常实训使用安装包的账号授权桥接。下面的无账号开发桥接仅用于独立调试模型，不用于网页账号关卡：

```bash
npx tsx scripts/vendor-bridge.ts --robot x2 --port 8765 --origin http://127.0.0.1:5173
```

外部启动模式在 Linux 端运行 C++ 适配器，地址与实际桥接一致：

```bash
source /opt/ros/humble/setup.bash
source /path/to/x2_workspace/install/setup.bash
.runtime/x2-native/x2_ros_bridge ws://127.0.0.1:8765/dds
```

若 SDK 位于项目 QEMU VM 内、桥接位于 Windows 主机，使用 `ws://10.0.2.2:8765/dds`。其他虚拟化环境使用其对应的宿主地址或本地端口转发。

新开 Linux 终端启动原版 MC，再在网页进入关卡：

```bash
source /opt/ros/humble/setup.bash
bash scripts/x2-mc.sh /path/to/mc-x86-v1.0.0-20260522
```

所有 ROS 进程使用相同的 `ROS_DOMAIN_ID`。随后运行官方示例：

```bash
source /opt/ros/humble/setup.bash
source /path/to/x2_workspace/install/setup.bash
ros2 run py_examples set_mc_action SD
ros2 run py_examples set_mc_action LD
ros2 run py_examples mc_locomotion_velocity
```

官方示例按提示输入前进、侧向、角速度。按照官方仿真说明，转向使用前进速度与角速度组合；纯角速度不保证启动步态。复位前先切换 `PASSIVE_DEFAULT` 并确认实际模式已切换，避免仍在发送的上一轮驱动指令立即释放复位后的机器人。

## 可重复验收

已有网页、C++ 适配器和 MC 正常运行时，在已 source SDK 的 Linux 终端执行：

```bash
python3 tests/dds/x2_acceptance.py --bridge http://127.0.0.1:8765 --report docs/x2-acceptance.json
```

该脚本会复位机器人并执行站立、前进、停车、转向、再次停车，检查真实物理位移、姿态、速度和仿真进度。失败时返回非零退出码并保存已采集的数据。跨项目 VM 时将 HTTP 地址改为 `http://10.0.2.2:8765`。

不打开网页的原生对照实验可使用 `npx tsx scripts/vendor-joint-harness.ts x2 18770`，它运行同一份模型与控制器。将 C++ 适配器和验收脚本改为连接 18770，不能与网页同时占用同一个模拟器连接。

常规检查：`npm test`、`npm run build`、`python -m unittest discover -s tests -p '*_test.py'`。

## 来源

- [X2 官方模型](https://github.com/AgibotTech/agibot_x2_urdf)
- [X2 官方仿真流程](https://x2-aimdk.agibot.com/zh-cn/latest/sim_contents.html)

模型来源提交与授权文件保留在 `public/robots/x2/`。模型和元数据由 `python scripts/import-vendor-models.py /path/to/vendor-repositories` 生成，不手动修改生成文件。