docs: 整理和精简文档结构

- 删除冗余文档（6个重复的说明文档） - 更新 README.md：简洁清晰的项目总览 - 更新 ros2/README.md：完整的 ROS 2 使用指南 - 保留核心技术文档：docs/arm.md（运动学推导）文档现在更加简洁，避免重复内容
2026-06-16 19:01:42 +08:00
parent 83b32542ef
commit f00537ebb9
8 changed files with 374 additions and 1724 deletions
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@

 > 本仓库为 **[中国机器人及人工智能大赛](https://www.caairobot.com)**（CRAIC）**机器人任务挑战赛（小型桌面级）** 参赛代码。

-ESP32-S3 双核摄像头 + ROS 2 键盘遥控 + UDP 实时通讯的一体化机器人控制系统。
+ESP32-S3 双核摄像头 + ROS 2 机械臂控制 + 视觉抓取的一体化机器人系统。

-## 赛事
+## 赛事信息

 **中国机器人及人工智能大赛**（**C**hina **R**obot and **A**rtificial **I**ntelligence **C**ompetition，简称 **CRAIC**）是由 [中国人工智能学会](https://www.caai.cn)（CAAI）主办的全国性学科竞赛，始于 1999 年，已列入**全国普通高等学校学科竞赛排行榜**及**教育部 A 类竞赛名单**。

@@ -23,68 +23,59 @@ ESP32-S3 双核摄像头 + ROS 2 键盘遥控 + UDP 实时通讯的一体化机

 ```
 craic/
-├── jxbeye/                    # ESP32-S3 摄像头固件 (PlatformIO)
-│   ├── src/main.cpp           # 双核并行推流 + AsyncUDP + ESP-NOW
-│   ├── platformio.ini         # 构建配置 (ESP32-S3-WROOM-1-N16R8)
-│   ├── boards/                # 自定义板级定义
-│   ├── lib/FTServo/           # 飞特舵机控制库
-│   └── include/ / test/
-├── ros2/                      # ROS 2 Humble 键盘遥控
-│   └── src/udp_teleop/        # 底盘 + 6轴机械臂 UDP 遥控节点
-├── tools/                     # 调试工具
-│   └── udp_server.py          # UDP 回显测试服务器
-└── .gitignore
+├── jxbeye/                    # ESP32-S3 固件 (PlatformIO)
+│   ├── src/main.cpp           # 双核摄像头推流 + UDP 控制
+│   └── platformio.ini         # ESP32-S3-WROOM-1-N16R8 配置
+├── ros2/                      # ROS 2 控制系统
+│   ├── src/arm_control_msgs/  # 消息和服务定义
+│   └── src/udp_teleop/        # 机械臂控制和视觉抓取节点
+├── tools/                     # 独立工具脚本
+│   ├── udp_control.py         # 命令行机械臂控制（带逆运动学）
+│   ├── camera_to_base.py      # 相机坐标到基坐标变换
+│   └── camera_capture.py      # MJPEG 流采集
+└── docs/                      # 技术文档
+    └── arm.md                 # 机械臂运动学推导
 ```

 ## 硬件

 | 组件 | 型号 |
 |------|------|
-| 主控 | ESP32-S3-WROOM-1-N16R8 (16MB Flash, 8MB PSRAM Octal) |
+| 主控 | ESP32-S3-WROOM-1-N16R8 (16MB Flash, 8MB PSRAM) |
 | 摄像头 | OV2640 (XGA 1024×768, JPEG) |
-| 舵机 | 飞特 SCS/STS 系列串行舵机 |
+| 机械臂 | 6-DOF，飞特 SCS/STS 串行舵机 |

-## 功能
+## 核心功能

 ### 1. ESP32-S3 固件 (`jxbeye/`)

- **双核并行架构**：Core 0 负责摄像头采集，Core 1 负责 WiFi 推流
- **MJPEG 实时推流**：Web 浏览器直接访问 `http://<IP>` 查看实时画面
- **AsyncUDP 非阻塞通讯**：UDP 指令由中断回调处理，不干扰推流
- **ESP-NOW**：低延迟点对点通信
- **在线 WiFi 配置**：通过 Web 页面或串口修改 SSID/密码，自动保存到 NVS
+- **双核架构**：Core 0 采集，Core 1 推流
+- **MJPEG 推流**：`http://<IP>` 实时查看
+- **UDP 控制**：端口 8888，非阻塞异步处理
+- **WiFi 配置**：串口发送 `WIFI:SSID:PASSWORD` 配置

-### 2. ROS 2 键盘遥控 (`ros2/src/udp_teleop/`)
+### 2. ROS 2 机械臂控制 (`ros2/`)

- **底盘遥控**：W/S 前进后退、A/D 左右平移、Q/E 旋转（差速驱动）
- **机械臂遥控**：6 轴关节角度独立控制，高度升降
- **多平台键盘后端**：
-  - `stdin` — Linux/macOS 终端原生输入，零依赖
-  - `pynput` — 跨平台按键监听
-  - `win_poll` — Windows Win32 API 轮询
- **可配置参数**：速度、步长、目标 IP/端口均通过 YAML 配置
+**arm_control 节点**：
+- 关节空间和笛卡尔空间运动控制
+- 完整逆运动学和正运动学
+- 服务接口：`move_joints`, `move_pose`, `get_pose`, `set_gripper`
+- 状态发布（10Hz）

-### 3. UDP 通讯协议
+**vision_grasp 节点**：
+- 相机坐标到基坐标系自动转换
+- 自动抓取：释放 → 移动 → 抓取 → 回收
+- 自动释放：移动 → 释放 → 回收

-所有指令通过 UDP 端口 `8888` 发送，格式：
+### 3. 工具脚本 (`tools/`)

-```
-# 底盘控制
-XYW:<X速度>:<Y速度>:<W角速度>:XZHY\n
-
-# 机械臂控制
-JXB:<高度>:<J2>:<J3>:<J4>:<J5>:<J6>:0:0:EZHY\n
-
-# 激光控制
-LASERON / LASEROFF
-
-# 串口透传
-<any payload ending with ZHY or \n>
-```
+- `udp_control.py` - 命令行机械臂控制（支持逆运动学）
+- `camera_to_base.py` - 坐标变换工具
+- `camera_capture.py` - 相机帧采集（支持自动扫描）

 ## 快速开始

-### 编译 & 烧录 ESP32 固件
+### ESP32 固件

 ```bash
 cd jxbeye
@@ -92,55 +83,134 @@ pio run -t upload
 pio device monitor
 ```

-首次启动后 ESP32 创建热点 `ESP32-S3-Camera`（密码 `12345678`），浏览器访问 `http://192.168.4.1`。
+首次启动创建热点 `ESP32-S3-Camera`（密码 `12345678`），访问 `http://192.168.4.1`。

-### 运行 ROS 2 键盘遥控
+### ROS 2 控制系统

 ```bash
-# 创建环境（首次）
+# 环境准备（首次）
 conda create -n ros2_humble -c robostack-staging -c conda-forge ros-humble-desktop
-conda install -n ros2_humble -c robostack-staging -c conda-forge colcon-common-extensions
-conda run -n ros2_humble pip install pynput
-
-# 构建 & 运行
 conda activate ros2_humble
+
+# 编译
 cd ros2
-colcon build --symlink-install --packages-select udp_teleop
+export PYTHON_EXECUTABLE=$CONDA_PREFIX/bin/python
+export PYTHON_INCLUDE_DIR=$CONDA_PREFIX/include/python3.12
+export PYTHON_LIBRARY=$CONDA_PREFIX/lib/libpython3.12.so
+
+colcon build --packages-select arm_control_msgs \
+  --cmake-args \
+    -DPython_EXECUTABLE=$PYTHON_EXECUTABLE \
+    -DPython_INCLUDE_DIR=$PYTHON_INCLUDE_DIR \
+    -DPython_LIBRARY=$PYTHON_LIBRARY
+
+colcon build --packages-select udp_teleop
 source install/setup.bash

-# 启动键盘遥控（默认目标 192.168.233.67:8888）
-ros2 run udp_teleop keyboard_control \
-    --ros-args --params-file src/udp_teleop/config/params.yaml
+# 运行机械臂控制
+ros2 run udp_teleop arm_control \
+    --ros-args --params-file src/udp_teleop/config/arm_control.yaml
+
+# 运行视觉抓取（新终端）
+ros2 run udp_teleop vision_grasp \
+    --ros-args --params-file src/udp_teleop/config/vision_grasp.yaml
 ```

-### 测试 UDP 通讯
+### 命令行工具

 ```bash
-# 启动回显服务器
-python tools/udp_server.py
+# 机械臂控制（关节空间）
+python tools/udp_control.py joints \
+    --height -100 --j2 10 --j3 20 --j4 30 --duration 2.0

-# 发送测试指令
-echo 'XYW:100:0:0:XZHY' | nc -u 127.0.0.1 8888
+# 机械臂控制（笛卡尔空间）
+python tools/udp_control.py pose \
+    --x 200 --y 100 --z -100 --phi 45 --duration 2.0
+
+# 相机采集
+python tools/camera_capture.py --ip 192.168.4.1
+python tools/camera_capture.py --scan  # 自动扫描
 ```

-### 串口配置 WiFi
+## UDP 协议

-在 ESP32 串口监视器中发送：
+所有指令通过 UDP 端口 `8888` 发送：

-```
-WIFI:热点名称:密码
+```bash
+# 底盘控制（麦克纳姆轮）
+XYW:<X>:<Y>:<W>:XZHY\n
+
+# 机械臂控制（6 轴）
+JXB:<height>:<J2>:<J3>:<J4>:<J5>:<J6>:0:0:EZHY\n
+
+# 激光控制
+LASERON / LASEROFF
 ```

-设备自动保存配置并重启。
+## 使用示例
+
+### ROS 服务调用
+
+```bash
+# 查询位姿
+ros2 service call /arm_control/get_pose arm_control_msgs/srv/GetPose
+
+# 移动到目标位置
+ros2 service call /arm_control/move_pose arm_control_msgs/srv/MovePose \
+    "{x: 200.0, y: 100.0, z: -100.0, phi: 45.0, duration: 2.0}"
+
+# 视觉抓取（发布相机坐标）
+ros2 topic pub --once /vision_grasp/grasp_target geometry_msgs/Point \
+    "{x: 10.0, y: 5.0, z: 250.0}"
+```
+
+### Python 集成
+
+```python
+import rclpy
+from geometry_msgs.msg import Point
+
+class VisionDetector:
+    def __init__(self):
+        self.grasp_pub = self.create_publisher(Point, 'vision_grasp/grasp_target', 10)
+    
+    def on_detection(self, camera_x, camera_y, camera_z):
+        msg = Point()
+        msg.x = camera_x
+        msg.y = camera_y
+        msg.z = camera_z
+        self.grasp_pub.publish(msg)
+```
+
+## 文档
+
+- **ROS 2 系统**：[ros2/README.md](ros2/README.md) - 完整的 ROS 节点文档
+- **运动学推导**：[docs/arm.md](docs/arm.md) - 机械臂逆运动学数学推导
+- **视觉标定**：[docs/vision_calibration_horizontal.md](docs/vision_calibration_horizontal.md) - 相机标定指南
+
+## 坐标系说明
+
+**机械臂基坐标系**（Z 轴朝上）：
+- 原点：J1 线性滑轨底部
+- X 轴：基座正前方
+- Y 轴：基座左侧
+- Z 轴：竖直向上（高度）
+
+**相机坐标系**（水平安装）：
+- X 轴：右侧
+- Y 轴：向下
+- Z 轴：正前方（光轴）
+
+变换由 `camera_to_base.py` 和 `vision_grasp` 节点自动处理。

 ## 依赖

 | 环境 | 依赖 |
 |------|------|
 | ESP32 | PlatformIO, Arduino framework, esp32-camera |
-| ROS 2 | ROS 2 Humble (Conda robostack), pynput |
-| 测试 | Python 3, Unix netcat |
+| ROS 2 | ROS 2 Humble (robostack), Python 3.12 |
+| 工具 | NumPy, OpenCV (可选) |

 ## 许可

-待定。
+MIT License