VR 遥操作¶

使用 VR 头显和手柄控制机器人。

支持的头显¶

头显	支持级别	模式	说明
Pico 企业版	推荐	Web、XRoboToolkit	USB 网络共享；使用自己的 App，不是消费版 Pico App
Pico 消费版	支持	Web、XRoboToolkit	头显 App 与企业版不同；本文不记录 USB 网络共享路径
Meta Quest	支持	Web、XRoboToolkit	消费级产品更容易买到

Pico 企业版与消费版

将 Pico 企业版 和 Pico 消费版 视为不同 SKU。不要把同一个头显 App 写成同时覆盖两者。

USB 网络共享 — Pico 企业版可通过 USB 与 ROS 2 主机共享网络。这是企业版能力，不是消费版 Pico 的路径。
不同的 App — 企业版与消费版 Pico 使用不同的头显 App。请安装与头显版本匹配的 App。fa-py-libraries README 的 XRoboToolkit 路径是「XRoboToolkit App + PC Service」对比浏览器 WebXR；它没有给出同时覆盖两个 Pico 版本的商店条目。

商店链接、额外包名和 ADB 步骤以头显 / fa-py-libraries README 写明的为准。

前提条件¶

可用的机器人演示（mock、仿真或真实硬件）
VR 头显（推荐 Pico 企业版；也可用 Pico 消费版或 Meta Quest）
已安装 fa-py-libraries
头显与 ROS 2 主机之间的网络（Wi-Fi，或 Pico 企业版上的 USB 网络共享）
在机器人描述的 config/ocs2/target_manager.yaml 中设置 enable_vr: true（多数机型默认关闭）

控制器要消费 VR 目标之前，先在该 YAML 里把 enable_vr: true 打开。同一文件里相关字段：vr_update_rate（启用 VR 后生效）和 vr_follow_frame（全身跟随坐标系；见故障排除）。

概述¶

VR 遥操作根据 VR 手柄追踪发布末端执行器位姿目标。随后由 MPC 控制器生成关节轨迹以跟随这些目标。

手臂如何柔顺跟踪这些位姿取决于机型。VR 遥操作使用两条不同路径：

路径	机器人	柔顺由谁提供	控制器下发什么
MIT 力控	高擎 Panthera HT；方舟无限机械臂	控制器 + 驱动层走 MIT / `full_control`（位置 + 速度 + 力矩；刚度在 HI 上）	接口齐全时走带力控 / MIX
厂商关节阻抗	天玑；珞石	厂商栈，经驱动层暴露	仅位置

负载辨识属于厂商阻抗路径（天玑 / 珞石），不属于 MIT 路径。详见下文。

力控与柔顺¶

MIT 力控（Panthera HT / 方舟无限）¶

在 Panthera HT 和 方舟无限 机械臂上走这条路径。驱动层必须运行带力控的 MIT 配置；控制器再用位置 / 速度 / 力矩的组合跟踪 VR 位姿。

高擎 Panthera HT — ht-ros2-control README：

HI control_mode:=mit（默认；旧名 full_control 仍可用）
驱动下发位置 + 速度 + 力矩 + kp/kd（pos_vel_tqe_kp_kd）
刚度是 HI 参数 joint_kp / joint_kd（rqt / ros2 param），不是 kp/kd 命令接口
文档中的其他 HI 模式：effort（仅力矩）、position（仅位置）

方舟无限机械臂 — arx-ros2-control README：

机械臂只支持 full_control / MIT MIX。xacro 里写的其他 control_mode 会告警并被忽略
write() 始终下发位置 + 速度 + 力矩
MIT 的 kp / kd 来自 HI 的 joint_k_gains / joint_d_gains（没有 kp/kd 命令接口）
README 映射：OCS2 轨迹 → 位置；OCS2 future_input → 速度；OCS2 力矩 → 重力 / 静力学前馈力矩

控制器 — ocs2_arm_controller README — Interface Configuration：

模式由机器人配置自动检测（没有名为 force:= 的额外 launch 参数）
仅位置：命令 position；状态 position + velocity
力控 / MIX：命令接口同时具备 position、velocity、effort、kp、kd；YAML force_gains 为 [kp, kd]
方舟无限文档把 OCS2 MIX 写成位置 + 速度 + 力矩，kp/kd 在 HI 上。高擎说明：当 kp/kd 不是命令接口时，OCS2 可能停在位置模式；重力补偿改用 ht_gravity_compensation 或调大 joint_kp（同一份 HT README）

先按精简分支的 ./quick_start.sh / hardware:=real 拉起机器人：高擎 Panthera HT 或方舟无限 Lift 2S，再按下文启动 VR。

