此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 设备 API
  • 连接到指定设备
  • 健康检查
  • 时钟
  • 主机时钟同步
  • 看门狗 - 仅限 RVC2
  • 自定义看门狗超时
  • 环境变量
  • 参考
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
设备类代表单个 Luxonis 硬件设备(OAK 摄像头或 RAE 机器人)。我们所有的设备都配备强大的机器人视觉核心 (RVC)。RVC 针对执行 AI 推理、CV 操作和 处理感官输入(例如立体深度、视频编码器等)进行了优化。

设备 API

Device 对象代表一个 OAK 设备。启动设备时,您必须向其上传一个 Pipeline,该 Pipeline 将在 VPU 上执行。 当您在代码中创建设备时,固件会与 Pipeline 和其他资产(例如 NN blob)一起上传。
Python
1with dai.Pipeline() as pipeline:
2    device = pipeline.getDefaultDevice()
3    # 打印设备 ID、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 3.8.0 增加了一个快速健康检查 API,您可以在启动主应用程序逻辑之前从主机运行它。使用它来验证设备状态、连接类型、带宽、电源行为、校准、摄像头传感器、红外传感器以及任何报告的问题。健康检查针对 DeviceInfo 运行,因此您可以先选择目标设备,然后执行诊断:
Python
1import depthai as dai
2from datetime import timedelta
3
4device_infos = dai.Device.getAllConnectedDevices()
5config = dai.HealthCheckConfig(
6    powerSupplyCheckDuration=timedelta(seconds=20)
7)
8
9metrics = dai.Device.performHealthCheck(device_infos[0], config)
10print(metrics)
当您需要更长的验证窗口来处理电源受限或部署式设置时,请增加 powerSupplyCheckDuration。

时钟

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# 配置 Pipeline
6with dai.Pipeline() as pipeline:
7    device = pipeline.getDefaultDevice()
8    # 第一个值:时间同步运行之间的间隔
9    # 第二个值:每次运行的时间同步样本数,用于计算更好的值
10    # 第三个值:如果为 true,则部分时间同步请求将以随机间隔执行,否则以固定间隔执行
11    device.setTimesync(timedelta(seconds=5), 10, True) # (这些是默认值)

看门狗 - 仅限 RVC2

看门狗是 POE(以太网供电)设备与 DepthAI 协同操作的关键组件。当 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 列表。列表以“AND”方式而不是“OR”方式过滤结果
DEPTHAI_DEVICE_ID_LISTMXID 列表的别名。列表以“AND”方式而不是“OR”方式过滤结果
DEPTHAI_DEVICE_NAME_LIST将默认搜索限制为指定的 NAME。接受逗号分隔的 NAME 列表。列表以“AND”方式而不是“OR”方式过滤结果。它还在 tcpip 情况下搜索主机子网之外的 NAME。
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 指针,用于无根 Android 与设备的交互。解释为 uintptr_t 的十进制值
DEPTHAI_CRASHDUMP保存崩溃转储的目录。
DEPTHAI_CRASHDUMP_TIMEOUT指定获取崩溃转储时等待设备重启的持续时间(毫秒)。如果为 0,则禁用崩溃转储检索。
DEPTHAI_TELEMETRY设置为 0 可选择退出默认遥测收集。
DEPTHAI_ENABLE_ANALYTICS_COLLECTION用于 Pipeline 模式分析收集的旧环境变量。
DEPTHAI_DISABLE_CRASHDUMP_COLLECTION设置为 1 可禁用用于诊断的自动崩溃转储收集。
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()
dtor to close the 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