# 使用指南

## 开发环境

- 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 | 云台串口通信 |
| chassis_node | chassis_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

# 底盘通信（默认串口 /dev/ttyCH341USB0）
ros2 run chassis_control_pkg chassis_node
```

gimbal_node 支持串口参数覆盖：

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

chassis_node 同样支持串口参数覆盖：

```bash
ros2 run chassis_control_pkg chassis_node --ros-args -p serial_port:=/dev/ttyUSB1
```

## 4. 接入前端（可选）

前端依赖已集成在 launch 文件中，一键启动即可。首次使用需安装依赖：

```bash
sudo apt install ros-${ROS_DISTRO}-rosbridge-server
sudo apt install ros-${ROS_DISTRO}-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. 启动 launch 文件（已包含所有 ROS2 节点 + rosbridge + web_video_server）
2. 启动/重载 Nginx

## 5. 模式切换

通过 HTTP API 切换云台工作模式：

```bash
# 自动追踪模式
curl -X POST http://localhost:8080/api/gimbal/mode/switch \
  -H "Content-Type: application/json" \
  -d '{"mode": "auto"}'

# 手动控制模式
curl -X POST http://localhost:8080/api/gimbal/mode/switch \
  -H "Content-Type: application/json" \
  -d '{"mode": "manual"}'

# 调试模式
curl -X POST http://localhost:8080/api/gimbal/mode/switch \
  -H "Content-Type: application/json" \
  -d '{"mode": "debug"}'
```

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

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

### 底盘模式切换

```bash
# 自动模式
curl -X POST http://localhost:8080/api/chassis/mode/switch \
  -H "Content-Type: application/json" \
  -d '{"mode": "auto"}'

# 手动模式
curl -X POST http://localhost:8080/api/chassis/mode/switch \
  -H "Content-Type: application/json" \
  -d '{"mode": "manual"}'

# 调试模式
curl -X POST http://localhost:8080/api/chassis/mode/switch \
  -H "Content-Type: application/json" \
  -d '{"mode": "debug"}'
```

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

```bash
ros2 topic pub /chassis/mode std_msgs/String "data: 'auto'"
```

## 6. 激光控制

```bash
# 开激光
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 话题发送：

```bash
ros2 topic pub /laser/command std_msgs/String "data: 'on'"
ros2 topic pub /laser/command std_msgs/String "data: 'off'"
```

## 7. 手动控制云台

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

## 8. PID 调参（调试模式）

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

```bash
ros2 topic pub /web/gimbal_pid_config std_msgs/String \
  '{"visual_yaw": {"kp": 1.0, "ki": 0.0, "kd": 0.0},
    "visual_pitch": {"kp": 1.0, "ki": 0.0, "kd": 0.0},
    "angle_yaw": {"kp": 1.0, "ki": 0.0, "kd": 0.0},
    "angle_pitch": {"kp": 1.0, "ki": 0.0, "kd": 0.0}}'
```

参数立即生效，调试完毕后切回 auto 或 manual 模式。

### 底盘 PID 调参

先切换底盘到 debug 模式，然后通过 `/web/chassis_pid_config` 话题发送参数：

```bash
ros2 topic pub /web/chassis_pid_config std_msgs/String \
  '{"speed": {"kp": 1.0, "ki": 0.0, "kd": 0.0},
    "angle": {"kp": 1.0, "ki": 0.0, "kd": 0.0},
    "position": {"kp": 1.0, "ki": 0.0, "kd": 0.0}}'
```

## 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` 是否存在、波特率 921600 是否匹配 |
| 底盘无反应 | 串口 `/dev/ttyCH341USB0` 是否存在、波特率 115200 是否匹配 |
| 模式切换报错 | web_node 是否在 :8080 端口运行 |
| MJPEG 不出画面 | web_video_server 是否运行、proxy_buffering 是否设为 off |