chore: add ros2 udp_teleop package and tools

2026-05-27 02:17:35 +08:00
parent 13fdba5fff
commit 6f6577d983
13 changed files with 743 additions and 3 deletions
--- a/ros2/src/udp_teleop/README.md
+++ b/ros2/src/udp_teleop/README.md
@@ -0,0 +1,165 @@
+# 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` 在终端直接运行。