docs: add usage guide and README with architecture overview

2026-05-31 22:25:00 +08:00
parent 19d5e432a4
commit a281fd115e
2 changed files with 286 additions and 0 deletions
@@ -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 |