# OAK USB 部署指南

OAK USB 相机通过 USB-C 线缆供电和传输数据。它们支持 USB2 或 USB3（最高 10 Gbps），并连接到主机计算机。

### 安装依赖

Follow instructions below to install dependencies:

#### macOS & Windows

No installation script is needed.

#### Linux

Execute the commands below to setup the udev rules on Linux systems:

```bash
echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="03e7", MODE="0666"' | sudo tee /etc/udev/rules.d/80-movidius.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
```

Please refer to [Installation documentation](https://docs.luxonis.com/software/depthai/manual-install.md#supported-platforms) if
any issues occur.

### 连接 USB 设备

使用 USB3 USB-C 线缆以获得最大带宽。主机可以为设备供电，但建议使用外部电源。请参阅“为 OAK 设备供电” [此处](#Debugging)。

USB3 线缆在 USB-A 接头内部通常为蓝色。如果不是蓝色，则可能是 USB2 充电线缆。

> 使用过长（>2 米）的 USB 线缆连接可能会导致连接问题。如果需要使用更长的线缆，请确保是
> **有源**
> USB3 线缆。

### 初次连接

DepthAI 会扫描 USB 设备、上传固件/管线/资源，并启动管线。

最快的测试方法是使用 [OAK Viewer](https://docs.luxonis.com/software-v3/depthai/tools/oak-viewer.md)。如果它找到了设备并开始流式传输帧，说明连接正常。

### 调试

如果看到 RuntimeError: No available devices，则表示 DepthAI 未找到设备。请确认电源和 USB3 连接，然后使用下方的标签页。

我们建议在进行任何故障排除之前，使用最新的 depthai 版本。

#### lsusb

执行 lsusb | grep 03e7 时，应看到类似以下输出：

```bash
$ lsusb | grep 03e7
Bus 001 Device 120: ID 03e7:2485 Intel Movidius MyriadX
# 或者，如果设备已启动，应看到：
# Bus 001 Device 001: ID 03e7:f63b Intel Myriad VPU [Movidius Neural Compute Stick]
```

如果使用 lsusb -v，当设备等待连接时，会显示 USB 速度为 480 Mb/s。连接到设备后，depthai 会上传固件，速度将变为 5 Gb/s（如果支持 USB3）。

如果刷入了引导加载程序，设备可能首先以引导加载程序身份枚举：

```bash
Bus 003 Device 038: ID 03e7:f63c Intel Luxonis Bootloader
```

FFC 式设备（OAK-FFC 4P/3P/...）可以刷入引导加载程序，但并非必需。对于未刷入引导加载程序的普通设备，只有在应用启动后才能看到设备（无引导加载程序条目）。

应用启动时，设备会重新枚举为：

```bash
Bus 002 Device 032: ID 03e7:f63b Intel Myriad VPU [Movidius Neural Compute Stick]
```

只有启动后的设备才会枚举为 USB3。如果应用启动后仍停留在 USB2 速度，最常见的原因是主机侧 USB 端口或线缆有问题。请尝试其他 USB3 端口、较短的线缆或供电的 USB3 集线器。

运行 dmesg -w 并将 OAK 相机连接到主机时，终端中应显示类似以下输出：

```bash
/~$ dmesg -w

[223940.862544] usb 1-3.2: new high-speed USB device number 120 using xhci_hcd
[223940.963357] usb 1-3.2: New USB device found, idVendor=03e7, idProduct=2485, bcdDevice= 0.01
[223940.963364] usb 1-3.2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[223940.963368] usb 1-3.2: Product: Movidius MyriadX
[223940.963371] usb 1-3.2: Manufacturer: Movidius Ltd.
[223940.963373] usb 1-3.2: SerialNumber: 03e72485
```

#### 为 OAK 相机供电

USB3 能够提供高达 900mA 的电流，而 USB2 则能提供高达 500mA 的电流。OAK 相机的功耗在 500mA 到 900mA 之间，具体取决于型号和当前工作负载。 Pro 版本的设备峰值功耗可达 15W，取决于红外激光投射器和红外补光 LED
的使用情况。 这也取决于主机电脑。有些电脑的 USB 控制器供电能力不强（例如单板计算机，如 [RaspberryPi](https://docs.luxonis.com/hardware/platform/deploy/to-rpi.md)，其 eFuse
限制为 1.2A）。 主机的 USB 控制器还会影响您能使用的 USB 线缆长度，因为较长的线缆电阻更大，电压降也会更明显。 如果出现以下情况，您应为 OAK 相机外置供电：

 * 您将额外的 USB 设备连接到树莓派的 USB 端口，这些设备消耗的电流过大。树莓派总共只能提供 1.2A，因此如果所有 USB 设备的总功耗超过 1.2A，就会发生欠压。
 * 您使用的是 Pro 版 OAK 相机，它带有红外激光点投射器和红外补光 LED。

我们始终建议为您的 OAK 相机外置供电，可通过以下方式之一：

 * 圆孔插头 —— 在具有圆孔插头的设备上使用（[OAK-D](https://docs.luxonis.com/hardware/products/OAK-D.md)、[OAK-FFC
   4P](https://docs.luxonis.com/hardware/products/OAK-FFC%25204P.md)、[OAK-FFC
   3P](https://docs.luxonis.com/hardware/products/OAK-FFC%25203P.md)）
 * 有源 USB3 集线器
 * 使用 [Y 型适配器](https://docs.luxonis.com/hardware/products/Y-adapter.md)
 * 对于 Pro 设备，需要搭配 Y 型适配器使用一个 15W 电源适配器，以提供足够的电力。

原因是 OAK 存在电流尖峰（尤其是在使用视频编码器和运行 AI 推理时），峰值功耗可达 2W，这可能导致欠压。

#### Linux udev 规则

Linux 需要一条 udev 规则来允许非 root 用户访问 USB 设备。如果没有设置权限，depthai 会抛出如下错误：

```bash
[warning] Insufficient permissions to communicate with X_LINK_BOOTED device having name "2.8". Make sure udev rules are set
```

需要设置以下规则以允许访问 USB 设备：

```bash
echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="03e7", MODE="0666"' | sudo tee /etc/udev/rules.d/80-movidius.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
```

#### Using USB2

如果您使用的是USB2线缆/USB2端口，或者使用了劣质的USB3线缆，或者使用了较长的线缆（如超过2.5米），您可能会遇到类似于 X_LINK_COMMUNICATION_NOT_OPEN 或 X_LINK_ERROR
的错误。在这种情况下，一种解决方法是强制使用USB2通信。这将向设备上传USB2版本的固件，并将通信速度限制为USB2。

要强制使用USB2模式，您可以在创建 dai.Device 对象时设置 maxUsbSpeed=dai.UsbSpeed.HIGH

```python
import depthai as dai
pipeline = dai.Pipeline()
# 使用节点填充您的管道
# 强制USB2通信
with dai.Device(maxUsbSpeed=dai.UsbSpeed.HIGH) as device:
    # ...
```

> **卡在 USB2 模式**
> 仅有引导设备会枚举为 USB3。如果应用启动后仍停留在 USB2 速度，最常见的原因是主机端的 USB 端口或线缆。请尝试不同的 USB3 端口、更短的线缆或使用有源 USB3 集线器。

### 运行时

连接并上传管线后，连接应保持稳定，延迟应较低（低于 0.5 秒），USB3 下行速率应约为 2.5 Gbps。

### 调试

如果应用停止工作或通信缓慢，请参考下方的调试标签页。

#### Connection drop

如果连接在一段时间后断开，可能有几个潜在原因。

#### Device crash

设备可能因固件错误或用户应用程序中的bug而崩溃。

如果存在固件错误或（用户定义的）pipeline问题，会生成一份[崩溃报告](https://docs.luxonis.com/software-v3/depthai/examples/crash_report.md)，您应将其发送给我们（support@luxonis.com）。

如果运行上述脚本时未发现崩溃报告，则意味着可能是电源问题，或者连接断开（不太可能是硬件问题）。

另外，从depthai 2.28.0开始，自动崩溃报告生成功能默认启用。这将向Luxonis服务器发送崩溃报告，内容包括：

 * 崩溃转储本身
 * pipeline配置
 * depthai版本
 * 主机操作系统版本（MacOS/Linux/Windows）

它不会包含任何用户数据、图像或NN模型。但会包含[Script](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/script.md)节点代码。如果您想禁用自动崩溃报告生成，可以将环境变量DEPTHAI_DISABLE_CRASHDUMP_COLLECTION设置为1。

#### Power issue

这是一个相当常见的问题，通常是由于USB控制器无法为设备提供足够的电力。设备可能在一段时间内正常工作，然后因随机电源尖峰而崩溃。

请阅读上方关于如何正确为设备供电的章节（初始连接 > 为OAK相机供电）。

#### Communication issue

如果设备处于运动状态（例如在移动机器人上），且USB线缆未妥善固定，这也是一个常见问题。USB线路可能会中断（断开）一瞬间，导致设备断开连接。

如果是这种情况，建议使用USB3螺丝锁紧线缆（[Amazon链接](https://www.amazon.com/StarTech-com-Screw-Locking-Cable-10Gbps/dp/B09J99WGSF)）。

#### Low speed / High latency

如果你注意到FPS较低和/或消息延迟较高，应检查以下内容：

 1. [OAK带宽测试](https://github.com/luxonis/oak-examples/tree/master/random-scripts#oak-bandwidth-test) - 应在USB3下达到2.5/1.0 Gbps左右
 2. [OAK延迟测试](https://github.com/luxonis/oak-examples/tree/master/random-scripts#oak-latency-test) - 应低于5ms

如果带宽/延迟低于预期，应查看[低延迟文档](https://docs.luxonis.com/software/depthai/optimizing.md)。

### 后续步骤

成功部署设备后，您可以使用以下资源了解更多关于软件生态系统的信息：

 1. [软件文档](https://docs.luxonis.com/software-v3.md)
 2. [DepthAI 代码示例](https://docs.luxonis.com/software-v3/depthai/examples.md)