.. _Python APIs: Python API ########## This section describes the methods in our host Python API for a developer to communicate with the SiMa device in PCIe mode, from their x86 machine. .. list-table:: :widths: 30 70 :header-rows: 1 :align: left * - Name - Description * - :ref:`device initialization ` .. code-block:: python __init__(self, dev_name, device_queue, device_timeout) - This method initializes the device interface by setting up the HostHelper instance and enumerating the available devices to retrieve their GUIDs. * - :ref:`device connect ` .. code-block:: connect(self, guid, queue_entries=0, queue_depth=0) - 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). * - :ref:`load model ` .. code-block:: load_model(self, device, in_shape_list, out_shape_list, metadata, model_path=None, model_hdl=None) - This method loads a model onto the connected device from a file path or using a model handle dictionary prepares the input and output tensors and sets up the metadata. * - :ref:`update ` .. code-block:: __update__(self, in_data: Union[np.ndarray, bytes]) - This method copies the provided input data into the input tensor of the device. * - :ref:`get tensor ` .. code-block:: __get_tensor__(self, out_data: Union[np.ndarray, bytes]) - This method copies the output tensor data from the device to the provided output data array. * - :ref:`run inference ` .. code-block:: run_inference(self, model, in_data: Union[np.ndarray, bytes], do_async=False, callback_f=None) - This method runs inference on the input data using the specified model. * - :ref:`unload model ` .. code-block:: unload_model(self, model) - This method unloads the specified model from the device, freeing up resources. * - :ref:`disconnect ` .. code-block:: disconnect(self, device) - This method disconnects from the specified device, closing the connection and releasing resources. * - :ref:`get GUIDs ` .. code-block:: __get_guids__(self) - This method returns a list of IDs for all available PCIe devices connected to the host machine. If the vector size is not the number of cards expected, there is something wrong. Check that the cards are connected properly. * - :ref:`print GUIDs ` .. code-block:: print_guids(self) - This method prints the GUIDs of all available PCIe devices to the console which is a quick way to identify the connected devices on a host system. * - :ref:`reset ` .. code-block:: reset(self, device) - This method resets the specified device. * - :ref:`reset queue ` .. code-block:: reset_queue(self, device) - This method resets the queue of the specified device. * - :ref:`open device ` .. code-block:: open_device(self, device) - This method opens the specified device. **Running an Example Pipeline in PCIe Mode (OpenPose)** Follow the steps in this section to compile a model and run the resulting application on the MLSoC device connected over PCIe. **Pre-requisites** * An Ubuntu 22.04 host computer with four Gen3/4 PCIe slots. * An MLSoC device connected via PCIe. For instructions on Board Bring-up in PCIe Mode, see :ref:`PCIe setup`. * Palette software installed on your host computer. See Palette Software Installation, earlier in this document. * Install the Python library using the package manager. **Step** #. Compile a model using the Palette software's ModelSDK tool and the appropriate calibration dataset. **Error Codes** The SiMa Python API returns four error codes which are listed in the table below. The API also returns a success message which is displayed if the application executes as expected. .. list-table:: :widths: 50 50 :header-rows: 1 * - Code Name - Description * - Success (0) - Indicates success, that is, execution occurred as expected. * - Failure (1) - Indicates failure. * - Invalid Input (2) - Indicates unexpected input. * - Overflow (3) - Indicates memory allocation error. * - Retry (4) - Retry event. In the Python bindings, you will primarily encounter 0, 1, and 2. The Python bindings take care of asserting some of these failures for you. Therefore, the APIs may do one of two tasks when encountering errors: * Raise an exception or value error (may be due to one of the error codes) * Return the result that will contain the error code itself For different APIs, we spell out various corrective methods. Corrective methods may include resetting the corresponding MLSoC device. **Class: intf** The `intf` class provides an interface to interact with PCIe capable devices connected to a supported host machine using SiMa's custom driver. **Attributes** .. list-table:: :widths: 50 50 :header-rows: 1 * - Name - Description * - `dev_name (str)` - This is used to identify and initialize the PCIe device interface with the specified SoC. * - `host_helper (HostHelper)` - This provides lower-level device management and interaction functions. * - `dev_ptr (DevicePointer)` - This is a pointer to the connected device, used to perform operations on the device. * - `guids (list)` - A list of GUIDs for available devices. These specify which SoC to connect to. * - `model_ref (ModelReference)` - A reference to the model context associated with the pipeline (input/output memory sizes/locations, etc). * - `meta_data (list)` - Metadata associated with the device and the loaded model. This data is used for managing and processing inference tasks. .. toctree:: :maxdepth: 2 :hidden: init.rst connect.rst load_model.rst update.rst get_tensor.rst run_inference.rst unload_model.rst disconnect.rst get_guids.rst print_guids.rst reset.rst reset_queue.rst open_device.rst ../../python-autoapi/sima/host/index.rst