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 # ...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 queueOutput queue settings
When the host is reading very fast from the queue (eg. insidewhile 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)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
Deviceobject 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 variablesDEPTHAI_WATCHDOG_INITIAL_DELAY and DEPTHAI_BOOTUP_TIMEOUT to your desired timeout values (in milliseconds) as follows:Linux/macOS
Windows Powershell
Windows CMD
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)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. |
DEPTHAI_ENABLE_FEEDBACK_CRASHDUMP | 1/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
method
method
method
getInputQueueNames(self) -> list[str]: list[str]Get all available input queue names
Returns:
Vector of input queue namesmethod
method
getOutputQueueNames(self) -> list[str]: list[str]Get all available output queue names
Returns:
Vector of output queue namesmethod
method
class
depthai.Device.Config
variable
variable
variable
variable
variable
method