CloudSoftwareHardware
Software Stack
DepthAI
OAK Apps
AI Models
Troubleshooting

ON THIS PAGE

  • Device
  • Device API
  • Connect to specified device
  • Clock
  • Host clock syncing
  • Watchdog - RVC2 only
  • 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
1with dai.Pipeline() as pipeline:
2    device = pipeline.getDefaultDevice()
3    # Print DeviceID, USB speed, and available cameras on the device
4    print('DeviceID:',device.getDeviceInfo().getDeviceId())
5    print('USB speed:',device.getUsbSpeed())
6    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 DeviceID, IP, or USB port name) you want to connect to.
Python
1# Specify DeviceID, IP Address or USB path
2device_info = depthai.DeviceInfo("14442C108144F1D000") # DeviceID
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(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.Pipeline() as pipeline:
7    device = pipeline.getDefaultDevice()
8    # 1st value: Interval between timesync runs
9    # 2nd value: Number of timesync samples per run which are used to compute a better value
10    # 3rd value: If true partial timesync requests will be performed at random intervals, otherwise at fixed intervals
11    device.setTimesync(timedelta(seconds=5), 10, True) # (These are default values)

Watchdog - RVC2 only

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', 'info', '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_RECONNECT_TIMEOUTSpecifies timeout in milliseconds for reconnecting to a device after a connection loss. If set to 0, reconnect is disabled.
DEPTHAI_PROTOCOLRestricts default search to the specified protocol. Options: any, usb, tcpip, tcpshd.
DEPTHAI_PLATFORMRestricts default search to the specified platform. Options: any, rvc2, rvc3, rvc4.
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". It also looks for NAMEs outside of the host's subnet in case of tcpip.
DEPTHAI_DEVICE_BINARYOverrides device Firmware binary. Mostly for internal debugging purposes.
DEPTHAI_DEVICE_RVC4_FWPOverrides device RVC4 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_ALLOW_FACTORY_FLASHINGInternal use only
DEPTHAI_LIBUSB_ANDROID_JAVAVMJavaVM pointer that is passed to libusb for rootless Android interaction with devices. Interpreted as decimal value of uintptr_t
DEPTHAI_CRASHDUMPDirectory in which to save the crash dump.
DEPTHAI_CRASHDUMP_TIMEOUTSpecifies the duration in milliseconds to wait for device reboot when obtaining a crash dump. Crash dump retrieval disabled if 0.
DEPTHAI_ENABLE_ANALYTICS_COLLECTIONEnables automatic analytics collection (pipeline schemas) used to improve the library
DEPTHAI_DISABLE_CRASHDUMP_COLLECTIONDisables automatic crash dump collection used to improve the library
DEPTHAI_HUB_EVENTS_BASE_URLURL for events of the Luxonis Hub
DEPTHAI_HUB_API_KEYAPI key for the Luxonis Hub
DEPTHAI_ZOO_INTERNET_CHECK(Default) 1 - perform internet check, if available, download the newest model version; 0 - skip internet check and use cached model
DEPTHAI_ZOO_INTERNET_CHECK_TIMEOUT(Default) 1000 - timeout in milliseconds for the internet check
DEPTHAI_ZOO_CACHE_PATH(Default) .depthai_cached_models - Folder where cached zoo models are stored
DEPTHAI_ZOO_MODELS_PATH(Default) depthai_models - Folder where zoo model description files are stored
DEPTHAI_RECORDEnables holistic record to the specified directory.
DEPTHAI_REPLAYReplays holistic replay from the specified file or directory.
DEPTHAI_PROFILINGEnables runtime profiling of data transfer between the host and connected devices. Set to 1 to enable. Requires DEPTHAI_LEVEL=debug or lower to print.

Reference

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
Platform getPlatform()
function
std::string getPlatformAsString()
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(Config config)
Connects to any available device with custom config.
Parameters
  • config: Device custom configuration to boot with
function
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
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(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(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(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(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