# 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-v3/depthai/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
with dai.Pipeline() as pipeline:
    device = pipeline.getDefaultDevice()
    # Print DeviceID, USB speed, and available cameras on the device
    print('DeviceID:',device.getDeviceInfo().getDeviceId())
    print('USB speed:',device.getUsbSpeed())
    print('Connected cameras:',device.getConnectedCameras())
```

## Connect to specified device

If you have [multiple devices](https://docs.luxonis.com/software-v3/depthai/tutorials/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 DeviceID,
IP, or USB port name) you want to connect to.

```python
# Specify DeviceID, IP Address or USB path
device_info = depthai.DeviceInfo("14442C108144F1D000") # DeviceID
#device_info = depthai.DeviceInfo("192.168.1.44") # IP Address
#device_info = depthai.DeviceInfo("3.3.3") # USB port name
with depthai.Device(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-v3/depthai/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.Pipeline() as pipeline:
    device = pipeline.getDefaultDevice()
    # 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)
```

## 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:

#### 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', 'info', '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_RECONNECT_TIMEOUT` | Specifies timeout in milliseconds for reconnecting to a device after a connection loss. If set to
0, reconnect is disabled. |
| `DEPTHAI_PROTOCOL` | Restricts default search to the specified protocol. Options: `any`, `usb`, `tcpip`, `tcpshd`. |
| `DEPTHAI_PLATFORM` | Restricts default search to the specified platform. Options: `any`, `rvc2`, `rvc3`, `rvc4`. |
| `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". It also looks for NAMEs outside of the host's subnet in case of tcpip. |
| `DEPTHAI_DEVICE_BINARY` | Overrides device Firmware binary. Mostly for internal debugging purposes. |
| `DEPTHAI_DEVICE_RVC4_FWP` | Overrides device RVC4 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_ALLOW_FACTORY_FLASHING` | Internal use only |
| `DEPTHAI_LIBUSB_ANDROID_JAVAVM` | JavaVM pointer that is passed to libusb for rootless Android interaction with devices.
Interpreted as decimal value of uintptr_t |
| `DEPTHAI_CRASHDUMP` | Directory in which to save the crash dump. |
| `DEPTHAI_CRASHDUMP_TIMEOUT` | Specifies the duration in milliseconds to wait for device reboot when obtaining a crash dump.
Crash dump retrieval disabled if 0. |
| `DEPTHAI_ENABLE_ANALYTICS_COLLECTION` | Enables automatic analytics collection (pipeline schemas) used to improve the library |
| `DEPTHAI_DISABLE_CRASHDUMP_COLLECTION` | Disables automatic crash dump collection used to improve the library |
| `DEPTHAI_HUB_EVENTS_BASE_URL` | URL for events of the Luxonis Hub |
| `DEPTHAI_HUB_API_KEY` | API 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_RECORD` | Enables holistic record to the specified directory. |
| `DEPTHAI_REPLAY` | Replays holistic replay from the specified file or directory. |
| `DEPTHAI_PROFILING` | Enables 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

### dai::Device

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

#### ReconnectionStatus

Kind: enum

#### Device()

Kind: function

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

#### ~Device()

Kind: function

dtor to close the device

#### DeviceBase()

Kind: function

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

#### DeviceBase(UsbSpeed maxUsbSpeed)

Kind: function

Connects to device parameters: maxUsbSpeed: Maximum allowed USB speed

#### DeviceBase(const DeviceInfo & devInfo, UsbSpeed maxUsbSpeed)

Kind: function

Connects to device specified by devInfo. parameters: devInfo: DeviceInfo which specifies which device to connect to; maxUsbSpeed:
Maximum allowed USB speed

#### DeviceBase(const DeviceInfo & devInfo, const std::filesystem::path & pathToCmd)

Kind: function

Connects to device specified by devInfo. parameters: devInfo: DeviceInfo which specifies which device to connect to; pathToCmd:
Path to custom device firmware

#### DeviceBase(Config config)

Kind: function

Connects to any available device with custom config. parameters: config: Device custom configuration to boot with

#### DeviceBase(Config config, const DeviceInfo & devInfo)

Kind: function

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)

Kind: function

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(std::string nameOrDeviceId)

Kind: function

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)

Kind: function

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

#### DeviceBase(Config config, UsbSpeed maxUsbSpeed)

Kind: function

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 std::filesystem::path & pathToCmd)

Kind: function

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

#### DeviceBase(Config config, const DeviceInfo & devInfo, UsbSpeed maxUsbSpeed)

Kind: function

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 std::filesystem::path & pathToCmd, bool dumpOnly)

Kind: function

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