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.

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