# 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` 使用以下固定顺序：

```text
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]`。

## 数据流

正常链路保持不变：

```text
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 中的按钮继续使用现有嵌套结构：

```json
{
  "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、合并本地分支以及任何远程写操作。