# DroneScrewServer 部署指南

## 概述

DroneScrewServer 是基于海康威视 MVS USB 相机的螺杆检测服务端程序，运行在 ARM/Linux 平台。

---

## 目录结构

```
DroneScrewServer/
├── DroneScrewServer          # 可执行文件
├── config/
│   └── config.xml            # 配置文件
├── setup_mvs_env.sh          # 环境配置脚本
├── run_server.sh             # 启动脚本（推荐使用）
├── USB_CAMERA_TROUBLESHOOTING.md  # 故障排查指南
└── README.md                 # 本文件
```

---

## 快速开始

### 方法 1：使用启动脚本（推荐）

```bash
# 赋予执行权限
chmod +x run_server.sh setup_mvs_env.sh

# 启动服务（自动配置环境）
sudo ./run_server.sh
```

### 方法 2：手动启动

```bash
# 1. 配置环境变量
source ./setup_mvs_env.sh

# 2. 配置 USB 内存（需要 root）
sudo sh -c 'echo 2000 > /sys/module/usbcore/parameters/usbfs_memory_mb'

# 3. 运行程序
sudo ./DroneScrewServer
```

---

## 系统要求

### 硬件要求
- **平台**：ARM aarch64（如 RK3588、Jetson 等）
- **USB**：USB 3.0 端口（推荐）
- **内存**：至少 2GB 可用内存
- **相机**：海康威视 MVS USB 工业相机

### 软件要求
- **操作系统**：Linux ARM64（Ubuntu 20.04+ / Debian 11+）
- **依赖库**：
  - Qt 5.15+
  - ZeroMQ 4.3+
  - Protobuf 3.20+
  - MVS SDK 3.0.1（已包含在项目中）

---

## 依赖的 SDK 文件

程序运行时需要以下 SDK 文件（已包含在项目中）：

```
SDK/Device/MVS/MVS_STD_V3.0.1_251113/MVS-3.0.1_aarch64_20251113/
├── lib/aarch64/
│   ├── libMvCameraControl.so          # 主库
│   ├── libGCBase_gcc494_v3_0.so
│   ├── libGenCP_gcc494_v3_0.so
│   ├── libCLProtocol_gcc494_v3_0.so
│   ├── libFormatConversion.so
│   └── ThirdParty/
│       ├── libavutil.so.60.8.100      # FFmpeg 依赖
│       └── libswscale.so.9.1.100
└── include/
    ├── MvCameraControl.h
    └── ...
```

**重要**：这些文件必须存在，否则程序无法启动。

---

## 配置文件

### config/config.xml

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DroneScrewServerConfig>
    <!-- 相机配置 -->
    <Camera serialNumber="" exposureTime="10000" gain="5.0"/>
    
    <!-- ZeroMQ 端口配置 -->
    <Zmq controlPort="5555" resultPort="5556" rawImagePort="5557"/>
    
    <!-- RTSP 推流配置 -->
    <Rtsp port="8554" path="/live/dronescrew" bitrateKbps="4096" fps="30"/>
    
    <!-- 算法参数 -->
    <Algorithm scoreThreshold="0.5" nmsThreshold="0.45" 
               inputWidth="640" inputHeight="640"
               modelPath="./model/dronescrew.onnx" modelType="0"/>
</DroneScrewServerConfig>
```

**参数说明**：
- `serialNumber`：相机序列号（留空则使用第一个检测到的相机）
- `exposureTime`：曝光时间（微秒）
- `gain`：增益值
- `controlPort`：ZMQ 控制端口
- `resultPort`：ZMQ 结果发布端口
- `rawImagePort`：原始图像发布端口（0 表示禁用）

---

## 环境变量说明

程序运行需要以下环境变量（`setup_mvs_env.sh` 会自动配置）：

```bash
# MVS SDK 根路径
export MVCAM_SDK_PATH=/path/to/MVS-3.0.1_aarch64_20251113

# 库搜索路径
export LD_LIBRARY_PATH=$MVCAM_SDK_PATH/lib/aarch64:$MVCAM_SDK_PATH/lib/aarch64/ThirdParty:$LD_LIBRARY_PATH
```

---

## 常见问题

### 1. 错误：找不到 libMvCameraControl.so

**原因**：环境变量未配置或 SDK 文件缺失

**解决**：
```bash
# 检查 SDK 文件是否存在
ls SDK/Device/MVS/MVS_STD_V3.0.1_251113/MVS-3.0.1_aarch64_20251113/lib/aarch64/libMvCameraControl.so

# 使用启动脚本（会自动配置）
./run_server.sh
```

### 2. 错误：MV_CC_StartGrabbing fail: 80000006

**原因**：USB 资源申请失败

**解决**：
1. 确保使用 `sudo` 运行
2. 配置 USB 内存：`sudo sh -c 'echo 2000 > /sys/module/usbcore/parameters/usbfs_memory_mb'`
3. 降低相机分辨率或帧率
4. 查看详细排查指南：`USB_CAMERA_TROUBLESHOOTING.md`

### 3. 错误：Enumerated 0 devices

**原因**：
- 权限不足（未使用 sudo）
- USB 相机未连接
- USB 驱动问题

**解决**：
```bash
# 检查 USB 设备
lsusb | grep -i hikvision

# 使用 sudo 运行
sudo ./run_server.sh
```

### 4. 推流模块超时

**原因**：相机启动失败，没有图像数据

**解决**：先解决相机启动问题（参考上述错误 2 和 3）

---

## 网络协议

### ZeroMQ 接口

**控制端口（REQ/REP）**：默认 5555
- 启动检测：`START_WORK`
- 停止检测：`STOP_WORK`
- 单次检测：`SINGLE_DETECTION`
- 设置曝光：`SET_EXPOSURE <value>`
- 设置增益：`SET_GAIN <value>`

**结果端口（PUB/SUB）**：默认 5556
- 发布检测结果（JSON 格式）

**原始图像端口（PUB/SUB）**：默认 5557（可选）
- 发布原始相机图像

### RTSP 推流

**URL 格式**：`rtsp://<server_ip>:8554/live/dronescrew`

---

## 日志

程序日志输出到标准输出，可以重定向到文件：

```bash
sudo ./run_server.sh 2>&1 | tee server.log
```

---

## 性能优化

### 降低带宽占用
1. 降低分辨率：1920x1080 → 1280x720
2. 降低帧率：30fps → 15fps
3. 使用 Mono8 像素格式（如果算法支持）

### 提高检测性能
1. 使用硬件加速（如 RK3588 的 NPU）
2. 优化算法模型（量化、剪枝）
3. 调整算法参数（scoreThreshold、nmsThreshold）

---

## 技术支持

遇到问题请查看：
1. `USB_CAMERA_TROUBLESHOOTING.md` - USB 相机故障排查
2. 程序日志输出
3. MVS SDK 文档：`SDK/Device/MVS/MVS_STD_V3.0.1_251113/MVS-3.0.1_aarch64_20251113/doc/`