HomeCloudSoftwareHardware
DepthAI Components
DepthAI Tutorials
DepthAI Perception
Tools
ROS
Neural Networks
DepthAI API References

ON THIS PAGE

  • Device
  • Device API
  • Connect to specified device
  • Clock
  • Host clock syncing
  • Device queues
  • Output queue settings
  • Some additional information
  • Watchdog
  • Customizing the Watchdog Timeout
  • Environment Variables
  • Reference

Device

Device class represents a single Luxonis' hardware device (OAK camera or 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).
Python
1pipeline = depthai.Pipeline()
2
3# Create nodes, configure them and link them together
4
5# Connect to the device and upload the pipeline to it
6with depthai.Device(pipeline) as device:
7    # Print MxID, USB speed, and available cameras on the device
8    print('MxId:',device.getDeviceInfo().getMxId())
9    print('USB speed:',device.getUsbSpeed())
10    print('Connected cameras:',device.getConnectedCameras())

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.
Python
1# Specify MXID, IP Address or USB path
2device_info = depthai.DeviceInfo("14442C108144F1D000") # MXID
3#device_info = depthai.DeviceInfo("192.168.1.44") # IP Address
4#device_info = depthai.DeviceInfo("3.3.3") # USB port name
5with depthai.Device(pipeline, device_info) as device:
6    # ...

Clock

The depthai clock dai.Clock.now() (Python) or dai::Clock::now() (C++) is a monotonic clock that is used for timestamps in the depthai library. It is derived from std::chrono::steady_clock and is not affected by system time changes (eg. NTP sync).The method returns datetime.timedelta (Python) or std::chrono::steady_clock::duration (C++) since the host (PC) boot. It is used when calling getTimestamp() on device messages and will indicate the time when the message was created on the device.There is also a separate monotonic clock on the device which is used for retrieving time since device (OAK) boot and can be called using getTimestampDevice().

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).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.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.
Python
1# Configure host clock syncing example
2
3import depthai as dai
4from datetime import timedelta
5# Configure pipeline
6with dai.Device(pipeline) as device:
7    # 1st value: Interval between timesync runs
8    # 2nd value: Number of timesync samples per run which are used to compute a better value
9    # 3rd value: If true partial timesync requests will be performed at random intervals, otherwise at fixed intervals
10    device.setTimesync(timedelta(seconds=5), 10, True) # (These are default values)

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).
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() # Read from the queue, blocks until message arrives
15  outputQueue.tryGet() # Read from the queue, returns None if there's no msg (doesn't block)
16  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 settings

When the host is reading very fast from the queue (eg. 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 host queue faster than the host can read from it. Then the messages in the queue will start to increase - and both maxSize and blocking settings will determine the behavior of the queue in this case. Two common configurations are:
Py
1with dai.Device(pipeline) as device:
2  # If you want only the latest message, and don't care about previous ones;
3  # When a new msg arrives to the host, it will overwrite the previous (oldest) one if it's still in the queue
4  q1 = device.getOutputQueue(name="name1", maxSize=1, blocking=False)
5
6
7  # If you care about every single message (eg. H264/5 encoded video; if you miss a frame, you will get artifacts);
8  # If the queue is full, the device will wait until the host reads a message from the queue
9  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:
Linux/macOS
Windows Powershell
Windows CMD
Alternatively, you can set the timeout directly in your code:
Python
1pipeline = depthai.Pipeline()
2
3# Create a BoardConfig object
4config = depthai.BoardConfig()
5
6# Set the parameters
7config.watchdogInitialDelayMs = <my_value>
8config.watchdogTimeoutMs = <my_value>
9
10pipeline.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 VariableDescription
DEPTHAI_LEVELSets logging verbosity, options: 'trace', 'debug', 'warn', 'error', 'off'
XLINK_LEVELSets logging verbosity of XLink library, options: 'debug', 'info', 'warn', 'error', 'fatal', 'off'
DEPTHAI_INSTALL_SIGNAL_HANDLERSet to 0 to disable installing Backward signal handler for stack trace printing
DEPTHAI_WATCHDOGSets device watchdog timeout. Useful for debugging (DEPTHAI_WATCHDOG=0), to prevent device reset while the process is paused.
DEPTHAI_WATCHDOG_INITIAL_DELAYSpecifies delay after which the device watchdog starts.
DEPTHAI_SEARCH_TIMEOUTSpecifies timeout in milliseconds for device searching in blocking functions.
DEPTHAI_CONNECT_TIMEOUTSpecifies timeout in milliseconds for establishing a connection to a given device.
DEPTHAI_BOOTUP_TIMEOUTSpecifies timeout in milliseconds for waiting the device to boot after sending the binary.
DEPTHAI_PROTOCOLRestricts default search to the specified protocol. Options: any, usb, tcpip.
DEPTHAI_DEVICE_MXID_LISTRestricts 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_LISTAlias to MXID list. Lists filter results in an "AND" manner and not "OR"
DEPTHAI_DEVICE_NAME_LISTRestricts default search to the specified NAMEs. Accepts comma separated list of NAMEs. Lists filter results in an "AND" manner and not "OR"
DEPTHAI_DEVICE_BINARYOverrides device Firmware binary. Mostly for internal debugging purposes.
DEPTHAI_BOOTLOADER_BINARY_USBOverrides device USB Bootloader binary. Mostly for internal debugging purposes.
DEPTHAI_BOOTLOADER_BINARY_ETHOverrides device Network Bootloader binary. Mostly for internal debugging purposes.
DEPTHAI_ENABLE_FEEDBACK_CRASHDUMP1/0 to enable/disable sending of crash dump directly to Luxonis. It sends the dump, pipeline, OS and depthai version information.

Reference

class

depthai.Device(depthai.DeviceBase)

class
Config
Device specific configuration
method
__enter__(self) -> Device: Device
method
__init__
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