Device

Device is an OAK camera or a RAE robot. On all of our devices there’s a powerful Robotics Vision Core (RVC). The RVC is optimized for performing AI inference, CV operations, and for processing sensory inputs (eg. stereo depth, video encoders, etc.).

Device API

Device object represents an OAK device. When starting the device, you have to upload a Pipeline to it, which will get executed on the VPU. When you create the device in the code, firmware is uploaded together with the pipeline and other assets (such as NN blobs).

pipeline = depthai.Pipeline()

# Create nodes, configure them and link them together

# Upload the pipeline to the device
with depthai.Device(pipeline) as device:
  # Print MxID, USB speed, and available cameras on the device
  print('MxId:',device.getDeviceInfo().getMxId())
  print('USB speed:',device.getUsbSpeed())
  print('Connected cameras:',device.getConnectedCameras())

  # Input queue, to send message from the host to the device (you can receive the message on the device with XLinkIn)
  input_q = device.getInputQueue("input_name", maxSize=4, blocking=False)

  # Output queue, to receive message on the host from the device (you can send the message on the device with XLinkOut)
  output_q = device.getOutputQueue("output_name", maxSize=4, blocking=False)

  while True:
      # Get a message that came from the queue
      output_q.get() # Or output_q.tryGet() for non-blocking

      # Send a message to the device
      cfg = depthai.ImageManipConfig()
      input_q.send(cfg)

Connect to specified device

If you have multiple devices and only want to connect to a specific one, or if your OAK PoE camera is outside of your subnet, you can specify the device (either with MxID, IP, or USB port name) you want to connect to.

# Specify MXID, IP Address or USB path
device_info = depthai.DeviceInfo("14442C108144F1D000") # MXID
#device_info = depthai.DeviceInfo("192.168.1.44") # IP Address
#device_info = depthai.DeviceInfo("3.3.3") # USB port name
with depthai.Device(pipeline, device_info) as device:
    # ...

Host clock syncing

When depthai library connects to a device, it automatically syncs device’s timestamp to host’s timestamp. Timestamp syncing happens continuously at around 5 second intervals, and can be configured via API (example script below).

../../_images/device_timesync.jpg

Device clocks are synced at below 500µs accuracy for PoE cameras, and below 200µs accuracy for USB cameras at 1σ (standard deviation) with host clock.

../../_images/clock-syncing.png

Above is a graph representing the accuracy of the device clock with respect to the host clock. We had 3 devices connected (OAK PoE cameras), all were hardware synchronized using FSYNC Y-adapter. Raspberry Pi (the host) had an interrupt pin connected to the FSYNC line, so at the start of each frame the interrupt happened and the host clock was recorded. Then we compared frame (synced) timestamps with host timestamps and computed the standard deviation. For the histogram above we ran this test for approximately 3 hours.

Below is a graph representing the difference between the device and host clock. The graph shows the difference between the device and host clock over time. The graph is a result of the same test as the previous one.

../../_images/timestamp-difference.png
# Configure host clock syncing example

import depthai as dai
from datetime import timedelta
# Configure pipeline
with dai.Device(pipeline) as device:
    # 1st value: Interval between timesync runs
    # 2nd value: Number of timesync samples per run which are used to compute a better value
    # 3rd value: If true partial timesync requests will be performed at random intervals, otherwise at fixed intervals
    device.setTimesync(timedelta(seconds=5), 10, True) # (These are default values)

Multiple devices

If you want to use multiple devices on a host, check Multiple DepthAI per Host.

Device queues

After initializing the device, you can create input/output queues that match XLinkIn/XLinkOut nodes in the pipeline. These queues will be located on the host computer (in RAM).

pipeline = dai.Pipeline()

xout = pipeline.createXLinkOut()
xout.setStreamName("output_name")
# ...
xin = pipeline.createXLinkIn()
xin.setStreamName("input_name")
# ...
with dai.Device(pipeline) as device:

  outputQueue = device.getOutputQueue("output_name", maxSize=5, blocking=False)
  inputQueue = device.getInputQueue("input_name")

  outputQueue.get() # Read from the queue, blocks until message arrives
  outputQueue.tryGet() # Read from the queue, returns None if there's no msg (doesn't block)
  if outputQueue.has(): # Check if there are any messages in the queue

When you define an output queue, the device can push new messages to it at any time, and the host can read from it at any time.

Output queue - maxSize and blocking

When the host is reading very fast from the queue (inside while True loop), the queue, regardless of its size, will stay empty most of the time. But as we add things on the host side (additional processing, analysis, etc), it may happen that the device will be pushing messages to the queue faster than the host can read from it. And then the messages in the queue will start to increase - and both maxSize and blocking flags determine the behavior of the queue in this case. Two common configurations are:

with dai.Device(pipeline) as device:
  # If you want only the latest message, and don't care about previous ones;
  # When a new msg arrives to the host, it will overwrite the previous (oldest) one if it's still in the queue
  q1 = device.getOutputQueue(name="name1", maxSize=1, blocking=False)


  # If you care about every single message (eg. H264/5 encoded video; if you miss a frame, you will get artifacts);
  # If the queue is full, the device will wait until the host reads a message from the queue
  q2 = device.getOutputQueue(name="name2", maxSize=30, blocking=True) # Also default values (maxSize=30/blocking=True)

We used maxSize=30 just as an example, but it can be any int16 number. Since device queues are on the host computer, memory (RAM) usually isn’t that scarce, so maxSize wouldn’t matter that much. But if you are using a small SBC like RPI Zero (512MB RAM), and are streaming large frames (eg. 4K unencoded), you could quickly run out of memory if you set maxSize to a high value (and don’t read from the queue fast enough).

