usb.core – USB Core

This is a subset of the PyUSB core module.

exception usb.core.USBError

Bases: OSError

Catchall exception for USB related errors.

Initialize self. See help(type(self)) for accurate signature.

exception usb.core.USBTimeoutError

Bases: USBError

Raised when a USB transfer times out.

Initialize self. See help(type(self)) for accurate signature.

usb.core.find(find_all: bool = False, *, idVendor: int | None = None, idProduct: int | None = None) → Device

Find the first device that matches the given requirements or, if find_all is True, return a generator of all matching devices.

Returns None if no device matches.

class usb.core.Device

User code cannot create Device objects. Instead, get them from usb.core.find.

idVendor: int

The USB vendor ID of the device

idProduct: int

The USB product ID of the device

serial_number: str

The USB device’s serial number string.

product: str

The USB device’s product string.

manufacturer: str

The USB device’s manufacturer string.

set_configuration(configuration=1)

Set the active configuration.

The configuration parameter is the bConfigurationValue field of the configuration you want to set as active. If you call this method without parameter, it will use the first configuration found. As a device hardly ever has more than one configuration, calling the method without arguments is enough to get the device ready.

write(endpoint: int, data: circuitpython_typing.ReadableBuffer, timeout: int | None = None) → int

Write data to a specific endpoint on the device.

Parameters:

  • endpoint (int) – the bEndpointAddress you want to communicate with.

  • data (ReadableBuffer) – the data to send

  • timeout (int) – Time to wait specified in milliseconds. (Different from most CircuitPython!)

Returns:

the number of bytes written

read(endpoint: int, size_or_buffer: array.array, timeout: int | None = None) → int

Read data from the endpoint.

Parameters:

  • endpoint (int) – the bEndpointAddress you want to communicate with.

  • size_or_buffer (array.array) – the array to read data into. PyUSB also allows size but CircuitPython only support array to force deliberate memory use.

  • timeout (int) – Time to wait specified in milliseconds. (Different from most CircuitPython!)

Returns:

the number of bytes read

ctrl_transfer(bmRequestType: int, bRequest: int, wValue: int = 0, wIndex: int = 0, data_or_wLength: array.array | None = None, timeout: int | None = None) → int

Do a control transfer on the endpoint 0. The parameters bmRequestType, bRequest, wValue and wIndex are the same of the USB Standard Control Request format.

Control requests may or may not have a data payload to write/read. In cases which it has, the direction bit of the bmRequestType field is used to infer the desired request direction.

For host to device requests (OUT), data_or_wLength parameter is the data payload to send, and it must be a sequence type convertible to an array object. In this case, the return value is the number of bytes written in the data payload.

For device to host requests (IN), data_or_wLength is an array object which the data will be read to, and the return value is the number of bytes read.

is_kernel_driver_active(interface: int) → bool

Determine if CircuitPython is using the interface. If it is, the object will be unable to perform I/O.

Parameters:

interface (int) – the device interface number to check

detach_kernel_driver(interface: int) → None

Stop CircuitPython from using the interface. If successful, you will then be able to perform I/O. CircuitPython will automatically re-start using the interface on reload.

Parameters:

interface (int) – the device interface number to stop CircuitPython on

attach_kernel_driver(interface: int) → None

Allow CircuitPython to use the interface if it wants to.

Parameters:

interface (int) – the device interface number to allow CircuitPython to use