GrabBag/App/DroneScrewbolt/DroneScrewServer/USB_CAMERA_TROUBLESHOOTING.md

# USB 相机故障排查指南

## 问题：MV_CC_StartGrabbing 失败，错误码 0x80000006 (MV_E_RESOURCE)

### 错误含义
资源申请失败，通常是 USB 带宽不足或系统资源限制导致。

---

## 快速解决方案

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

项目提供了自动配置脚本，会自动设置环境变量和 USB 内存：

```bash
# 使用启动脚本运行（自动配置环境）
sudo ./run_server.sh

# 或者先配置环境，再运行
source ./setup_mvs_env.sh
sudo ./DroneScrewServer
```

### 方法 2：手动配置

如果启动脚本不可用，手动执行以下步骤：

```bash
# 1. 设置环境变量
export MVCAM_SDK_PATH=/path/to/SDK/Device/MVS/MVS_STD_V3.0.1_251113/MVS-3.0.1_aarch64_20251113
export LD_LIBRARY_PATH=$MVCAM_SDK_PATH/lib/aarch64:$MVCAM_SDK_PATH/lib/aarch64/ThirdParty:$LD_LIBRARY_PATH

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

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

---

## 详细解决方案

### 1. 环境变量配置（必须）

MVS SDK 需要以下环境变量：

- `MVCAM_SDK_PATH`：SDK 根目录
- `LD_LIBRARY_PATH`：包含 SDK 的 .so 库路径

**检查环境变量**：
```bash
echo $MVCAM_SDK_PATH
echo $LD_LIBRARY_PATH
```

**缺失的库文件**：
如果运行时提示找不到 `.so` 文件，检查以下路径：
- `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`
  - 等其他依赖库

- `SDK/Device/MVS/MVS_STD_V3.0.1_251113/MVS-3.0.1_aarch64_20251113/lib/aarch64/ThirdParty/`
  - `libavutil.so.60.8.100`
  - `libswscale.so.9.1.100`

### 2. USB 内存配置（必须）

USB 相机需要足够的 USB 内存缓冲区：

```bash
# 查看当前配置
cat /sys/module/usbcore/parameters/usbfs_memory_mb

# 设置为 2000 MB（推荐值）
sudo sh -c 'echo 2000 > /sys/module/usbcore/parameters/usbfs_memory_mb'
```

**永久配置**（重启后生效）：
```bash
# 编辑 /etc/default/grub
sudo nano /etc/default/grub

# 添加或修改 GRUB_CMDLINE_LINUX_DEFAULT
GRUB_CMDLINE_LINUX_DEFAULT="quiet usbcore.usbfs_memory_mb=2000"

# 更新 grub
sudo update-grub
sudo reboot
```

### 3. 权限问题（必须）
USB 相机在 Linux/ARM 平台需要 root 权限或配置 udev 规则。

**临时方案**：
```bash
sudo ./DroneScrewServer
```

**永久方案**：配置 udev 规则
```bash
# 创建 udev 规则文件
sudo nano /etc/udev/rules.d/99-mvs-camera.rules

# 添加以下内容（根据实际相机 VID/PID 调整）
SUBSYSTEM=="usb", ATTRS{idVendor}=="xxxx", MODE="0666"

# 重新加载 udev 规则
sudo udevadm control --reload-rules
sudo udevadm trigger
```

### 2. USB 带宽优化

#### 方案 A：降低分辨率
在配置文件 `config/config.xml` 中调整：
```xml
<Camera serialNumber="..." exposureTime="10000" gain="5.0" 
        width="1280" height="720"/>  <!-- 从 1920x1080 降低到 1280x720 -->
```

#### 方案 B：降低帧率
代码已自动限制为 30fps，如仍有问题可进一步降低：
```cpp
// 在 MvsDevice.cpp OpenDevice() 中修改
MV_CC_SetFloatValue(m_handle, "AcquisitionFrameRate", 15.0f);  // 降至 15fps
```

#### 方案 C：调整像素格式
使用更低带宽的像素格式（如 Mono8 代替 RGB8）：
```cpp
// 在打开设备后添加
MV_CC_SetEnumValueByString(m_handle, "PixelFormat", "Mono8");
```

### 3. USB 控制器检查

#### 检查 USB 版本
```bash
lsusb -t
```
确保相机连接到 USB 3.0 端口（SuperSpeed）。

#### 检查 USB 设备列表
```bash
lsusb | grep -i camera
# 或
lsusb | grep -i hikvision
```

#### 检查 USB 带宽占用
```bash
cat /sys/kernel/debug/usb/devices
```

### 4. 系统资源检查

#### 内存检查
```bash
free -h
```
确保有足够的可用内存（建议至少 500MB 空闲）。

#### USB 缓冲区调整
```bash
# 增加 USB 缓冲区大小
echo 128 > /sys/module/usbcore/parameters/usbfs_memory_mb
```

### 5. 其他 USB 设备
断开其他占用带宽的 USB 设备（如 USB 存储、USB 网卡等）。

---

## 调试步骤

1. **确认权限**：先用 `sudo` 运行，确认是否为权限问题
2. **查看日志**：检查详细的错误信息（宽度、高度、帧率）
3. **降低参数**：逐步降低分辨率/帧率，找到可工作的配置
4. **检查硬件**：更换 USB 线缆、USB 端口
5. **系统优化**：调整 USB 缓冲区、关闭不必要的服务

---

## 推荐配置（ARM 平台）

### 低带宽配置（稳定优先）
```xml
<Camera serialNumber="..." 
        exposureTime="10000" 
        gain="5.0"
        width="1280" 
        height="720"/>
```
- 分辨率：1280x720
- 帧率：15-30 fps
- 像素格式：Mono8 或 YUV422

### 高质量配置（性能优先）
```xml
<Camera serialNumber="..." 
        exposureTime="10000" 
        gain="5.0"
        width="1920" 
        height="1080"/>
```
- 分辨率：1920x1080
- 帧率：30 fps
- 像素格式：RGB8
- **要求**：USB 3.0 + 充足带宽

---

## 相关文件

- 设备驱动：`Device/MvsDevice/Src/MvsDevice.cpp`
- 配置文件：`App/DroneScrewbolt/DroneScrewServer/config/config.xml`
- SDK 文档：`SDK/Device/MVS/MVS_STD_V3.0.1_251113/`