From a281fd115e80ad01934878970877c332c90843a3 Mon Sep 17 00:00:00 2001 From: dev01 Date: Sun, 31 May 2026 22:25:00 +0800 Subject: [PATCH] docs: add usage guide and README with architecture overview --- README.md | 96 ++++++++++++++++++++++++ docs/使用指南.md | 190 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 286 insertions(+) create mode 100644 README.md create mode 100644 docs/使用指南.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..03d5403 --- /dev/null +++ b/README.md @@ -0,0 +1,96 @@ +# Vision Pipeline + +基于 ROS2 Humble 的机器视觉识别与云台追踪系统。 + +## 整体架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 硬件层 │ +│ ┌──────────┐ ┌──────────┐ ┌────────────────────┐ │ +│ │ 工业相机 │ │ Jeston │ │ 云台（UART） │ │ +│ │ (Hikrobot)│ │ (aarch64)│ │ Yaw + Pitch + 激光 │ │ +│ └────┬─────┘ └────┬─────┘ └─────────┬──────────┘ │ +│ │ │ │ │ +├───────┼───────────────┼────────────────────┼────────────────┤ +│ ▼ ▼ ▼ │ +│ ┌─────────┐ ┌──────────┐ ┌───────────────────┐ │ +│ │driver_pkg│ │algorithm_pkg│ │gimbal_control_pkg │ │ +│ │ │ │ │ │ │ │ +│ │ 相机驱动 │──▶│ 视觉处理 │──▶│ 云台串口通信 │ │ +│ │ MvCamera │ │ Otsu+轮廓 │ │ 0xA5/A6/A7/A8 │ │ +│ └────┬─────┘ └─────┬─────┘ └───────────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌─────────────────────────────────────┐ │ +│ │ application_pkg │ │ +│ │ ┌───────────────────────────────┐ │ │ +│ │ │ web_node (:8080) │ │ │ +│ │ │ - MJPEG 预览页 │ │ │ +│ │ │ - POST /api/mode/switch │──┼──▶ /gimbal/mode │ +│ │ └───────────────────────────────┘ │ │ +│ └─────────────────────────────────────┘ │ +│ │ +│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ rosbridge │ │web_video │ │ Nginx :80 │ │ +│ │ ws://:9090 │ │server :8081 │ │ / → 前端静态文件 │ │ +│ └──────┬──────┘ └──────┬───────┘ │ /stream → :8081 │ │ +│ │ │ │ /api → :8080 │ │ +├─────────┼────────────────┼──────────└──────────────────┘────┤ +│ ▼ ▼ │ +│ ┌─────────────────────────────────────┐ │ +│ │ 浏览器 (Vue3 前端) │ │ +│ │ - 视频预览 / 键盘遥控 / PID 调参 │ │ +│ └─────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## 数据流 + +| 阶段 | 话题 | 方向 | 消息类型 | 说明 | +|------|------|------|----------|------| +| 图像采集 | `/camera/image_raw` | camera_node → vision_node | `sensor_msgs/Image` | 原始相机图像 | +| 视觉结果 | `/vision/result_image` | vision_node → web_node | `sensor_msgs/Image` | 带轮廓标注的结果图 | +| 二值调试 | `/vision/binary_image` | vision_node → web_node | `sensor_msgs/Image` | 二值化调试图像 | +| 目标追踪 | `/vision/target` | vision_node → gimbal_node | `geometry_msgs/Point` | 归一化目标偏移 (x,y) | +| 模式切换 | `/gimbal/mode` | web_node → gimbal_node | `std_msgs/String` | auto/manual/debug | +| 手动控制 | `/cmd_gimbal` | 前端 → gimbal_node | `geometry_msgs/Twist` | yaw/pitch 角度 | +| PID 参数 | `/pid_config` | 前端 → gimbal_node | `std_msgs/String` | PID 参数 JSON | + +## 目录结构 + +``` +Vision/ +├── README.md +├── vision_example.py # 独立参考脚本（非 ROS2） +├── config/ +│ └── nginx-aimbot.conf # Nginx 配置 +├── docs/ +│ ├── 云台通信协议指南.md # 云台 UART 串口协议 +│ ├── 与前端对接文档.md # 前后端对接规范 +│ └── 使用指南.md # 使用说明 +└── workspace/ # ROS2 workspace + └── src/ + ├── driver_pkg/ # 工业相机驱动 + ├── algorithm_pkg/ # 视觉处理算法 + ├── application_pkg/ # HTTP 服务 + ├── gimbal_control_pkg/ # 云台串口通信 + └── bringup_pkg/ # 启动文件 +``` + +## 快速开始 + +```bash +# 构建 +cd workspace +colcon build --symlink-install +source install/setup.bash + +# 启动全流程 +ros2 launch bringup_pkg vision_pipeline.launch.py + +# 浏览器预览 +# http://<设备IP>:8080 +``` + +详细使用方法见 [使用指南](docs/使用指南.md)。 diff --git a/docs/使用指南.md b/docs/使用指南.md new file mode 100644 index 0000000..f12c6ec --- /dev/null +++ b/docs/使用指南.md @@ -0,0 +1,190 @@ +# 使用指南 + +## 开发环境 + +- ROS2 Humble + colcon +- Python 3.8+ +- OpenCV、NumPy +- Hikrobot MvCamera SDK（`/opt/MVS/`） +- pyserial + +## 1. 构建 + +```bash +cd workspace +colcon build --symlink-install +source install/setup.bash +``` + +`--symlink-install` 使 Python 修改无需重新构建即可生效。 + +## 2. 启动全流程 + +```bash +ros2 launch bringup_pkg vision_pipeline.launch.py +``` + +启动后包含四个节点： + +| 节点 | 包 | 功能 | +|------|-----|------| +| camera_node | driver_pkg | 工业相机图像采集 | +| vision_node | algorithm_pkg | 图像处理 + 目标检测 | +| web_node | application_pkg | HTTP 服务、预览 + API | +| gimbal_node | gimbal_control_pkg | 云台串口通信 | + +## 3. 分别启动 + +```bash +# 相机驱动 +ros2 run driver_pkg camera_node + +# 视觉处理 +ros2 run algorithm_pkg vision_node + +# Web 服务 +ros2 run application_pkg web_node + +# 云台通信（默认串口 /dev/ttyTHS1） +ros2 run gimbal_control_pkg gimbal_node +``` + +gimbal_node 支持串口参数覆盖： + +```bash +ros2 run gimbal_control_pkg gimbal_node --ros-args -p serial_port:=/dev/ttyUSB0 +``` + +## 4. 接入前端（可选） + +前端需要 rosbridge 和 web_video_server： + +```bash +# 安装依赖 +sudo apt install ros-${ROS_DISTRO}-rosbridge-server +sudo apt install ros-${ROS_DISTRO}-web-video-server + +# 启动 rosbridge WebSocket（默认 ws://0.0.0.0:9090） +ros2 run rosbridge_server rosbridge_websocket & + +# 启动 MJPEG 视频推流（默认 http://0.0.0.0:8081） +ros2 run web_video_server web_video_server & +``` + +### Nginx 部署 + +```bash +sudo cp config/nginx-aimbot.conf /etc/nginx/sites-available/aimbot +sudo ln -s /etc/nginx/sites-available/aimbot /etc/nginx/sites-enabled/ +sudo nginx -t && sudo systemctl reload nginx +``` + +Nginx 负责三件事： +- 托管前端静态文件（`/var/www/aimbot/`） +- 反代 MJPEG 视频流（`/stream` → `web_video_server :8081`） +- 反代模式切换 API（`/api/` → `web_node :8080`） + +### 启动顺序 + +1. 启动 ROS2 节点（launch 或分别启动） +2. 启动 rosbridge + web_video_server +3. 启动/重载 Nginx + +## 5. 模式切换 + +通过 HTTP API 切换云台工作模式： + +```bash +# 自动追踪模式 +curl -X POST http://localhost:8080/api/mode/switch \ + -H "Content-Type: application/json" \ + -d '{"mode": "auto"}' + +# 手动控制模式 +curl -X POST http://localhost:8080/api/mode/switch \ + -H "Content-Type: application/json" \ + -d '{"mode": "manual"}' + +# 调试模式 +curl -X POST http://localhost:8080/api/mode/switch \ + -H "Content-Type: application/json" \ + -d '{"mode": "debug"}' + +# 激光开关 +curl -X POST http://localhost:8080/api/mode/switch \ + -H "Content-Type: application/json" \ + -d '{"mode": "laser_on"}' +``` + +也可直接通过 ROS2 话题发送： + +```bash +ros2 topic pub /gimbal/mode std_msgs/String "data: 'auto'" +``` + +## 6. 手动控制云台 + +```bash +# angular.y = pitch 角速度, angular.z = yaw 角速度 +ros2 topic pub /cmd_gimbal geometry_msgs/Twist \ + "{angular: {y: 0.0, z: 0.0}}" +``` + +## 7. PID 调参（调试模式） + +先切换到 debug 模式，然后通过 `/pid_config` 话题发送参数： + +```bash +ros2 topic pub /pid_config std_msgs/String \ + '{"vision_yaw": {"kp": 1.0, "ki": 0.0, "kd": 0.0}, + "vision_pitch": {"kp": 1.0, "ki": 0.0, "kd": 0.0}, + "motor_yaw": {"kp": 1.0, "ki": 0.0, "kd": 0.0}, + "motor_pitch": {"kp": 1.0, "ki": 0.0, "kd": 0.0}}' +``` + +参数立即生效，调试完毕后切回 auto 或 manual 模式。 + +## 8. 查看视觉结果 + +浏览器打开 `http://<设备IP>:8080`，可看到： +- 原始图像 + 轮廓标注（result） +- Otsu 二值化 + 闭运算结果（binary） + +## 9. 查看话题 + +```bash +# 列出所有活跃话题 +ros2 topic list + +# 查看话题频率 +ros2 topic hz /camera/image_raw +ros2 topic hz /vision/target + +# 查看话题内容 +ros2 topic echo /vision/target +``` + +## 10. 测试 + +```bash +cd workspace + +# 测试全部包 +colcon test + +# 测试单个包 +colcon test --packages-select gimbal_control_pkg + +# 查看测试结果 +colcon test-result --all +``` + +## 11. 故障排查 + +| 现象 | 检查项 | +|------|--------| +| 相机打不开 | SDK 是否安装、相机是否连接、`/opt/MVS/` 路径是否正确 | +| 视觉画面无结果 | `/camera/image_raw` 是否有数据 | +| 云台无反应 | 串口 `/dev/ttyTHS1` 是否存在、波特率 115200 是否匹配 | +| 模式切换报错 | web_node 是否在 :8080 端口运行 | +| MJPEG 不出画面 | web_video_server 是否运行、proxy_buffering 是否设为 off |