这条 MIT 路径不是同构遥操作。Panthera HT 上主从 mode:=mit / effort 见同构遥操作。

厂商关节阻抗（天玑 / 珞石）¶

此路径用于天玑与珞石。控制器只发 关节位置。关节阻抗 / 柔顺是厂商能力，在驱动层上切换。

天玑 — marvin-ros2-control README：

命令接口：关节 仅 position。状态：position、velocity、effort
运行时 ctrl_mode：POSITION / JOINT_IMPEDANCE / CART_IMPEDANCE / POWER_OFF
关节阻抗增益：joint_k_gains / joint_d_gains（7 维）。笛卡尔：cart_k_gains / cart_d_gains
示例：ros2 param set /<hardware_node> ctrl_mode JOINT_IMPEDANCE

珞石 — 同一模式（位置命令；柔顺在厂商驱动层）。参数名在开通后的私有 rokae-ros2-control README。概览：驱动层。

使用天玑 / 珞石臂的内部 FA 机器人见 fa-deploy-ws 配置。额外机器人 ID 和 launch 参数在开通后的该仓库 README。

负载辨识¶

负载辨识只在天玑 / 珞石（厂商阻抗）路径上。它不是 MIT / OCS2 force_gains 流程。

已核实的公开天玑向导（CCS 上半自动工具动力学辨识）：marvin-ros2-control scripts/tool_dyn_identify_wizard.py，安装后为 ros2 run marvin_ros2_control tool_dyn_identify_wizard（CMakeLists.txt 的 install(PROGRAMS … RENAME tool_dyn_identify_wizard)）。

向导标题是机械臂负载辨识向导（工具动力学参数辨识 / CCS）。它连接 Marvin 控制器 IP，先采空载再采带载 PVT 轨迹，并打印 10 维工具动力学（m, mx, my, mz, ixx, …）。这些值对应同一 README 里的 HI 参数 left_dyn_param / right_dyn_param。

公开的 open-deploy-ws 没有负载辨识流程。内部现场天玑负载辨识在开通后的私有 fa-deploy-ws README（默认分支通常是 fa-w2）。脚本名以该 README 为准，这里不列出。

设置¶

1. Install fa-py-libraries¶

cd ~/
git clone https://github.com/fiveages-sim/fa-py-libraries.git
cd fa-py-libraries
./init.sh all

公开克隆用 HTTPS。若本机已有密钥，SSH（git clone git@github.com:fiveages-sim/fa-py-libraries.git）为可选项。

./init.sh all 做什么：子模块 + Python 3.12 环境 + ros2_robot_interface / ros2-viser / vr_pose_publisher。

2. Start Robot Demo¶

source ~/open-deploy-ws/install/setup.bash
ros2 launch ocs2_arm_controller demo.launch.py

3. Start VR Bridge¶

在新终端中，于 fa-py-libraries 内执行（README 命令 — 没有 ./run.sh vr --mode）：

cd ~/fa-py-libraries
./run.sh vr

这会启动 Vuer/WebXR 的 VR 位姿发布器。

VR 模式¶

Pico 和 Meta Quest 都支持两种连接模式：

模式	连接	设置	延迟	命令
Web（WebXR）	基于浏览器	简单	较高	`./run.sh vr`
XRoboToolkit	原生应用 + PC Service	需要安装应用	较低	先 `./run.sh vr-xrt-service`，再 `./run.sh vr-xrt`

Web 模式（WebXR）¶

基于浏览器、使用 Vuer 的 VR — Pico 和 Meta Quest 均可使用：

./run.sh vr

在 VR 头显的浏览器中打开显示的 URL。无需安装应用。

XRoboToolkit 模式¶

更低延迟的原生应用 — 推荐用于生产环境。摘自 fa-py-libraries README：

./init.sh install-xrobotoolkit-pc-service
./init.sh install-xrobotoolkit
./run.sh vr-xrt-service
./run.sh vr-xrt

需要在头显上安装与版本匹配的 XRoboToolkit App（企业版 App ≠ 消费版 Pico App），以及 PC Service。./run.sh vr-xrt-service stop 关闭 PC Service。

主题¶

VR 遥操作发布到：

话题	类型	描述
`/teleop/left_ee_pose`	`PoseStamped`	左手目标位姿
`/teleop/right_ee_pose`	`PoseStamped`	右手目标位姿
`/teleop/head_pose`	`PoseStamped`	头部追踪
`/teleop/trigger`	`Bool`	手柄扳机状态

机械臂跟随¶

配置哪条机械臂跟随哪个手柄：

# In configuration or launch
teleop_config:
  left_arm: "left_controller"
  right_arm: "right_controller"
  # or for single arm:
  right_arm: "any_controller"