Some additional information

  • Queues are thread-safe - they can be accessed from any thread.

  • Queues are created such that each queue is its own thread which takes care of receiving, serializing/deserializing, and sending the messages forward (same for input/output queues).

  • The Device object isn’t fully thread-safe. Some RPC calls (eg. getLogLevel, setLogLevel, getDdrMemoryUsage) will get thread-safe once the mutex is set in place (right now there could be races).

Watchdog

The watchdog is a crucial component in the operation of POE (Power over Ethernet) devices with DepthAI. When DepthAI disconnects from a POE device, the watchdog mechanism is the first to respond, initiating a reset of the camera. This reset is followed by a complete system reboot, which includes the loading of the DepthAI bootloader and the initialization of the entire networking stack.

The watchdog process is necessary to make the camera available for reconnection and typically takes about 10 seconds, which means the fastest possible reconnection time is 10 seconds.

Customizing the Watchdog Timeout

Set the environment variables DEPTHAI_WATCHDOG_INITIAL_DELAY and DEPTHAI_BOOTUP_TIMEOUT to your desired timeout values (in milliseconds) as follows:

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

For Windows PowerShell, set the environment variables like this:

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

In Windows CMD, you can set the environment variables as follows:

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

Alternatively, you can set the timeout directly in your code:

pipeline = depthai.Pipeline()

# Create a BoardConfig object
config = depthai.BoardConfig()

# Set the parameters
config.watchdogInitialDelayMs = <my_value>
config.watchdogTimeoutMs = <my_value>

pipeline.setBoardConfig(config)

By adjusting these settings, you can tailor the watchdog functionality to better suit your specific requirements.

Environment Variables

The following table lists various environment variables used in the system, along with their descriptions:

Environment Variable

Description

DEPTHAI_LEVEL

Sets logging verbosity, options: ‘trace’, ‘debug’, ‘warn’, ‘error’, ‘off’

XLINK_LEVEL

Sets logging verbosity of XLink library, options: ‘debug’, ‘info’, ‘warn’, ‘error’, ‘fatal’, ‘off’

DEPTHAI_INSTALL_SIGNAL_HANDLER

Set to 0 to disable installing Backward signal handler for stack trace printing

DEPTHAI_WATCHDOG

Sets device watchdog timeout. Useful for debugging (DEPTHAI_WATCHDOG=0), to prevent device reset while the process is paused.

DEPTHAI_WATCHDOG_INITIAL_DELAY

Specifies delay after which the device watchdog starts.

DEPTHAI_SEARCH_TIMEOUT

Specifies timeout in milliseconds for device searching in blocking functions.

DEPTHAI_CONNECT_TIMEOUT

Specifies timeout in milliseconds for establishing a connection to a given device.

DEPTHAI_BOOTUP_TIMEOUT

Specifies timeout in milliseconds for waiting the device to boot after sending the binary.

DEPTHAI_PROTOCOL

Restricts default search to the specified protocol. Options: any, usb, tcpip.

DEPTHAI_DEVICE_MXID_LIST

Restricts default search to the specified MXIDs. Accepts comma separated list of MXIDs. Lists filter results in an “AND” manner and not “OR”

DEPTHAI_DEVICE_ID_LIST

Alias to MXID list. Lists filter results in an “AND” manner and not “OR”

DEPTHAI_DEVICE_NAME_LIST

Restricts default search to the specified NAMEs. Accepts comma separated list of NAMEs. Lists filter results in an “AND” manner and not “OR”

DEPTHAI_DEVICE_BINARY

Overrides device Firmware binary. Mostly for internal debugging purposes.

DEPTHAI_BOOTLOADER_BINARY_USB

Overrides device USB Bootloader binary. Mostly for internal debugging purposes.

DEPTHAI_BOOTLOADER_BINARY_ETH

Overrides device Network Bootloader binary. Mostly for internal debugging purposes.

Reference

class depthai.Device

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

class Config

Device specific configuration

addLogCallback(self: depthai.DeviceBase, callback: Callable[[depthai.LogMessage], None])int

Add a callback for device logging. The callback will be called from a separate thread with the LogMessage being passed.

Parameter callback:

Callback to call whenever a log message arrives

Returns

Id which can be used to later remove the callback

close(self: depthai.DeviceBase)None

Closes the connection to device. Better alternative is the usage of context manager: with depthai.Device(pipeline) as device:

factoryResetCalibration(self: depthai.DeviceBase)None

Factory reset EEPROM data if factory backup is available.

Throws:

std::runtime_exception If factory reset was unsuccessful

flashCalibration(self: depthai.DeviceBase, calibrationDataHandler: depthai.CalibrationHandler)bool

Stores the Calibration and Device information to the Device EEPROM

Parameter calibrationObj:

CalibrationHandler object which is loaded with calibration information.

Returns

true on successful flash, false on failure

flashCalibration2(self: depthai.DeviceBase, arg0: depthai.CalibrationHandler)None

Stores the Calibration and Device information to the Device EEPROM

Throws:

std::runtime_exception if failed to flash the calibration

Parameter calibrationObj:

CalibrationHandler object which is loaded with calibration information.

flashEepromClear(self: depthai.DeviceBase)None

Destructive action, deletes User area EEPROM contents Requires PROTECTED permissions

Throws:

std::runtime_exception if failed to flash the calibration

Returns

True on successful flash, false on failure

flashFactoryCalibration(self: depthai.DeviceBase, arg0: depthai.CalibrationHandler)None

Stores the Calibration and Device information to the Device EEPROM in Factory area To perform this action, correct env variable must be set

