DepthAI v2 has been superseded by DepthAI v3. You are viewing legacy documentation.
此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

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

设备 API

Device 对象代表一个 OAK 设备。启动设备时,您必须将一个 Pipeline 上传到设备,该 Pipeline 将在 VPU 上执行。 当您在代码中创建设备时,固件会与 Pipeline 和其他资产(例如 NN blob)一起上传。
Python
1pipeline = depthai.Pipeline()
2
3# 创建节点,配置它们并将它们链接在一起
4
5# 连接到设备并将 Pipeline 上传到设备
6with depthai.Device(pipeline) as device:
7    # 打印 MxID、USB 速度和设备上可用的摄像头
8    print('MxId:',device.getDeviceInfo().getMxId())
9    print('USB speed:',device.getUsbSpeed())
10    print('Connected cameras:',device.getConnectedCameras())

连接到指定设备

如果您有 多个设备 并且只想连接到特定设备,或者您的 OAK PoE 摄像头在您的 子网之外,您可以指定要连接的设备(通过 MxID、IP 或 USB 端口名称)。
Python
1# 指定 MXID、IP 地址或 USB 路径
2device_info = depthai.DeviceInfo("14442C108144F1D000") # MXID
3#device_info = depthai.DeviceInfo("192.168.1.44") # IP 地址
4#device_info = depthai.DeviceInfo("3.3.3") # USB 端口名称
5with depthai.Device(pipeline, 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 型适配器 进行硬件同步。 树莓派(主机)有一个连接到 FSYNC 线的中断引脚,因此在每帧开始时发生中断并记录主机时钟。然后我们将帧(同步)时间戳与 主机时间戳进行比较并计算标准差。对于上面的直方图,我们运行此测试大约 3 小时。下图表示设备和主机时钟之间的差异。该图显示了设备和主机时钟之间随时间变化的差异。该图是与前一个测试相同的结果。
Python
1# 配置主机时钟同步示例
2
3import depthai as dai
4from datetime import timedelta
5# 配置 Pipeline
6with dai.Device(pipeline) as device:
7    # 第一个值:时间同步运行之间的间隔
8    # 第二个值:每次运行的时间同步样本数,用于计算更好的值
9    # 第三个值:如果为 true,则部分时间同步请求将以随机间隔执行,否则以固定间隔执行
10    device.setTimesync(timedelta(seconds=5), 10, True) # (这些是默认值)

设备队列

初始化设备后,您可以创建与 XLinkIn/XLinkOut 节点匹配的输入/输出队列。这些队列将位于主机计算机(RAM)上。
Py
1pipeline = dai.Pipeline()
2
3xout = pipeline.createXLinkOut()
4xout.setStreamName("output_name")
5# ...
6xin = pipeline.createXLinkIn()
7xin.setStreamName("input_name")
8# ...
9with dai.Device(pipeline) as device:
10
11  outputQueue = device.getOutputQueue("output_name", maxSize=5, blocking=False)
12  inputQueue = device.getInputQueue("input_name")
13
14  outputQueue.get() # 从队列中读取,阻塞直到消息到达
15  outputQueue.tryGet() # 从队列中读取,如果没有消息则返回 None(不阻塞)
16  if outputQueue.has(): # 检查队列中是否有任何消息
当您定义输出队列时,设备可以随时向其推送新消息,主机可以随时从中读取。

输出队列设置

当主机从队列中读取速度非常快时(例如,在 while True 循环中),队列,无论其大小如何,大部分时间都将保持为空。但是,随着我们在主机端添加内容(额外的处理、分析等),设备可能会比主机读取速度更快地将消息推送到主机队列。然后队列中的消息将开始增加——在这种情况下,maxSize 和 blocking 设置将决定队列的行为。两种常见的配置是:
Py
1with dai.Device(pipeline) as device:
2  # 如果您只想要最新消息,并且不关心以前的消息;
3  # 当新消息到达主机时,如果它仍在队列中,它将覆盖以前(最旧的)消息
4  q1 = device.getOutputQueue(name="name1", maxSize=1, blocking=False)
5
6
7  # 如果您关心每一条消息(例如 H264/5 编码视频;如果您错过一帧,您将得到伪影);
8  # 如果队列已满,设备将等待主机从队列中读取消息
9  q2 = device.getOutputQueue(name="name2", maxSize=30, blocking=True) # 也是默认值 (maxSize=30/blocking=True)
我们使用 maxSize=30 只是一个例子,它可以是任何 int16 数字。由于设备队列在主机计算机上,内存 (RAM) 通常不是那么稀缺,因此 maxSize 不会那么重要。 但是,如果您使用像 RPI Zero (512MB RAM) 这样的小型 SBC,并且正在流式传输大帧(例如 4K 未编码),如果您将 maxSize 设置为高值(并且没有足够快地从队列中读取),您可能会很快耗尽内存。

一些额外信息

  • 队列是线程安全的——它们可以从任何线程访问。
  • 队列的创建方式是每个队列都有自己的线程,负责接收、序列化/反序列化和转发消息(输入/输出队列相同)。
  • Device 对象不是完全线程安全的。一些 RPC 调用(例如 getLogLevel、setLogLevel、getDdrMemoryUsage)一旦设置了互斥锁就会变得线程安全(目前可能存在竞争)。

看门狗

看门狗是 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'、'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_PROTOCOL将默认搜索限制为指定的协议。选项:any、usb、tcpip。
DEPTHAI_DEVICE_MXID_LIST将默认搜索限制为指定的 MXID。接受逗号分隔的 MXID 列表。列表以“AND”方式而不是“OR”方式过滤结果
DEPTHAI_DEVICE_ID_LISTMXID 列表的别名。列表以“AND”方式而不是“OR”方式过滤结果
DEPTHAI_DEVICE_NAME_LIST将默认搜索限制为指定的 NAME。接受逗号分隔的 NAME 列表。列表以“AND”方式而不是“OR”方式过滤结果
DEPTHAI_DEVICE_BINARY覆盖设备固件二进制文件。主要用于内部调试。
DEPTHAI_BOOTLOADER_BINARY_USB覆盖设备 USB 引导加载程序二进制文件。主要用于内部调试。
DEPTHAI_BOOTLOADER_BINARY_ETH覆盖设备网络引导加载程序二进制文件。主要用于内部调试。
DEPTHAI_DISABLE_CRASHDUMP_COLLECTION设置为 1 时,禁用向 Luxonis 发送崩溃转储。默认情况下,崩溃转储、管道、操作系统和 depthai 版本信息会发送给 Luxonis 以进行诊断。
DEPTHAI_ENABLE_ANALYTICS_COLLECTION设置为 1 时,分析数据(管道架构)会发送给 Luxonis,用于进一步改进库。

参考

class

depthai.Device(depthai.DeviceBase)

class
Config
Device specific configuration
method
method
method
method
getInputQueueNames(self) -> list[str]: list[str]
Get all available input queue names  Returns:     Vector of input queue names
method
method
getOutputQueueNames(self) -> list[str]: list[str]
Get all available output queue names  Returns:     Vector of output queue names
method
method