docs: 添加手柄输入扩展设计
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
# 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、合并本地分支以及任何远程写操作。
|
||||
Reference in New Issue
Block a user