YikaiFu-cart/acRealman_xr

Fork 1

Files

T

YikaiFu-cart 378ba05be8 docs: 添加手柄输入扩展设计

2026-07-30 20:05:07 +08:00

4.7 KiB

Raw Blame History

XRoboToolkit 手柄输入扩展设计

背景

当前 xrobotoolkit_to_udp_bridge 已从 XRoboToolkit PC-Service SDK 读取左右手柄摇杆、主键和副键，但 udp_controller_receiver 只把 grip、trigger 和位姿写入 XrController，其余信息在 UDP 到 ROS2 的转换中丢失。

后续项目会使用 LeRobot 同时记录相机、RM75 状态和手柄输入。本次只补齐当前明确需要的手柄字段，不实现 LeRobot 录制，不改变现有机械臂控制逻辑。

目标

将左右手柄摇杆、主键和副键发布到现有 XrController 话题。
保持现有 grip、trigger 和 pose 的语义及控制行为不变。
兼容不包含新增字段的旧 UDP 数据包。
使用现有节点、消息和 UDP 协议，不增加依赖或新话题。
更新 README 和 AGENTS，记录接口及 Superpowers 的 Git 操作边界。

不在本次范围

Grip 和 Trigger 原始模拟量。
菜单键、摇杆按键、SDK 时间戳和 bridge 序号。
头显位姿、26 点手部骨骼、身体追踪和 Motion Tracker。
LeRobot 数据集录制、相机同步和 RM75 状态采集。
任何机械臂控制参数、安全逻辑或真机行为修改。

方案选择

采用直接扩展 XrController 的方案。相比新增 sensor_msgs/Joy 话题，该方案不需要额外同步左右手柄话题；相比继续只保留 UDP JSON，它能让 ROS2 和后续 LeRobot 适配层直接读取类型明确的数据。

修改消息定义后必须重新构建并重启相关节点。重新构建后的现有遥操作代码仍只读取原字段，不需要修改控制逻辑。

ROS2 消息格式

XrController.msg 使用以下固定顺序：

std_msgs/Header header
string hand

bool grip
float32 trigger
bool primary
bool secondary
float32[2] axis

geometry_msgs/Pose pose

字段语义：

primary：左手 X 键，右手 A 键。
secondary：左手 Y 键，右手 B 键。
axis：对应手柄摇杆的 [x, y]，每个分量限制在 [-1.0, 1.0]。

数据流

正常链路保持不变：

XRoboToolkit PC-Service SDK
→ xrobotoolkit_to_udp_bridge
→ UDP JSON
→ udp_controller_receiver
→ /xr/left_controller、/xr/right_controller
→ single_arm_velocity_teleop

bridge 继续读取 Grip 和 Trigger 模拟量并应用现有滞回，只是不再把未使用的 grip_value、trigger_value、menu 和 axis_click 放入 UDP JSON。

UDP 中的按钮继续使用现有嵌套结构：

{
  "grip": true,
  "trigger": 0.0,
  "axis": [0.2, -0.4],
  "buttons": {
    "primary": true,
    "secondary": false
  },
  "pos": [0.0, 1.0, 0.0],
  "quat": [0.0, 0.0, 0.0, 1.0]
}

udp_controller_receiver 将嵌套按钮展平到 ROS2 消息字段。现有遥操作节点忽略新增字段，因此目标位姿、夹爪触发和安全停止路径均不变化。

兼容与异常处理

旧 UDP 包缺少 axis 或 buttons 时，发布 axis=[0.0, 0.0]、primary=false、secondary=false。
新增可选字段格式错误时使用上述默认值，不丢弃有效的 Grip、Trigger 和位姿。
bridge 和 receiver 均将摇杆分量限制在 [-1.0, 1.0]。
旧包中存在 menu、axis_click 或其他按钮字段时忽略，不报错。
sample_udp_sender 保持旧格式，用它验证向后兼容，不为本次需求增加新参数。

文件范围

xr_rm_interfaces/msg/XrController.msg
xr_rm_input/xr_rm_input/xrobotoolkit_to_udp_bridge.py
xr_rm_input/xr_rm_input/udp_controller_receiver.py
xr_rm_input/test/ 下的一份最小兼容性测试
README.md
AGENTS.md

不修改 xr_rm_teleop 控制实现及三个机械臂 YAML。

README 与 AGENTS 规则

README 增加新的手柄字段、UDP 格式和兼容行为说明。

AGENTS 和 README 同时明确：使用 Superpowers 执行任务时，只允许按 skill 工作流创建本地 Git 提交；不得推送、合并或执行其他远程写操作。skill 如需本地 worktree 或配套分支，可以创建，但不得将其合并到其他分支。

验证

自动验证包括：

bridge 生成的 UDP payload 只包含确认保留的按钮和摇杆字段。
左手 X/Y 与右手 A/B 正确映射到 primary/secondary。
receiver 正确发布新增字段。
旧 UDP 包继续发布，新增字段使用默认值。
非法新增字段不会阻断现有 Grip、Trigger 和位姿。
在 /home/robot/WS_xr source ROS2 Humble 后运行相关 pytest。
运行 colcon build --symlink-install。

运行验证只使用 mock，不连接真机、不移动机械臂、不操作夹爪。

Git 边界

本设计和后续实现可以按 Superpowers 流程创建本地提交。禁止执行 git push、创建或合并 PR、合并本地分支以及任何远程写操作。

4.7 KiB Raw Blame History