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]]

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]) – 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]) – output stream, none for stdout

Exceptions

exception pyftdi.usbtools.UsbToolsError

UsbTools error.