Throws:

std::runtime_exception if failed to flash the calibration

Returns

True on successful flash, false on failure

flashFactoryEepromClear(self: depthai.DeviceBase)None

Destructive action, deletes Factory area EEPROM contents Requires FACTORY PROTECTED permissions

Throws:

std::runtime_exception if failed to flash the calibration

Returns

True on successful flash, false on failure

static getAllAvailableDevices() → List[depthai.DeviceInfo]

Returns all available devices

Returns

Vector of available devices

static getAllConnectedDevices() → List[depthai.DeviceInfo]

Returns information of all connected devices. The devices could be both connectable as well as already connected to devices.

Returns

Vector of connected device information

static getAnyAvailableDevice(*args, **kwargs)

Overloaded function.

  1. getAnyAvailableDevice(timeout: datetime.timedelta) -> Tuple[bool, depthai.DeviceInfo]

Waits for any available device with a timeout

Parameter timeout:

duration of time to wait for the any device

Returns

Tuple of bool and DeviceInfo. Bool specifies if device was found. DeviceInfo specifies the found device

  1. getAnyAvailableDevice() -> Tuple[bool, depthai.DeviceInfo]

Gets any available device

Returns

Tuple of bool and DeviceInfo. Bool specifies if device was found. DeviceInfo specifies the found device

getAvailableStereoPairs(self: depthai.DeviceBase) → List[depthai.StereoPair]

Get stereo pairs taking into account the calibration and connected cameras.

@note This method will always return a subset of getStereoPairs.

Returns

Vector of stereo pairs

getBootloaderVersion(self: depthai.DeviceBase) → Optional[depthai.Version]

Gets Bootloader version if it was booted through Bootloader

Returns

DeviceBootloader::Version if booted through Bootloader or none otherwise

getCameraSensorNames(self: depthai.DeviceBase) → Dict[depthai.CameraBoardSocket, str]

Get sensor names for cameras that are connected to the device

Returns

Map/dictionary with camera sensor names, indexed by socket

getChipTemperature(self: depthai.DeviceBase)depthai.ChipTemperature

Retrieves current chip temperature as measured by device

Returns

Temperature of various onboard sensors

getCmxMemoryUsage(self: depthai.DeviceBase)depthai.MemoryInfo

Retrieves current CMX memory information from device

Returns

Used, remaining and total cmx memory

getConnectedCameraFeatures(self: depthai.DeviceBase) → List[depthai.CameraFeatures]

Get cameras that are connected to the device with their features/properties

Returns

Vector of connected camera features

getConnectedCameras(self: depthai.DeviceBase) → List[depthai.CameraBoardSocket]

Get cameras that are connected to the device

Returns

Vector of connected cameras

getConnectedIMU(self: depthai.DeviceBase)str

Get connected IMU type

Returns

IMU type

getConnectionInterfaces(self: depthai.DeviceBase) → List[depthai.connectionInterface]

Get connection interfaces for device

Returns

Vector of connection type

getCrashDump(self: depthai.DeviceBase, clearCrashDump: bool = True)depthai.CrashDump

Retrieves crash dump for debugging.

getDdrMemoryUsage(self: depthai.DeviceBase)depthai.MemoryInfo

Retrieves current DDR memory information from device

Returns

Used, remaining and total ddr memory

static getDeviceByMxId(mxId: str) → Tuple[bool, depthai.DeviceInfo]

Finds a device by MX ID. Example: 14442C10D13EABCE00

Parameter mxId:

MyraidX ID which uniquely specifies a device

Returns

Tuple of bool and DeviceInfo. Bool specifies if device was found. DeviceInfo specifies the found device

getDeviceInfo(self: depthai.DeviceBase)depthai.DeviceInfo

Get the Device Info object o the device which is currently running

Returns

DeviceInfo of the current device in execution

getDeviceName(self: depthai.DeviceBase)object

Get device name if available

Returns

device name or empty string if not available

static getEmbeddedDeviceBinary(*args, **kwargs)

Overloaded function.

  1. getEmbeddedDeviceBinary(usb2Mode: bool, version: depthai.OpenVINO.Version = <Version.???: 7>) -> List[int]

Gets device firmware binary for a specific OpenVINO version

Parameter usb2Mode:

USB2 mode firmware

Parameter version:

Version of OpenVINO which firmware will support

Returns

Firmware binary

  1. getEmbeddedDeviceBinary(config: depthai.Device.Config) -> List[int]

Gets device firmware binary for a specific configuration

Parameter config:

FW with applied configuration

Returns

Firmware binary

getEmbeddedIMUFirmwareVersion(self: depthai.DeviceBase)depthai.Version

Get embedded IMU firmware version to which IMU can be upgraded

Returns

Get embedded IMU firmware version to which IMU can be upgraded.

static getFirstAvailableDevice(skipInvalidDevices: bool = True) → Tuple[bool, depthai.DeviceInfo]

Gets first available device. Device can be either in XLINK_UNBOOTED or XLINK_BOOTLOADER state

Returns

Tuple of bool and DeviceInfo. Bool specifies if device was found. DeviceInfo specifies the found device

static getGlobalProfilingData()depthai.ProfilingData

Get current global accumulated profiling data

Returns

ProfilingData from all devices

getIMUFirmwareUpdateStatus(self: depthai.DeviceBase) → Tuple[bool, float]

Get IMU firmware update status

Returns

Whether IMU firmware update is done and last firmware update progress as percentage. return value true and 100 means that the update was successful return value true and other than 100 means that the update failed

getIMUFirmwareVersion(self: depthai.DeviceBase)depthai.Version

Get connected IMU firmware version

