141 lines
4.7 KiB
Markdown
141 lines
4.7 KiB
Markdown
# 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、合并本地分支以及任何远程写操作。
|