# 设备

Device 类代表单个 Luxonis 硬件设备（OAK 相机或 RAE 机器人）。在我们所有设备上都有一个强大的机器人视觉核心
([RVC](https://docs.luxonis.com/hardware/platform/rvc/rvc2.md#rvc2))。RVC 针对执行 AI 推理、CV 操作以及处理传感器输入（如立体深度、视频编码器等）进行了优化。

## 设备 API

Device 对象代表一个 OAK 设备。启动设备时，您需要将 [管道](https://docs.luxonis.com/software-v3/depthai/depthai-components/pipeline.md) 上传到设备，该管道将在 VPU
上执行。 当您在代码中创建设备时，固件会与管道以及其他资源（如 NN blob）一起上传。

```python
with dai.Pipeline() as pipeline:
    device = pipeline.getDefaultDevice()
    # 打印设备上的 DeviceID、USB 速度和可用相机
    print('DeviceID:',device.getDeviceInfo().getDeviceId())
    print('USB speed:',device.getUsbSpeed())
    print('Connected cameras:',device.getConnectedCameras())
```

## 连接到指定设备

如果您有 [多个设备](https://docs.luxonis.com/software-v3/depthai/tutorials/multi-device-setup.md) 且只想连接到特定设备，或者您的 OAK PoE 相机位于子网之外，
您可以指定要连接的设备（通过 DeviceID、IP 或 USB 端口名称）。

```python
# 指定 DeviceID、IP 地址或 USB 路径
device_info = depthai.DeviceInfo("14442C108144F1D000") # DeviceID
#device_info = depthai.DeviceInfo("192.168.1.44") # IP 地址
#device_info = depthai.DeviceInfo("3.3.3") # USB 端口名称
with depthai.Device(device_info) as device:
    # ...
```

## 时钟

depthai 时钟 dai.Clock.now()（Python）或 dai::Clock::now()（C++）是一个单调时钟，用于 depthai 库中的时间戳。它源自
[std::chrono::steady_clock](https://en.cppreference.com/w/cpp/chrono/steady_clock)，不受系统时间更改（如 NTP 同步）的影响。

该方法返回自主机（PC）启动以来的 datetime.timedelta（Python）或 std::chrono::steady_clock::duration（C++）。它在调用设备
[消息](https://docs.luxonis.com/software-v3/depthai/depthai-components/messages.md) 上的 getTimestamp() 时使用，并指示消息在设备上创建的时间。

设备上还有一个单独的单调时钟，用于检索自设备（OAK）启动以来的时间，可通过 getTimestampDevice() 调用。

### 主机时钟同步

当 depthai 库连接到设备时，它会自动将设备的时间戳与主机的时间戳同步。时间戳同步以大约 5 秒的间隔持续进行， 并可以通过 API 进行配置（以下示例脚本）。

设备时钟与主机时钟的同步精度：PoE 相机低于 500µs，USB 相机低于 200µs（1σ 标准差）。

上图显示了设备时钟相对于主机时钟的精度。我们连接了 3 个设备（OAK PoE 相机），所有设备都通过 [FSYNC Y
型适配器](https://shop71313603.taobao.com/?spm=pc_detail.30350276.shop_block.dshopinfo.27a17dd635FNDA) 进行了硬件同步。 Raspberry
Pi（主机）有一个中断引脚连接到 FSYNC 线，因此在每帧开始时会发生中断，并记录主机时钟。然后我们将帧（同步的）时间戳与主机时间戳进行比较，并计算标准差。对于上面的直方图，我们运行此测试大约 3 小时。

下图显示了设备时钟与主机时钟之间的差异。该图显示了设备时钟与主机时钟随时间变化的差值。该图是上述相同测试的结果。

```python
# 配置主机时钟同步的示例

import depthai as dai
from datetime import timedelta
# 配置管道
with dai.Pipeline() as pipeline:
    device = pipeline.getDefaultDevice()
    # 第一个值：同步运行间隔
    # 第二个值：每次运行用于计算更优值的同步样本数
    # 第三个值：如果为 True，则部分同步请求将在随机间隔执行，否则在固定间隔执行
    device.setTimesync(timedelta(seconds=5), 10, True) # （这些是默认值）
```

## 看门狗 - 仅限 RVC2

看门狗是 DepthAI 中 POE（以太网供电）设备运行的关键组件。当 DepthAI 与 POE 设备断开连接时，看门狗机制首先响应， 启动相机重置。此重置后跟完整的系统重启，包括加载 DepthAI 引导加载程序和初始化整个网络协议栈。

看门狗进程是使摄像头能够重新连接所必需的，通常需要大约10秒，这意味着最快的重新连接时间为10秒。

### 自定义看门狗超时

按如下方式设置环境变量 DEPTHAI_WATCHDOG_INITIAL_DELAY 和 DEPTHAI_BOOTUP_TIMEOUT 为您期望的超时值（以毫秒为单位）：

#### Windows Powershell

```bash
$env:DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value>
$env:DEPTHAI_BOOTUP_TIMEOUT=<my_value>
python3 script.py
```

#### Linux/macOS

```bash
DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value> DEPTHAI_BOOTUP_TIMEOUT=<my_value> python3 script.py
```

#### Windows CMD

```bash
set DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value>
set DEPTHAI_BOOTUP_TIMEOUT=<my_value>
python3 script.py
```

或者，您可以直接在代码中设置超时：

```python
pipeline = depthai.Pipeline()

# 创建 BoardConfig 对象
config = depthai.BoardConfig()

# 设置参数
config.watchdogInitialDelayMs = <my_value>
config.watchdogTimeoutMs = <my_value>

pipeline.setBoardConfig(config)
```

通过调整这些设置，您可以根据具体需求定制看门狗功能。

## 环境变量

下表列出了系统中使用的各种环境变量及其描述：

| 环境变量 | 描述 |
| --- | --- |
| `DEPTHAI_LEVEL` | 设置日志详细级别，选项：'trace', 'debug', 'info', 'warn', 'error', 'off' |
| `XLINK_LEVEL` | 设置 XLink 库的日志详细级别，选项：'debug', 'info', 'warn', 'error', 'fatal', 'off' |
| `DEPTHAI_INSTALL_SIGNAL_HANDLER` | 设置为 0 可禁用安装 Backward 信号处理器以打印堆栈跟踪 |
| `DEPTHAI_WATCHDOG` | 设置设备看门狗超时。用于调试（`DEPTHAI_WATCHDOG=0`），以防止进程暂停时设备复位。 |
| `DEPTHAI_WATCHDOG_INITIAL_DELAY` | 指定设备看门狗启动前的延迟时间。 |
| `DEPTHAI_SEARCH_TIMEOUT` | 指定在阻塞函数中搜索设备时的超时时间（毫秒）。 |
| `DEPTHAI_CONNECT_TIMEOUT` | 指定建立与给定设备连接的超时时间（毫秒）。 |
| `DEPTHAI_BOOTUP_TIMEOUT` | 指定发送二进制文件后等待设备启动的超时时间（毫秒）。 |
| `DEPTHAI_RECONNECT_TIMEOUT` | 指定连接丢失后重新连接设备的超时时间（毫秒）。如果设置为 0，则禁用重连。 |
| `DEPTHAI_PROTOCOL` | 将默认搜索限制为指定的协议。选项：`any`, `usb`, `tcpip`, `tcpshd`。 |
| `DEPTHAI_PLATFORM` | 将默认搜索限制为指定的平台。选项：`any`, `rvc2`, `rvc3`, `rvc4`。 |
| `DEPTHAI_DEVICE_MXID_LIST` | 将默认搜索限制为指定的 MXID。接受逗号分隔的 MXID 列表。列表过滤结果为“与”关系而非“或” |
| `DEPTHAI_DEVICE_ID_LIST` | MXID 列表的别名。列表过滤结果为“与”关系而非“或” |
| `DEPTHAI_DEVICE_NAME_LIST` | 将默认搜索限制为指定的名称。接受逗号分隔的名称列表。列表过滤结果为“与”关系而非“或”。在 tcpip 情况下，也会查找主机子网之外的名称。 |
| `DEPTHAI_DEVICE_BINARY` | 覆盖设备固件二进制文件。主要用于内部调试。 |
| `DEPTHAI_DEVICE_RVC4_FWP` | 覆盖设备 RVC4 固件二进制文件。主要用于内部调试。 |
| `DEPTHAI_BOOTLOADER_BINARY_USB` | 覆盖设备 USB 引导加载程序二进制文件。主要用于内部调试。 |
| `DEPTHAI_BOOTLOADER_BINARY_ETH` | 覆盖设备网络引导加载程序二进制文件。主要用于内部调试。 |
| `DEPTHAI_ALLOW_FACTORY_FLASHING` | 仅限内部使用 |
| `DEPTHAI_LIBUSB_ANDROID_JAVAVM` | 传递给 libusb 的 JavaVM 指针，用于在无 root 权限的 Android 设备上进行交互。解释为 uintptr_t 的十进制值 |
| `DEPTHAI_CRASHDUMP` | 保存崩溃转储的目录。 |
| `DEPTHAI_CRASHDUMP_TIMEOUT` | 获取崩溃转储时等待设备重启的持续时间（毫秒）。如果为 0，则禁用崩溃转储检索。 |
| `DEPTHAI_ENABLE_ANALYTICS_COLLECTION` | 启用自动分析收集（管道模式），用于改进库 |
| `DEPTHAI_DISABLE_CRASHDUMP_COLLECTION` | 禁用自动崩溃转储收集，用于改进库 |
| `DEPTHAI_HUB_EVENTS_BASE_URL` | Luxonis Hub 事件的 URL |
| `DEPTHAI_HUB_API_KEY` | Luxonis Hub 的 API 密钥 |
| `DEPTHAI_ZOO_INTERNET_CHECK` | （默认）1 - 执行网络检查，如果可用，下载最新模型版本；0 - 跳过网络检查并使用缓存的模型 |
| `DEPTHAI_ZOO_INTERNET_CHECK_TIMEOUT` | （默认）1000 - 网络检查的超时时间（毫秒） |
| `DEPTHAI_ZOO_CACHE_PATH` | （默认）.depthai_cached_models - 缓存 zoo 模型的文件夹 |
| `DEPTHAI_ZOO_MODELS_PATH` | （默认）depthai_models - 存储 zoo 模型描述文件的文件夹 |
| `DEPTHAI_RECORD` | 启用全局记录到指定目录。 |
| `DEPTHAI_REPLAY` | 从指定文件或目录重放全局记录。 |
| `DEPTHAI_PROFILING` | 启用主机与连接设备间数据传输的运行时分析。设置为 1 启用。需要 `DEPTHAI_LEVEL=debug` 或更低级别以打印。 |

## 参考

### dai::Device

Kind: class

Represents the DepthAI device with the methods to interact with it. Implements the host-side queues to connect with XLinkIn and
XLinkOut nodes

#### ReconnectionStatus

Kind: enum

#### Device()

Kind: function

Connects to any available device with a DEFAULT_SEARCH_TIME timeout. Uses OpenVINO version OpenVINO::VERSION_UNIVERSAL

#### ~Device()

Kind: function

dtor to close the device

#### DeviceBase()

Kind: function

Connects to any available device with a DEFAULT_SEARCH_TIME timeout. Uses OpenVINO version OpenVINO::VERSION_UNIVERSAL

#### DeviceBase(UsbSpeed maxUsbSpeed)

Kind: function

Connects to device parameters: maxUsbSpeed: Maximum allowed USB speed

#### DeviceBase(const DeviceInfo & devInfo, UsbSpeed maxUsbSpeed)

Kind: function

Connects to device specified by devInfo. parameters: devInfo: DeviceInfo which specifies which device to connect to; maxUsbSpeed:
Maximum allowed USB speed

#### DeviceBase(const DeviceInfo & devInfo, const std::filesystem::path & pathToCmd)

Kind: function

Connects to device specified by devInfo. parameters: devInfo: DeviceInfo which specifies which device to connect to; pathToCmd:
Path to custom device firmware

#### DeviceBase(const Config & config)

Kind: function

Connects to any available device with custom config. parameters: config: Device custom configuration to boot with

#### DeviceBase(const Config & config, const DeviceInfo & devInfo)

Kind: function

Connects to device 'devInfo' with custom config. parameters: config: Device custom configuration to boot with; devInfo: DeviceInfo
which specifies which device to connect to

#### DeviceBase(const DeviceInfo & devInfo)

Kind: function

Connects to any available device with a DEFAULT_SEARCH_TIME timeout. Uses OpenVINO version OpenVINO::VERSION_UNIVERSAL parameters:
devInfo: DeviceInfo which specifies which device to connect to

#### DeviceBase(std::string nameOrDeviceId)

Kind: function

Connects to any available device with a DEFAULT_SEARCH_TIME timeout. Uses OpenVINO version OpenVINO::VERSION_UNIVERSAL parameters:
nameOrDeviceId: Creates DeviceInfo with nameOrDeviceId to connect to

#### DeviceBase(std::string nameOrDeviceId, UsbSpeed maxUsbSpeed)

Kind: function

Connects to any available device with a DEFAULT_SEARCH_TIME timeout. Uses OpenVINO version OpenVINO::VERSION_UNIVERSAL parameters:
nameOrDeviceId: Creates DeviceInfo with nameOrDeviceId to connect to; maxUsbSpeed: Maximum allowed USB speed

#### DeviceBase(const Config & config, UsbSpeed maxUsbSpeed)

Kind: function

Connects to device specified by devInfo. parameters: config: Config with which the device will be booted with; maxUsbSpeed:
Maximum allowed USB speed

#### DeviceBase(const Config & config, const std::filesystem::path & pathToCmd)

Kind: function

Connects to any available device with a DEFAULT_SEARCH_TIME timeout. parameters: config: Config with which the device will be
booted with; pathToCmd: Path to custom device firmware

#### DeviceBase(const Config & config, const DeviceInfo & devInfo, UsbSpeed maxUsbSpeed)

Kind: function

Connects to device specified by devInfo. parameters: config: Config with which the device will be booted with; devInfo: DeviceInfo
which specifies which device to connect to; maxUsbSpeed: Maximum allowed USB speed

#### DeviceBase(const Config & config, const DeviceInfo & devInfo, const std::filesystem::path & pathToCmd, bool dumpOnly)

Kind: function

Connects to device specified by devInfo. parameters: config: Config with which the device will be booted with; devInfo: DeviceInfo
which specifies which device to connect to; pathToCmd: Path to custom device firmware; dumpOnly: If true only the minimal
connection is established to retrieve the crash dump