Returns

IMU firmware version

getInputQueue(*args, **kwargs)

Overloaded function.

  1. getInputQueue(self: depthai.Device, name: str) -> depthai.DataInputQueue

Gets an input queue corresponding to stream name. If it doesn’t exist it throws

Parameter name:

Queue/stream name, set in XLinkIn node

Returns

Smart pointer to DataInputQueue

  1. getInputQueue(self: depthai.Device, name: str, maxSize: int, blocking: bool = True) -> depthai.DataInputQueue

Gets an input queue corresponding to stream name. If it doesn’t exist it throws. Also sets queue options

Parameter name:

Queue/stream name, set in XLinkOut node

Parameter maxSize:

Maximum number of messages in queue

Parameter blocking:

Queue behavior once full. True: blocking, false: overwriting of oldest messages. Default: true

Returns

Smart pointer to DataInputQueue

getInputQueueNames(self: depthai.Device) → List[str]

Get all available input queue names

Returns

Vector of input queue names

getIrDrivers(self: depthai.DeviceBase) → List[Tuple[str, int, int]]

Retrieves detected IR laser/LED drivers.

Returns

driver name, I2C bus, I2C address. For OAK-D- Pro it should be [{“LM3644”, 2, 0x63}]

Return type

Vector of tuples containing

getLeonCssCpuUsage(self: depthai.DeviceBase)depthai.CpuUsage

Retrieves average CSS Leon CPU usage

Returns

Average CPU usage and sampling duration

getLeonCssHeapUsage(self: depthai.DeviceBase)depthai.MemoryInfo

Retrieves current CSS Leon CPU heap information from device

Returns

Used, remaining and total heap memory

getLeonMssCpuUsage(self: depthai.DeviceBase)depthai.CpuUsage

Retrieves average MSS Leon CPU usage

Returns

Average CPU usage and sampling duration

getLeonMssHeapUsage(self: depthai.DeviceBase)depthai.MemoryInfo

Retrieves current MSS Leon CPU heap information from device

Returns

Used, remaining and total heap memory

getLogLevel(self: depthai.DeviceBase)depthai.LogLevel

Gets current logging severity level of the device.

Returns

Logging severity level

getLogOutputLevel(self: depthai.DeviceBase)depthai.LogLevel

Gets logging level which decides printing level to standard output.

Returns

Standard output printing severity

getMxId(self: depthai.DeviceBase)str

Get MxId of device

Returns

MxId of connected device

getOutputQueue(*args, **kwargs)

Overloaded function.

  1. getOutputQueue(self: depthai.Device, name: str) -> depthai.DataOutputQueue

Gets an output queue corresponding to stream name. If it doesn’t exist it throws

Parameter name:

Queue/stream name, created by XLinkOut node

Returns

Smart pointer to DataOutputQueue

  1. getOutputQueue(self: depthai.Device, name: str, maxSize: int, blocking: bool = True) -> depthai.DataOutputQueue

Gets a queue corresponding to stream name, if it exists, otherwise it throws. Also sets queue options

Parameter name:

Queue/stream name, set in XLinkOut node

Parameter maxSize:

Maximum number of messages in queue

Parameter blocking:

Queue behavior once full. True specifies blocking and false overwriting of oldest messages. Default: true

Returns

Smart pointer to DataOutputQueue

getOutputQueueNames(self: depthai.Device) → List[str]

Get all available output queue names

Returns

Vector of output queue names

getProductName(self: depthai.DeviceBase)object

Get product name if available

Returns

product name or empty string if not available

getProfilingData(self: depthai.DeviceBase)depthai.ProfilingData

Get current accumulated profiling data

Returns

ProfilingData from the specific device

getQueueEvent(*args, **kwargs)

Overloaded function.

  1. getQueueEvent(self: depthai.Device, queueNames: List[str], timeout: datetime.timedelta = datetime.timedelta(days=-1, seconds=86399, microseconds=999999)) -> str

Gets or waits until any of specified queues has received a message

Parameter queueNames:

Names of queues for which to wait for

Parameter timeout:

Timeout after which return regardless. If negative then wait is indefinite. Default is -1

Returns

Queue name which received a message first

  1. getQueueEvent(self: depthai.Device, queueName: str, timeout: datetime.timedelta = datetime.timedelta(days=-1, seconds=86399, microseconds=999999)) -> str

Gets or waits until specified queue has received a message

Parameter queueNames:

Name of queues for which to wait for

Parameter timeout:

Timeout after which return regardless. If negative then wait is indefinite. Default is -1

Returns

Queue name which received a message

  1. getQueueEvent(self: depthai.Device, timeout: datetime.timedelta = datetime.timedelta(days=-1, seconds=86399, microseconds=999999)) -> str

Gets or waits until any queue has received a message

Parameter timeout:

Timeout after which return regardless. If negative then wait is indefinite. Default is -1

Returns

Queue name which received a message

getQueueEvents(*args, **kwargs)

Overloaded function.

  1. getQueueEvents(self: depthai.Device, queueNames: List[str], maxNumEvents: int = 18446744073709551615, timeout: datetime.timedelta = datetime.timedelta(days=-1, seconds=86399, microseconds=999999)) -> List[str]

Gets or waits until any of specified queues has received a message

Parameter queueNames:

Names of queues for which to block

Parameter maxNumEvents:

Maximum number of events to remove from queue - Default is unlimited

Parameter timeout:

Timeout after which return regardless. If negative then wait is indefinite - Default is -1

Returns

Names of queues which received messages first

  1. getQueueEvents(self: depthai.Device, queueName: str, maxNumEvents: int = 18446744073709551615, timeout: datetime.timedelta = datetime.timedelta(days=-1, seconds=86399, microseconds=999999)) -> List[str]

