.. _connect:



Connect to Device
=================

.. code-block::

    connect(self, guid, queue_entries=0, queue_depth=0)
     

**Description**

This method connects to a device using its GUID and sets up the device with the specified queue parameters. It only provides success (0) or failure (1).
If the operation is successful, there will be no exception or `valueerror` raised by the API. An exception is raised in case of failure [return value is None].

    * Possible failures include:
        - Providing an incorrect GUID
        - The MLSoC is not booted
        - The MLSoC PCIe stack is not functioning properly

    * If an `Exception` is raised:
        - Reset the MLSoC target by invoking reset(self, device). This API is a blocking call. Once the function returns, re-enumerate to ensure the GUID is found upon reboot, and retry to connect using the same GUID.
        - If this does not work, then the device has run into an unrecoverable error, and power cycling the machine is the next step.
          

**Parameters**
            
    * `guid(str)`: GUID of the device to connect to.
    * `queue_entries (int, optional)`: The number of queue entries. Default is 0.
    * `queue_depth (int, optional)`: The depth of the queue. Default is 0.
           

**Returns**
    
    * `DevicePointer`: A pointer to the connected device.

          
**Raises**
            
* `ValueError`: If the GUID is None (checks for user input).
* `Exception`: If the inference is not initialized or unable to connect to the device (failure state code: 1).
           

**Usage**

.. code-block::
   :linenos:
   
     device_guid = "1234-5678-90AB-CDEF"
     device_ptr = device_interface.connect(device_guid)