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

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

自动连接

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

验收结果

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

完整采样在 浏览器验收数据 和 原生验收数据。浏览器各阶段仿真时间/墙钟时间约为 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 分、解锁第二关、刷新保留进度，其他机器人的进度保持独立。详见 关卡验收记录。这项记录验证第一关完整闭环，其余任务仍由用户编写算法完成。

本次修复

• 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。

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 或外部运控电脑。

外部启动与开发调试

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

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

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

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，再在网页进入关卡：

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

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

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 终端执行：

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 官方模型
• X2 官方仿真流程

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