Gets or waits until specified queue has received a message

Parameter queueName:

Name of queues for which to wait for

Parameter maxNumEvents:

Maximum number of events to remove from queue. Default is unlimited

Parameter timeout:

Timeout after which return regardless. If negative then wait is indefinite. Default is -1

Returns

Names of queues which received messages first

  1. getQueueEvents(self: depthai.Device, maxNumEvents: int = 18446744073709551615, timeout: datetime.timedelta = datetime.timedelta(days=-1, seconds=86399, microseconds=999999)) -> List[str]

Gets or waits until any queue has received a message

Parameter maxNumEvents:

Maximum number of events to remove from queue. Default is unlimited

Parameter timeout:

Timeout after which return regardless. If negative then wait is indefinite. Default is -1

Returns

Names of queues which received messages first

getStereoPairs(self: depthai.DeviceBase) → List[depthai.StereoPair]

Get stereo pairs based on the device type.

Returns

Vector of stereo pairs

getSystemInformationLoggingRate(self: depthai.DeviceBase)float

Gets current rate of system information logging (“info” severity) in Hz.

Returns

Logging rate in Hz

getUsbSpeed(self: depthai.DeviceBase)depthai.UsbSpeed

Retrieves USB connection speed

Returns

USB connection speed of connected device if applicable. Unknown otherwise.

getXLinkChunkSize(self: depthai.DeviceBase)int

Gets current XLink chunk size.

Returns

XLink chunk size in bytes

hasCrashDump(self: depthai.DeviceBase)bool

Retrieves whether the is crash dump stored on device or not.

isClosed(self: depthai.DeviceBase)bool

Is the device already closed (or disconnected)

Warning

This function is thread-unsafe and may return outdated incorrect values. It is only meant for use in simple single-threaded code. Well written code should handle exceptions when calling any DepthAI apis to handle hardware events and multithreaded use.

isEepromAvailable(self: depthai.DeviceBase)bool

Check if EEPROM is available

Returns

True if EEPROM is present on board, false otherwise

isPipelineRunning(self: depthai.DeviceBase)bool

Checks if devices pipeline is already running

Returns

True if running, false otherwise

readCalibration(self: depthai.DeviceBase)depthai.CalibrationHandler

Fetches the EEPROM data from the device and loads it into CalibrationHandler object If no calibration is flashed, it returns default

Returns

The CalibrationHandler object containing the calibration currently flashed on device EEPROM

readCalibration2(self: depthai.DeviceBase)depthai.CalibrationHandler

Fetches the EEPROM data from the device and loads it into CalibrationHandler object

Throws:

std::runtime_exception if no calibration is flashed

Returns

The CalibrationHandler object containing the calibration currently flashed on device EEPROM

readCalibrationOrDefault(self: depthai.DeviceBase)depthai.CalibrationHandler

Fetches the EEPROM data from the device and loads it into CalibrationHandler object If no calibration is flashed, it returns default

Returns

The CalibrationHandler object containing the calibration currently flashed on device EEPROM

readCalibrationRaw(self: depthai.DeviceBase) → List[int]

Fetches the raw EEPROM data from User area

Throws:

std::runtime_exception if any error occurred

Returns

Binary dump of User area EEPROM data

readFactoryCalibration(self: depthai.DeviceBase)depthai.CalibrationHandler

Fetches the EEPROM data from Factory area and loads it into CalibrationHandler object

Throws:

std::runtime_exception if no calibration is flashed

Returns

The CalibrationHandler object containing the calibration currently flashed on device EEPROM in Factory Area

readFactoryCalibrationOrDefault(self: depthai.DeviceBase)depthai.CalibrationHandler

Fetches the EEPROM data from Factory area and loads it into CalibrationHandler object If no calibration is flashed, it returns default

Returns

The CalibrationHandler object containing the calibration currently flashed on device EEPROM in Factory Area

readFactoryCalibrationRaw(self: depthai.DeviceBase) → List[int]

Fetches the raw EEPROM data from Factory area

Throws:

std::runtime_exception if any error occurred

Returns

Binary dump of Factory area EEPROM data

removeLogCallback(self: depthai.DeviceBase, callbackId: int)bool

Removes a callback

Parameter callbackId:

Id of callback to be removed

Returns

True if callback was removed, false otherwise

setIrFloodLightBrightness(self: depthai.DeviceBase, mA: float, mask: int = - 1)bool

Sets the brightness of the IR Flood Light. Limits: up to 1500mA at 30% duty cycle. The duty cycle is controlled by the left camera STROBE, aligned to start of exposure. If the dot projector is also enabled, its lower duty cycle limits take precedence. The emitter is turned off by default

Parameter mA:

Current in mA that will determine brightness, 0 or negative to turn off

Parameter mask:

Optional mask to modify only Left (0x1) or Right (0x2) sides on OAK-D-Pro-W- DEV

Returns

True on success, false if not found or other failure

setIrFloodLightIntensity(self: depthai.DeviceBase, intensity: float, mask: int = - 1)bool

Sets the intensity of the IR Flood Light. Limits: Intensity is directly normalized to 0 - 1500mA current. The duty cycle is 30% when exposure time is longer than 30% frame time. Otherwise, duty cycle is 100% of exposure time. The duty cycle is controlled by the left camera STROBE, aligned to start of exposure. The emitter is turned off by default

Parameter intensity:

Intensity on range 0 to 1, that will determine brightness, 0 or negative to turn off

Parameter mask:

Optional mask to modify only Left (0x1) or Right (0x2) sides on OAK-D-Pro-W- DEV