手柄按键（分体 vs 全身）¶

按键取决于当前跑的是分体（split_body.launch.py）还是全身（full_body.launch.py）。两种模式共用：

操作	动作
扳机	夹爪 — 按拉动比例开合；开合模式下点按切换
右 A / 左 X	FSM 前进（`HOLD`→`OCS2`，`HOME`→`HOLD`）/ 后退（`OCS2`→`HOLD`，`HOLD`→`HOME`）
左摇杆点击	镜像
右摇杆点击	`STORAGE` ↔ `UPDATE`（仅 OCS2）
握把（短按）	切换摇杆平面（`XY` ↔ `Z+Yaw`）

全身额外提供握把 + 摇杆（分体下忽略；FSM 须已在 OCS2）：

操作	动作
左握把 + 左摇杆	身体：上 = 竖直，下 = 锁定腰部，左 = 跟随，右 = 自定义锁定
右握把 + 右摇杆	WBC：上 = 双臂耦合开/关，下 = 底盘解锁/锁定，左 = 预留，右 = 参考关节追踪

握把 + 同侧扳机切换该扳机所映射夹爪的百分比 / 开合模式。左 Y + 右 B 为尺度对齐（关闭镜像并退回 STORAGE）。左右摇杆同时按下切换底盘遥控 ↔ 末端控制。

安全¶

运动限制

VR 遥操作可能发出快速运动指令。使用真实硬件时：

从较低速度限制开始
手放在急停开关上
清空机器人工作空间
在软件中使用工作空间限位

网络设置¶

头显与 ROS 2 主机必须处于可达网络（相同 Domain ID；按需使用 Zenoh 或 DDS）。

Pico 企业版： 支持 USB 网络共享 — 用 USB 将头显连接到电脑以共享网络。按头显自带的 USB 网络界面操作；本页不列出 ADB 或 usb0 命令。
Pico 消费版 / Meta Quest： 使用常规 Wi-Fi（或其他 IP）路径。不要假定有 USB 网络共享。

然后：

确认两台设备能够互相访问
若不在同一局域网，配置 ROS 2 Domain 或 Zenoh 桥接
为 ROS 2 端口设置防火墙规则

验证¶

VR 桥接日志显示追踪数据
ros2 topic echo /teleop/right_ee_pose 有更新
机器人跟随 VR 手柄运动

故障排除¶

没有追踪数据¶

确认 VR 设备追踪正常
确认浏览器/应用已获得 WebXR 权限
检查网络（Wi-Fi，或 Pico 企业版上的 USB 网络共享）
确认头显 App 与 Pico 版本匹配（企业版 vs 消费版）

延迟较高¶

优先使用 Pico 企业版（尽可能用 USB 网络共享）
使用 XRoboToolkit（./run.sh vr-xrt）而不是 WebXR
在头显版本支持时，使用有线 / USB 共享网络
在配置中降低更新频率
检查是否存在网络拥塞

机器人不跟随¶

确认描述包 config/ocs2/target_manager.yaml 中 enable_vr: true（多数机型默认关闭）
确认控制器处于遥操作模式（进入 OCS2 后再到 UPDATE）
确认目标位姿在工作空间内
确认没有触发安全限位

`base_footprint` 缺失（全身 / FULL_BODY）¶

全身控制可能警告 base_footprint 不存在（lookupTransform 的 target_frame）。默认 vr_follow_frame 是 base_footprint。在 config/ocs2/target_manager.yaml 里把 vr_follow_frame 改成机器人实际基座（例如 base_link）。

下一步¶

同构遥操作用于主从关节跟随（Panthera HT 的 mode:=mit / effort — 不是上面的 VR MIT 路径）
状态机与话题用于模式控制
ocs2_arm_controller — force_gains 与 MIX 检测
marvin-ros2-control — 天玑位置 + JOINT_IMPEDANCE
vr_pose_publisher — 已发布的 /teleop/* 话题

VR 遥操作¶

支持的头显¶

前提条件¶

概述¶

力控与柔顺¶

MIT 力控（Panthera HT / 方舟无限）¶

厂商关节阻抗（天玑 / 珞石）¶

负载辨识¶

设置¶

1. Install fa-py-libraries¶

2. Start Robot Demo¶

3. Start VR Bridge¶

VR 模式¶

Web 模式（WebXR）¶

XRoboToolkit 模式¶

主题¶

机械臂跟随¶

手柄按键（分体 vs 全身）¶

安全¶

网络设置¶

验证¶

故障排除¶

没有追踪数据¶

延迟较高¶

机器人不跟随¶

base_footprint 缺失（全身 / FULL_BODY）¶

下一步¶

`base_footprint` 缺失（全身 / FULL_BODY）¶