# udp_teleop — ROS 2 底盘 + 机械臂键盘 UDP 遥控

通过键盘实时控制底盘（差速驱动）和机械臂（6 电机），指令通过 **单一 UDP socket** 发送到设备端。

## 项目结构

```
ros2/
├── build/                     # colcon 构建产物（自动生成）
├── install/                   # colcon 安装产物（自动生成）
├── log/                       # 构建日志（自动生成）
└── src/
    └── udp_teleop/            # ROS 2 包
        ├── config/
        │   └── params.yaml        # 可配置参数
        ├── launch/                # launch 文件（预留）
        ├── udp_teleop/
        │   ├── __init__.py
        │   └── keyboard_control.py  # 键盘遥控节点
        ├── resource/
        ├── test/
        ├── package.xml
        ├── setup.cfg
        └── setup.py
```

## 环境搭建

### 1. 安装 Conda

使用 Miniconda 或 Anaconda。推荐 Miniconda：

```bash
# 下载并安装 Miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
```

### 2. 创建 ROS 2 Humble 环境

使用 robostack 频道安装 ROS 2 Humble Desktop 完整版：

```bash
conda create -n ros2_humble -c robostack-staging -c conda-forge ros-humble-desktop
```

### 3. 安装构建工具

```bash
conda activate ros2_humble
conda install -c robostack-staging -c conda-forge \
    colcon-common-extensions \
    ros-humble-ament-cmake \
    python3-pip
```

### 4. 安装 Python 依赖

```bash
pip install pynput
```

### 5. 激活环境

每次使用前：

```bash
conda activate ros2_humble
source /path/to/ros2/install/setup.bash   # 首次构建后执行
```

## 构建

```bash
cd ros2
colcon build --symlink-install --packages-select udp_teleop
source install/setup.bash
```

> `--symlink-install`：修改 Python 源文件后无需重新构建，直接生效。

## 运行

### 使用参数文件（推荐）

```bash
ros2 run udp_teleop keyboard_control \
    --ros-args --params-file src/udp_teleop/config/params.yaml
```

### 命令行覆盖参数

```bash
ros2 run udp_teleop keyboard_control \
    --ros-args -p udp_ip:=192.168.1.100 -p udp_port:=9999
```

## 按键映射

### 底盘控制

| 按键 | 功能 |
|------|------|
| `W` / `S` | 前进 / 后退 |
| `A` / `D` | 左移 / 右移 |
| `Q` / `E` | 左转 / 右转 |

### 机械臂控制

| 按键 | 功能 |
|------|------|
| `↑` / `↓` | 升降高度（↑ 升高，↓ 降低） |
| `2` ~ `6` | 选择关节 J2 ~ J6 |
| `←` / `→` | 减小 / 增大当前关节角度 |

> 底盘和机械臂可以**同时操控**。机械臂指令仅在按下机械臂相关按键后发送。

### 其他

| 按键 | 功能 |
|------|------|
| `Ctrl+C` | 退出并发送底盘停止指令 |

## UDP 协议

### 底盘指令

```
XYW:<X速度>:<Y速度>:<W角速度>:XZHY\n
```

### 机械臂指令

```
JXB:<高度>:<J2>:<J3>:<J4>:<J5>:<J6>:0:0:EZHY\n
```

- 6 个电机：电机 1 控制高度，电机 2~6 对应关节 J2~J6
- 末尾补零至 8 个值

## 参数配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `udp_ip` | `127.0.0.1` | UDP 目标 IP 地址 |
| `udp_port` | `8888` | UDP 目标端口 |
| `chassis_linear_speed` | `100` | 底盘线速度 |
| `chassis_angular_speed` | `45` | 底盘角速度 |
| `arm_height_step` | `5` | 高度每步变化量 |
| `arm_joint_step` | `5` | 关节角度每步变化量 |
| `update_rate` | `0.05` | 控制循环周期（秒） |
| `stdin_hold_time` | `0.04` | 按键持续时间（秒），修复箭头键时序问题 |
| `debug_keys` | `false` | 是否在状态行显示当前按键 |
| `keyboard_backend` | `auto` | 键盘后端：`auto` / `stdin` / `pynput` / `win_poll` |

## 键盘后端

| 后端 | 说明 |
|------|------|
| `auto` | 自动选择：Linux/macOS 用 `stdin`，Windows 用 `win_poll` |
| `stdin` | 基于终端原始输入，无需额外依赖，**需要交互终端** |
| `pynput` | 基于 pynput 库，跨平台，需要 `pip install pynput` |
| `win_poll` | Windows 专用，通过 Win32 API 轮询按键状态 |

> `ros2 launch` 启动的子进程**没有交互终端**，使用 `stdin` 后端会报错。必须通过 `ros2 run` 在终端直接运行。