Returns

True on success, false if not found or other failure

setIrLaserDotProjectorBrightness(self: depthai.DeviceBase, mA: float, mask: int = - 1)bool

Sets the brightness of the IR Laser Dot Projector. Limits: up to 765mA at 30% duty cycle, up to 1200mA at 6% duty cycle. The duty cycle is controlled by left camera STROBE, aligned to start of exposure. The emitter is turned off by default

Parameter mA:

Current in mA that will determine brightness, 0 or negative to turn off

Parameter mask:

Optional mask to modify only Left (0x1) or Right (0x2) sides on OAK-D-Pro-W- DEV

Returns

True on success, false if not found or other failure

setIrLaserDotProjectorIntensity(self: depthai.DeviceBase, intensity: float, mask: int = - 1)bool

Sets the intensity of the IR Laser Dot Projector. Limits: up to 765mA at 30% frame time duty cycle when exposure time is longer than 30% frame time. Otherwise, duty cycle is 100% of exposure time, with current increased up to max 1200mA to make up for shorter duty cycle. The duty cycle is controlled by left camera STROBE, aligned to start of exposure. The emitter is turned off by default

Parameter intensity:

Intensity on range 0 to 1, that will determine brightness. 0 or negative to turn off

Parameter mask:

Optional mask to modify only Left (0x1) or Right (0x2) sides on OAK-D-Pro-W- DEV

Returns

True on success, false if not found or other failure

setLogLevel(self: depthai.DeviceBase, level: depthai.LogLevel)None

Sets the devices logging severity level. This level affects which logs are transferred from device to host.

Parameter level:

Logging severity

setLogOutputLevel(self: depthai.DeviceBase, level: depthai.LogLevel)None

Sets logging level which decides printing level to standard output. If lower than setLogLevel, no messages will be printed

Parameter level:

Standard output printing severity

setSystemInformationLoggingRate(self: depthai.DeviceBase, rateHz: float)None

Sets rate of system information logging (“info” severity). Default 1Hz If parameter is less or equal to zero, then system information logging will be disabled

Parameter rateHz:

Logging rate in Hz

setTimesync(*args, **kwargs)

Overloaded function.

  1. setTimesync(self: depthai.DeviceBase, arg0: datetime.timedelta, arg1: int, arg2: bool) -> None

Configures Timesync service on device. It keeps host and device clocks in sync First time timesync is started it waits until the initial sync is completed Afterwards the function changes the following parameters

Parameter period:

Interval between timesync runs

Parameter numSamples:

Number of timesync samples per run which are used to compute a better value. Set to zero to disable timesync

Parameter random:

If true partial timesync requests will be performed at random intervals, otherwise at fixed intervals

  1. setTimesync(self: depthai.DeviceBase, enable: bool) -> None

Enables or disables Timesync service on device. It keeps host and device clocks in sync.

Parameter enable:

Enables or disables consistent timesyncing

setXLinkChunkSize(self: depthai.DeviceBase, sizeBytes: int)None

Sets the chunk size for splitting device-sent XLink packets. A larger value could increase performance, and 0 disables chunking. A negative value is ignored. Device defaults are configured per protocol, currently 64*1024 for both USB and Ethernet.

Parameter sizeBytes:

XLink chunk size in bytes

startIMUFirmwareUpdate(self: depthai.DeviceBase, forceUpdate: bool = False)bool

Starts IMU firmware update asynchronously only if IMU node is not running. If current firmware version is the same as embedded firmware version then it’s no- op. Can be overridden by forceUpdate parameter. State of firmware update can be monitored using getIMUFirmwareUpdateStatus API.

Parameter forceUpdate:

Force firmware update or not. Will perform FW update regardless of current version and embedded firmware version.

Returns

Returns whether firmware update can be started. Returns false if IMU node is started.

startPipeline(*args, **kwargs)

Overloaded function.

  1. startPipeline(self: depthai.DeviceBase) -> None

Starts the execution of the devices pipeline

Returns

True if pipeline started, false otherwise

  1. startPipeline(self: depthai.DeviceBase, arg0: depthai.Pipeline) -> bool

Starts the execution of a given pipeline

Parameter pipeline:

OpenVINO version of the pipeline must match the one which the device was booted with.

Returns

True if pipeline started, false otherwise

class dai::Device : public dai::DeviceBase

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

Public Functions

Device(const Pipeline &pipeline)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • pipeline: Pipeline to be executed on the device

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
Device(const Pipeline &pipeline, T usb2Mode)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • pipeline: Pipeline to be executed on the device

  • usb2Mode: (bool) Boot device using USB2 mode firmware

Device(const Pipeline &pipeline, UsbSpeed maxUsbSpeed)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • pipeline: Pipeline to be executed on the device

  • maxUsbSpeed: Maximum allowed USB speed

Device(const Pipeline &pipeline, const dai::Path &pathToCmd)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • pipeline: Pipeline to be executed on the device

  • pathToCmd: Path to custom device firmware

Device(const Pipeline &pipeline, const DeviceInfo &devInfo)

Connects to device specified by devInfo.

Parameters
  • pipeline: Pipeline to be executed on the device

  • devInfo: DeviceInfo which specifies which device to connect to

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
Device(const Pipeline &pipeline, const DeviceInfo &devInfo, T usb2Mode)

Connects to device specified by devInfo.

Parameters
  • pipeline: Pipeline to be executed on the device

  • devInfo: DeviceInfo which specifies which device to connect to

  • usb2Mode: (bool) Boot device using USB2 mode firmware

