# Qnbot 外骨骼 Demo 工作空间

Qnbot 外骨骼遥操作演示项目，用于展示外骨骼数据接收、可视化和机器人控制映射功能。

## 包结构

本工作空间包含三个 ROS2 包：

### 1. interface_protocol
**消息接口定义包**

定义了外骨骼系统所需的自定义消息类型：
- `ExoFullState.msg` - 外骨骼完整状态（关节+双IMU+复位标志）
- `ImuInfo.msg` - IMU 数据（四元数、欧拉角、加速度、角速度）
- `JointCommand.msg` - 关节命令
- `JointState.msg` - 关节状态
- `HandCommand.msg` - 手部/夹爪命令

### 2. qnbot_teleoperator
**外骨骼遥操作核心包**

主要功能：
- **WebSocket 服务器**：接收外骨骼实时数据（端口 19091）
- **RViz 可视化**：显示外骨骼 URDF 模型和实时姿态
- **Retargeting 配置**：外骨骼关节到机器人关节的映射配置
- **协议解析**：解析外骨骼数据协议

### 3. qnbot_replay
**数据回放包**

通过 Action Server 回放 `.msgpack` 格式的录制数据，支持：
- WebSocket 数据流回放
- 回放速度控制
- 回放进度查询

## 快速开始

### 克隆与编译
```bash
# 创建工作空间并克隆
mkdir -p ~/your_workspace/src
cd ~/your_workspace/src
git clone <本仓库地址> .

# 编译
cd ~/your_workspace
colcon build
source install/setup.bash
```

### 一键启动（WebSocket + RViz）
```bash
ros2 launch qnbot_teleoperator demo_full.launch.py
```

### 单独启动 RViz 可视化
```bash
# 使用 GUI 滑条控制关节
ros2 launch qnbot_teleoperator exoskeleton_display.launch.py source:=gui

# 订阅外骨骼数据
ros2 launch qnbot_teleoperator exoskeleton_display.launch.py source:=exo_command
```

## 网络隔离

如果局域网内有多台电脑运行 ROS2，建议设置不同的 Domain ID 避免干扰：
```bash
export ROS_DOMAIN_ID=42
```

## 话题列表

| 话题 | 类型 | 说明 |
|------|------|------|
| `/exo/joint_command` | sensor_msgs/JointState | 外骨骼关节命令（16关节） |
| `/exo/gamepad_keys` | sensor_msgs/Joy | 手柄摇杆和按钮数据 |
| `/exo/full_state` | interface_protocol/ExoFullState | 外骨骼完整状态 |

## 目录结构
```
your_workspace/
├── src/                           # 本仓库内容 clone 到此
│   ├── interface_protocol/        # 消息定义
│   ├── qnbot_teleoperator/        # 遥操作核心
│   │   ├── config/                # 配置文件
│   │   ├── launch/                # 启动文件
│   │   ├── resource/              # URDF、mesh 资源
│   │   └── scripts/               # 工具脚本
│   ├── qnbot_replay/              # 数据回放
│   └── README.md
├── build/                         # 编译产物（自动生成）
├── install/                       # 安装目录（自动生成）
└── log/                           # 日志（自动生成）
```
