# `usbtools` - USB tools

## Classes

class pyftdi.usbtools.UsbTools

  Helpers to obtain information about connected USB devices.

  classmethod build_dev_strings(scheme, vdict, pdict, devdescs)

    Build URL and device descriptors from UsbDeviceDescriptors.

    Parameters

      - scheme (`str`) – protocol part of the URLs to generate

      - vdict (`Dict`[`str`, `int`]) – vendor name map of USB vendor ids

      - pdict (`Dict`[`int`, `Dict`[`str`, `int`]]) – vendor id map of product name map of product ids

      - devdescs (`Sequence`[`Tuple`[`UsbDeviceDescriptor`, `int`]]) – USB devices and interfaces

    Return type

      `List`[`Tuple`[`str`, `str`]]

    Returns

      list of (url, descriptors)

  classmethod enumerate_candidates(urlparts, vdict, pdict, default_vendor)

    Enumerate USB device URLs that match partial URL and VID/PID criteria.

    Parameters

      - urlpart – splitted device specifier URL

      - vdict (`Dict`[`str`, `int`]) – vendor name map of USB vendor ids

      - pdict (`Dict`[`int`, `Dict`[`str`, `int`]]) – vendor id map of product name map of product ids

      - default_vendor (`int`) – default vendor id

    Return type

      `Tuple`[`List`[`Tuple`[`UsbDeviceDescriptor`, `int`]], `Optional`[`int`, `None`]]

    Returns

      list of (usbdev, iface), parsed index if any

  classmethod find_all(vps, nocache=False)

    Find all devices that match the specified vendor/product pairs.

    Parameters

      - vps (`Sequence`[`Tuple`[`int`, `int`]]) – a sequence of 2-tuple (vid, pid) pairs

      - nocache (bool) – bypass cache to re-enumerate USB devices on the host

    Return type

      `List`[`Tuple`[`UsbDeviceDescriptor`, `int`]]

    Returns

      a list of 2-tuple (UsbDeviceDescriptor, interface count)

  classmethod find_backend()

    Try to find and load an PyUSB backend.

    ..note:: There is no need to call this method for regular usage.

    Return type

      `IBackend`

    Returns

      PyUSB backend

  classmethod flush_cache()

    Flush the FTDI device cache.

    It is highly recommanded to call this method a FTDI device is unplugged/plugged back since the last enumeration, as the device may appear on a different USB location each time it is plugged in.

    Failing to clear out the cache may lead to USB Error 19: `Device may have been disconnected`.

  classmethod get_device(devdesc)

    Find a previously open device with the same vendor/product or initialize a new one, and return it.

    If several FTDI devices of the same kind (vid, pid) are connected to the host, either index or serial argument should be used to discriminate the FTDI device.

    index argument is not a reliable solution as the host may enumerate the USB device in random order. serial argument is more reliable selector and should always be prefered.

    Some FTDI devices support several interfaces/ports (such as FT2232H and FT4232H). The interface argument selects the FTDI port to use, starting from 1 (not 0).

    Parameters

      devdesc (`UsbDeviceDescriptor`) – Device descriptor that identifies the device by constraints.

    Return type

      `Device`

    Returns

      PyUSB device instance

  classmethod get_string(device, stridx)

    Retrieve a string from the USB device, dealing with PyUSB API breaks

    Parameters

      - device (`Device`) – USB device instance

      - stridx (`int`) – the string identifier

    Return type

      `str`

    Returns

      the string read from the USB device

  classmethod list_devices(urlstr, vdict, pdict, default_vendor)

    List candidates that match the device URL pattern.

    See

      `show_devices()` to generate the URLs from the candidates list

    Parameters

      - url – the URL to parse

      - vdict (`Dict`[`str`, `int`]) – vendor name map of USB vendor ids

      - pdict (`Dict`[`int`, `Dict`[`str`, `int`]]) – vendor id map of product name map of product ids

      - default_vendor (`int`) – default vendor id

    Return type

      `List`[`Tuple`[`UsbDeviceDescriptor`, `int`]]

    Returns

      list of (UsbDeviceDescriptor, interface)

  classmethod parse_url(urlstr, scheme, vdict, pdict, default_vendor)

    Parse a device specifier URL.

    Parameters

      - url – the URL to parse

      - scheme (`str`) – scheme to match in the URL string (scheme://…)

      - vdict (`Dict`[`str`, `int`]) – vendor name map of USB vendor ids

      - pdict (`Dict`[`int`, `Dict`[`str`, `int`]]) – vendor id map of product name map of product ids

      - default_vendor (`int`) – default vendor id

    Return type

      `Tuple`[`UsbDeviceDescriptor`, `int`]

    Returns

      UsbDeviceDescriptor, interface

    ..note:

    > URL syntax:

    > > protocol://vendor:product[:serial|:index|:bus:addr]/interface

  classmethod release_all_devices(devclass=None)

    Release all open devices.

    Parameters

      devclass (`Optional`[`Type`, `None`]) – optional class to only release devices of one type

    Return type

      `int`

    Returns

      the count of device that have been released.

  classmethod release_device(usb_dev)

    Release a previously open device, if it not used anymore.

    Parameters

      usb_dev (`Device`) – a previously instanciated USB device instance

  classmethod show_devices(scheme, vdict, pdict, devdescs, out=None)

    Show supported devices. When the joker url `scheme://*/?` is specified as an URL, it generates a list of connected USB devices that match the supported USB devices. It can be used to provide the end-user with a list of valid URL schemes.

    Parameters

      - scheme (`str`) – scheme to match in the URL string (scheme://…)

      - vdict (`Dict`[`str`, `int`]) – vendor name map of USB vendor ids

      - pdict (`Dict`[`int`, `Dict`[`str`, `int`]]) – vendor id map of product name map of product ids

      - devdescs (`Sequence`[`Tuple`[`UsbDeviceDescriptor`, `int`]]) – candidate devices

      - out (`Optional`[`TextIO`, `None`]) – output stream, none for stdout

## Exceptions

exception pyftdi.usbtools.UsbToolsError

  UsbTools error.