Device(const Pipeline &pipeline, const DeviceInfo &devInfo, UsbSpeed maxUsbSpeed)

Connects to device specified by devInfo.

Parameters
  • pipeline: Pipeline to be executed on the device

  • devInfo: DeviceInfo which specifies which device to connect to

  • maxUsbSpeed: Maximum allowed USB speed

Device(const Pipeline &pipeline, const DeviceInfo &devInfo, const dai::Path &pathToCmd)

Connects to device specified by devInfo.

Parameters
  • pipeline: Pipeline to be executed on the device

  • devInfo: DeviceInfo which specifies which device to connect to

  • pathToCmd: Path to custom device firmware

Device()

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

~Device() override

dtor to close the device

std::shared_ptr<DataOutputQueue> getOutputQueue(const std::string &name)

Gets an output queue corresponding to stream name. If it doesn’t exist it throws

Return

Smart pointer to DataOutputQueue

Parameters
  • name: Queue/stream name, created by XLinkOut node

std::shared_ptr<DataOutputQueue> getOutputQueue(const std::string &name, unsigned int maxSize, bool blocking = true)

Gets a queue corresponding to stream name, if it exists, otherwise it throws. Also sets queue options

Return

Smart pointer to DataOutputQueue

Parameters
  • name: Queue/stream name, set in XLinkOut node

  • maxSize: Maximum number of messages in queue

  • blocking: Queue behavior once full. True specifies blocking and false overwriting of oldest messages. Default: true

std::vector<std::string> getOutputQueueNames() const

Get all available output queue names

Return

Vector of output queue names

std::shared_ptr<DataInputQueue> getInputQueue(const std::string &name)

Gets an input queue corresponding to stream name. If it doesn’t exist it throws

Return

Smart pointer to DataInputQueue

Parameters
  • name: Queue/stream name, set in XLinkIn node

std::shared_ptr<DataInputQueue> getInputQueue(const std::string &name, unsigned int maxSize, bool blocking = true)

Gets an input queue corresponding to stream name. If it doesn’t exist it throws. Also sets queue options

Return

Smart pointer to DataInputQueue

Parameters
  • name: Queue/stream name, set in XLinkOut node

  • maxSize: Maximum number of messages in queue

  • blocking: Queue behavior once full. True: blocking, false: overwriting of oldest messages. Default: true

std::vector<std::string> getInputQueueNames() const

Get all available input queue names

Return

Vector of input queue names

std::vector<std::string> getQueueEvents(const std::vector<std::string> &queueNames, std::size_t maxNumEvents = std::numeric_limits<std::size_t>::max(), std::chrono::microseconds timeout = std::chrono::microseconds(-1))

Gets or waits until any of specified queues has received a message

Return

Names of queues which received messages first

Parameters
  • queueNames: Names of queues for which to block

  • maxNumEvents: Maximum number of events to remove from queue - Default is unlimited

  • timeout: Timeout after which return regardless. If negative then wait is indefinite - Default is -1

std::vector<std::string> getQueueEvents(const std::initializer_list<std::string> &queueNames, std::size_t maxNumEvents = std::numeric_limits<std::size_t>::max(), std::chrono::microseconds timeout = std::chrono::microseconds(-1))
std::vector<std::string> getQueueEvents(std::string queueName, std::size_t maxNumEvents = std::numeric_limits<std::size_t>::max(), std::chrono::microseconds timeout = std::chrono::microseconds(-1))

Gets or waits until specified queue has received a message

Return

Names of queues which received messages first

Parameters
  • queueName: Name of queues for which to wait for

  • maxNumEvents: Maximum number of events to remove from queue. Default is unlimited

  • timeout: Timeout after which return regardless. If negative then wait is indefinite. Default is -1

std::vector<std::string> getQueueEvents(std::size_t maxNumEvents = std::numeric_limits<std::size_t>::max(), std::chrono::microseconds timeout = std::chrono::microseconds(-1))

Gets or waits until any queue has received a message

Return

Names of queues which received messages first

Parameters
  • maxNumEvents: Maximum number of events to remove from queue. Default is unlimited

  • timeout: Timeout after which return regardless. If negative then wait is indefinite. Default is -1

std::string getQueueEvent(const std::vector<std::string> &queueNames, std::chrono::microseconds timeout = std::chrono::microseconds(-1))

Gets or waits until any of specified queues has received a message

Return

Queue name which received a message first

Parameters
  • queueNames: Names of queues for which to wait for

  • timeout: Timeout after which return regardless. If negative then wait is indefinite. Default is -1

std::string getQueueEvent(const std::initializer_list<std::string> &queueNames, std::chrono::microseconds timeout = std::chrono::microseconds(-1))
std::string getQueueEvent(std::string queueName, std::chrono::microseconds timeout = std::chrono::microseconds(-1))

Gets or waits until specified queue has received a message

Return

Queue name which received a message

Parameters
  • queueNames: Name of queues for which to wait for

  • timeout: Timeout after which return regardless. If negative then wait is indefinite. Default is -1

std::string getQueueEvent(std::chrono::microseconds timeout = std::chrono::microseconds(-1))

Gets or waits until any queue has received a message

Return

Queue name which received a message

Parameters
  • timeout: Timeout after which return regardless. If negative then wait is indefinite. Default is -1

DeviceBase(const Pipeline &pipeline)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • pipeline: Pipeline to be executed on the device

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
DeviceBase(const Pipeline &pipeline, T usb2Mode)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • pipeline: Pipeline to be executed on the device

  • usb2Mode: Boot device using USB2 mode firmware

DeviceBase(const Pipeline &pipeline, UsbSpeed maxUsbSpeed)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • pipeline: Pipeline to be executed on the device

  • maxUsbSpeed: Maximum allowed USB speed

