# 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](https://docs.luxonis.com/hardware/platform/rvc/rvc2.md#rvc2)). 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](https://docs.luxonis.com/software/depthai-components/pipeline.md) 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
pipeline = depthai.Pipeline()

# Create nodes, configure them and link them together

# Connect to the device and upload the pipeline to it
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())
```

## Connect to specified device

If you have [multiple devices](https://docs.luxonis.com/software/depthai/multi-device-setup.md) 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
# 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:
    # ...
```

## 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](https://en.cppreference.com/w/cpp/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](https://docs.luxonis.com/software/depthai-components/messages.md) 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](https://shop.luxonis.com/products/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
# 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)
```

## Device queues

After initializing the device, you can create input/output queues that match
[XLinkIn](https://docs.luxonis.com/software/depthai-components/nodes/xlink_in.md)/[XLinkOut](https://docs.luxonis.com/software/depthai-components/nodes/xlink_out.md)
nodes in the pipeline. These queues will be located on the host computer (in RAM).

```py
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 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
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:

#### Windows Powershell

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

#### Linux/macOS

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

#### Windows CMD

```bash
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:

```python
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. |
| `DEPTHAI_DISABLE_CRASHDUMP_COLLECTION` | when set to 1, disable sending of crash dump to Luxonis. By default, the crash dump,
pipeline, OS and depthai version information are sent to Luxonis for diagnostics. |
| `DEPTHAI_ENABLE_ANALYTICS_COLLECTION` | when set to 1, analytic data (pipeline schema) is sent to Luxonis which will be used to
further improve the library. |

## Reference

### depthai.Device(depthai.DeviceBase)

Kind: Class

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

#### depthai.Device.Config

Kind: Class

Device specific configuration

##### board: BoardConfig

Kind: Class Variable

##### logLevel: depthai.LogLevel|None

Kind: Class Variable

##### nonExclusiveMode: bool

Kind: Class Variable

##### outputLogLevel: depthai.LogLevel|None

Kind: Class Variable

##### version: OpenVINO.Version

Kind: Class Variable

##### __init__(self)

Kind: Method

#### __enter__(self) -> Device: Device

Kind: Method

#### __init__()

Kind: Method

#### getInputQueue()

Kind: Method

#### getInputQueueNames(self) -> list[str]: list[str]

Kind: Method

Get all available input queue names

Returns:
Vector of input queue names

#### getOutputQueue()

Kind: Method

#### getOutputQueueNames(self) -> list[str]: list[str]

Kind: Method

Get all available output queue names

Returns:
Vector of output queue names

#### getQueueEvent()

Kind: Method

#### getQueueEvents()

Kind: Method