概览硬件软件云平台
OAK 应用
DepthAI
AI
软件栈
故障排除

本页目录

  • 设备 API
  • 连接到指定设备
  • 时钟
  • 主机时钟同步
  • 看门狗 - 仅限 RVC2
  • 自定义看门狗超时
  • 环境变量
  • 参考

设备

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

设备 API

Device 对象代表一个 OAK 设备。启动设备时，您需要将 管道 上传到设备，该管道将在 VPU 上执行。 当您在代码中创建设备时，固件会与管道以及其他资源（如 NN blob）一起上传。
Python
1with dai.Pipeline() as pipeline:
2    device = pipeline.getDefaultDevice()
3    # 打印设备上的 DeviceID、USB 速度和可用相机
4    print('DeviceID:',device.getDeviceInfo().getDeviceId())
5    print('USB speed:',device.getUsbSpeed())
6    print('Connected cameras:',device.getConnectedCameras())

连接到指定设备

如果您有 多个设备 且只想连接到特定设备，或者您的 OAK PoE 相机位于子网之外， 您可以指定要连接的设备（通过 DeviceID、IP 或 USB 端口名称）。
Python
1# 指定 DeviceID、IP 地址或 USB 路径
2device_info = depthai.DeviceInfo("14442C108144F1D000") # DeviceID
3#device_info = depthai.DeviceInfo("192.168.1.44") # IP 地址
4#device_info = depthai.DeviceInfo("3.3.3") # USB 端口名称
5with depthai.Device(device_info) as device:
6    # ...

时钟

depthai 时钟 dai.Clock.now()（Python）或 dai::Clock::now()（C++）是一个单调时钟，用于 depthai 库中的时间戳。它源自 std::chrono::steady_clock，不受系统时间更改（如 NTP 同步）的影响。该方法返回自主机（PC）启动以来的 datetime.timedelta（Python）或 std::chrono::steady_clock::duration（C++）。它在调用设备 消息 上的 getTimestamp() 时使用，并指示消息在设备上创建的时间。设备上还有一个单独的单调时钟，用于检索自设备（OAK）启动以来的时间，可通过 getTimestampDevice() 调用。

主机时钟同步

当 depthai 库连接到设备时，它会自动将设备的时间戳与主机的时间戳同步。时间戳同步以大约 5 秒的间隔持续进行， 并可以通过 API 进行配置（以下示例脚本）。
设备时钟与主机时钟的同步精度：PoE 相机低于 500µs，USB 相机低于 200µs（1σ 标准差）。
上图显示了设备时钟相对于主机时钟的精度。我们连接了 3 个设备（OAK PoE 相机），所有设备都通过 FSYNC Y 型适配器 进行了硬件同步。 Raspberry Pi（主机）有一个中断引脚连接到 FSYNC 线，因此在每帧开始时会发生中断，并记录主机时钟。然后我们将帧（同步的）时间戳与主机时间戳进行比较，并计算标准差。对于上面的直方图，我们运行此测试大约 3 小时。下图显示了设备时钟与主机时钟之间的差异。该图显示了设备时钟与主机时钟随时间变化的差值。该图是上述相同测试的结果。
Python
1# 配置主机时钟同步的示例
2
3import depthai as dai
4from datetime import timedelta
5# 配置管道
6with dai.Pipeline() as pipeline:
7    device = pipeline.getDefaultDevice()
8    # 第一个值：同步运行间隔
9    # 第二个值：每次运行用于计算更优值的同步样本数
10    # 第三个值：如果为 True，则部分同步请求将在随机间隔执行，否则在固定间隔执行
11    device.setTimesync(timedelta(seconds=5), 10, True) # （这些是默认值）

看门狗 - 仅限 RVC2

看门狗是 DepthAI 中 POE（以太网供电）设备运行的关键组件。当 DepthAI 与 POE 设备断开连接时，看门狗机制首先响应， 启动相机重置。此重置后跟完整的系统重启，包括加载 DepthAI 引导加载程序和初始化整个网络协议栈。看门狗进程是使摄像头能够重新连接所必需的，通常需要大约10秒，这意味着最快的重新连接时间为10秒。

自定义看门狗超时

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

Windows Powershell

Command Line
1$env:DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value>
2$env:DEPTHAI_BOOTUP_TIMEOUT=<my_value>
3python3 script.py

Linux/macOS

Command Line
1DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value> DEPTHAI_BOOTUP_TIMEOUT=<my_value> python3 script.py

Windows CMD

Command Line
1set DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value>
2set DEPTHAI_BOOTUP_TIMEOUT=<my_value>
3python3 script.py
或者，您可以直接在代码中设置超时：
Python
1pipeline = depthai.Pipeline()
2
3# 创建 BoardConfig 对象
4config = depthai.BoardConfig()
5
6# 设置参数
7config.watchdogInitialDelayMs = <my_value>
8config.watchdogTimeoutMs = <my_value>
9
10pipeline.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_LISTMXID 列表的别名。列表过滤结果为“与”关系而非“或”
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_URLLuxonis Hub 事件的 URL
DEPTHAI_HUB_API_KEYLuxonis 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 或更低级别以打印。

参考

class

dai::Device

#include Device.hpp
function
Device()
Connects to any available device with a DEFAULT_SEARCH_TIME timeout. Uses OpenVINO version OpenVINO::VERSION_UNIVERSAL
function
~Device()
function
DeviceBase()
Connects to any available device with a DEFAULT_SEARCH_TIME timeout. Uses OpenVINO version OpenVINO::VERSION_UNIVERSAL
function
DeviceBase(UsbSpeed maxUsbSpeed)
Connects to device
Parameters
  • maxUsbSpeed: Maximum allowed USB speed
function
DeviceBase(const DeviceInfo & devInfo, UsbSpeed maxUsbSpeed)
Connects to device specified by devInfo.
Parameters
  • devInfo: DeviceInfo which specifies which device to connect to
  • maxUsbSpeed: Maximum allowed USB speed
function
DeviceBase(const DeviceInfo & devInfo, const std::filesystem::path & pathToCmd)
Connects to device specified by devInfo.
Parameters
  • devInfo: DeviceInfo which specifies which device to connect to
  • pathToCmd: Path to custom device firmware
explicit function
DeviceBase(const Config & config)
Connects to any available device with custom config.
Parameters
  • config: Device custom configuration to boot with
function
DeviceBase(const Config & config, const DeviceInfo & devInfo)
Connects to device 'devInfo' with custom config.
Parameters
  • config: Device custom configuration to boot with
  • devInfo: DeviceInfo which specifies which device to connect to
explicit function
DeviceBase(const DeviceInfo & devInfo)
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
function
DeviceBase(std::string nameOrDeviceId)
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
function
DeviceBase(std::string nameOrDeviceId, UsbSpeed maxUsbSpeed)
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
function
DeviceBase(const Config & config, UsbSpeed maxUsbSpeed)
Connects to device specified by devInfo.
Parameters
  • config: Config with which the device will be booted with
  • maxUsbSpeed: Maximum allowed USB speed
function
DeviceBase(const Config & config, const std::filesystem::path & pathToCmd)
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
function
DeviceBase(const Config & config, const DeviceInfo & devInfo, UsbSpeed maxUsbSpeed)
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
function
DeviceBase(const Config & config, const DeviceInfo & devInfo, const std::filesystem::path & pathToCmd, bool dumpOnly)
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
enum

ReconnectionStatus