DeviceBase(const Pipeline &pipeline, const dai::Path &pathToCmd)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • pipeline: Pipeline to be executed on the device

  • pathToCmd: Path to custom device firmware

DeviceBase(const Pipeline &pipeline, const DeviceInfo &devInfo)

Connects to device specified by devInfo.

Parameters
  • pipeline: Pipeline to be executed on the device

  • devInfo: DeviceInfo which specifies which device to connect to

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
DeviceBase(const Pipeline &pipeline, const DeviceInfo &devInfo, T usb2Mode)

Connects to device specified by devInfo.

Parameters
  • pipeline: Pipeline to be executed on the device

  • devInfo: DeviceInfo which specifies which device to connect to

  • usb2Mode: Boot device using USB2 mode firmware

DeviceBase(const Pipeline &pipeline, const DeviceInfo &devInfo, UsbSpeed maxUsbSpeed)

Connects to device specified by devInfo.

Parameters
  • pipeline: Pipeline to be executed on the device

  • devInfo: DeviceInfo which specifies which device to connect to

  • maxUsbSpeed: Maximum allowed USB speed

DeviceBase(const Pipeline &pipeline, const DeviceInfo &devInfo, const dai::Path &pathToCmd)

Connects to device specified by devInfo.

Parameters
  • pipeline: Pipeline to be executed on the device

  • devInfo: DeviceInfo which specifies which device to connect to

  • pathToCmd: Path to custom device firmware

DeviceBase()

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

DeviceBase(OpenVINO::Version version)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • version: OpenVINO version which the device will be booted with.

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
DeviceBase(OpenVINO::Version version, T usb2Mode)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • version: OpenVINO version which the device will be booted with

  • usb2Mode: Boot device using USB2 mode firmware

DeviceBase(OpenVINO::Version version, UsbSpeed maxUsbSpeed)

Connects to device specified by devInfo.

Parameters
  • version: OpenVINO version which the device will be booted with

  • maxUsbSpeed: Maximum allowed USB speed

DeviceBase(OpenVINO::Version version, const dai::Path &pathToCmd)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • version: OpenVINO version which the device will be booted with

  • pathToCmd: Path to custom device firmware

DeviceBase(OpenVINO::Version version, const DeviceInfo &devInfo)

Connects to device specified by devInfo.

Parameters
  • version: OpenVINO version which the device will be booted with

  • devInfo: DeviceInfo which specifies which device to connect to

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
DeviceBase(OpenVINO::Version version, const DeviceInfo &devInfo, T usb2Mode)

Connects to device specified by devInfo.

Parameters
  • version: OpenVINO version which the device will be booted with

  • devInfo: DeviceInfo which specifies which device to connect to

  • usb2Mode: Boot device using USB2 mode firmware

DeviceBase(OpenVINO::Version version, const DeviceInfo &devInfo, UsbSpeed maxUsbSpeed)

Connects to device specified by devInfo.

Parameters
  • version: OpenVINO version which the device will be booted with

  • devInfo: DeviceInfo which specifies which device to connect to

  • maxUsbSpeed: Maximum allowed USB speed

DeviceBase(OpenVINO::Version version, const DeviceInfo &devInfo, const dai::Path &pathToCmd)

Connects to device specified by devInfo.

Parameters
  • version: OpenVINO version which the device will be booted with

  • devInfo: DeviceInfo which specifies which device to connect to

  • pathToCmd: Path to custom device firmware

DeviceBase(Config config)

Connects to any available device with custom config.

Parameters
  • config: Device custom configuration to boot with

DeviceBase(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

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

DeviceBase(const DeviceInfo &devInfo, UsbSpeed maxUsbSpeed)

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

  • maxUsbSpeed: Maximum allowed USB speed

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

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

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
DeviceBase(Config config, T usb2Mode)

Connects to any available device with a DEFAULT_SEARCH_TIME timeout.

Parameters
  • config: Config with which the device will be booted with

  • usb2Mode: Boot device using USB2 mode firmware

DeviceBase(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

DeviceBase(Config config, const dai::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

template<typename T, std::enable_if_t<std::is_same<T, bool>::value, bool> = true>
DeviceBase(Config config, const DeviceInfo &devInfo, T usb2Mode)

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

  • usb2Mode: Boot device using USB2 mode firmware

DeviceBase(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

DeviceBase(Config config, const DeviceInfo &devInfo, const dai::Path &pathToCmd, bool dumpOnly = false)

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

Public Static Attributes

constexpr std::size_t EVENT_QUEUE_MAXIMUM_SIZE = {2048}

Maximum number of elements in event queue.

Private Functions

bool startPipelineImpl(const Pipeline &pipeline) override

Allows the derived classes to handle custom setup for starting the pipeline

See

startPipeline

Note

Remember to call this function in the overload to setup the communication properly

Return

True if pipeline started, false otherwise

Parameters
  • pipeline: OpenVINO version of the pipeline must match the one which the device was booted with

void closeImpl() override

Allows the derived classes to handle custom setup for gracefully stopping the pipeline

Note

Remember to call this function in the overload to setup the communication properly

Private Members

std::unordered_map<std::string, std::shared_ptr<DataOutputQueue>> outputQueueMap
std::unordered_map<std::string, std::shared_ptr<DataInputQueue>> inputQueueMap
std::unordered_map<std::string, DataOutputQueue::CallbackId> callbackIdMap
std::mutex eventMtx
std::condition_variable eventCv
std::deque<std::string> eventQueue

Got questions?

Head over to Discussion Forum for technical support or any other questions you might have.