Vision/docs/使用指南.md

使用指南

开发环境

• ROS2 Humble + colcon
• Python 3.8+
• OpenCV、NumPy
• Hikrobot MvCamera SDK（/opt/MVS/）
• pyserial

1. 构建

cd workspace
colcon build --symlink-install
source install/setup.bash

--symlink-install 使 Python 修改无需重新构建即可生效。

2. 启动全流程

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. 分别启动

# 相机驱动
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 支持串口参数覆盖：

ros2 run gimbal_control_pkg gimbal_node --ros-args -p serial_port:=/dev/ttyUSB0

4. 接入前端（可选）

前端需要 rosbridge 和 web_video_server：

# 安装依赖
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 部署

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 切换云台工作模式：

# 自动追踪模式
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"}'

也可直接通过 ROS2 话题发送：

ros2 topic pub /gimbal/mode std_msgs/String "data: 'auto'"

6. 激光控制

# 开激光
curl -X POST http://localhost:8080/api/laser \
  -H "Content-Type: application/json" \
  -d '{"action": "on"}'

# 关激光
curl -X POST http://localhost:8080/api/laser \
  -H "Content-Type: application/json" \
  -d '{"action": "off"}'

也可直接通过 ROS2 话题发送：

ros2 topic pub /gimbal/mode std_msgs/String "data: 'laser_on'"
ros2 topic pub /gimbal/mode std_msgs/String "data: 'laser_off'"

7. 手动控制云台

# angular.y = pitch 角速度, angular.z = yaw 角速度
ros2 topic pub /cmd_gimbal geometry_msgs/Twist \
  "{angular: {y: 0.0, z: 0.0}}"

8. PID 调参（调试模式）

先切换到 debug 模式，然后通过 /pid_config 话题发送参数：

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 模式。

9. 查看话题

# 列出所有活跃话题
ros2 topic list

# 查看话题频率
ros2 topic hz /camera/image_raw
ros2 topic hz /vision/target

# 查看话题内容
ros2 topic echo /vision/target

10. 测试

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