API

Main module for usbreq. You mostly want the methods of USBDevice.

usbreq.find(*args, **kwargs)

Creates a USBDevice using the same logic and arguments as usb.core.find().

class usbreq.USBDevice(dev: Device)

Wrapper for usb.core.Device that adds shortcut and convenience methods.

control_request(*, direction: str | int | USBDirection, req_type: str | int | USBRequestType, recipient: str | int | USBRecipient, request: str | int | USBRequestNumber, value: int = 0, index: int = 0, length: int | None = None, data: bytes | None = None, **kwargs)

Wrapper for usb.core.Device.ctrl_transfer which has shortcut kwargs for convenience.

Parameters:

  • direction (Union[str, int, USBDirection]) – The direction field of bmRequestType. Accepts everything USBDirection.parse() does.

  • req_type (Union[str, int, USBRequestType]) – The type field of bmRequestType. Accepts everything USBRequestType.parse() does.

  • recipient (Union[str, int, USBRecipient]) – The recipient field of bmRequestType. Accepts everything USBRecipient.parse() does.

  • request (Union[str, int, USBRequestNumber]) – The bRequest field of setup data. Accepts everything USBRequestNumber.parse() does. Also passable as bRequest.

  • value (int) – The wValue field of setup data. Specific to the request you’re performing. Also passable as wValue.

  • index (int) – The wIndex field of setup data. Specific to the request you’re performing. Also passable as wIndex.

  • length (Optional[int]) – How many bytes you want to request from the device or send to the device. If specified for OUT requests, your specified data is automatically truncated to this length. If specified for IN requests, this length is sent as part of the USB request. Optional in both cases. If not specified for IN requests, inferred as 0xFF (max length).

  • data (bytes) – The data to send for OUT requests.

get_descriptor(*, type, index=0, langid=None, length=None, req_type='STANDARD', recipient='DEVICE', find_intended=False)

Shortcut for the GET_DESCRIPTOR standard request.

Parameters:

  • type (Union[str, int, USBDescriptorType]) – The type of descriptor to get. Accepts as a string in any case, or a number.

  • index (int) – Which descriptor of that type to get, if applicable.

  • langid (Optional[int]) – Optional language ID for a string descriptor, if applicable.

  • find_intended (bool) – USB does not allow you to individually and directly request interface or endpoint descriptors. Specifying find_intended=True asks this method, instead of making the actual control request that would correspond to the passed arguments, to make the request that includes the descriptor you specified with type and index, and then parse the device-returned data to find that descriptor and return only that instead. This is experimental and may have unexpected results!

Returns:

The bytes of the descriptor.

Return type:

bytes

Raises:

ValueError – if type as a string or number does not describe a known descriptor type

class usbreq.USBDirection(value)

The direction field of bmRequestType.

OUT = 0x00
HOST_TO_DEVICE = 0x00
IN = 0x80
DEVICE_TO_HOST = 0x80
classmethod parse(direction: str | int | USBDirection)

Parses a USB direction from a string or number. Strings are accepted in any case, with underscores, dashes, or even spaces.

Parameters:

direction (Union[str, int, USBDirection]) – A string or integer describing the descriptor type. Valid strings are: "OUT", "IN", "HOST_TO_DEVICE", and "DEVICE_TO_HOST", in any case, and with underscores, dashes, or spaces.

Return type:

USBDirection

class usbreq.USBRequestType(value)

The type field of bmRequestType.

STANDARD = 0x00
CLASS = 0x20
VENDOR = 0x40
RESERVED = 0x60
classmethod parse(req_type: str | int | USBRequestType)

Parses a USB request type from a string or number. Strings are accepted in any case.

Parameters:

req_type (Union[str, int, USBRequestType]) – A string or integer describing the request type. Valid strings are "STANDARD", "CLASS", "VENDOR", and "RESERVED", in any case.

Return type:

USBRequestType

class usbreq.USBRecipient(value)

The recipient field of bmRequestType.

classmethod parse(recipient: str | int | USBRecipient)

Parses a USB recipient from a string or number. Strings are accepted in any case.

Parameters:

recipient (Union[str, int, USBRecipient]) – A string or integer describing the recipient. Valid strings are: "DEVICE", "INTERFACE", "ENDPOINT", "OTHER", and "RESERVED", in any case.

Return type:

USBRecipient

class usbreq.USBRequestNumber(value)

The bRequest field of setup data.

classmethod parse(request: str | int | USBRequestNumber)

Parses a USB request number from a string or number. Strings are accepted in any case, with underscores, dashes, or even spaces.

Parameters:

request (Union[str, int, USBRequestNumber]) – A string or integer describing the request. Valid strings are the enum constants of this class, in any case.

Return type:

USBRequestNumber

class usbreq.USBDescriptorType(value)

Descriptor types valid for USBDevice.get_descriptor().

DEVICE = 0x01
CONFIGURATION = 0x02
STRING = 0x03
INTERFACE = 0x04
ENDPOINT = 0x05
classmethod parse(descriptor_type: str | int | USBDescriptorType)

Parses a descriptor type from a string or number. Strings are accepted in any case.

Parameters:

descriptor_type (Union[str, int, USBDescriptorType]) – A string or integer describing the descriptor type.

Return type:

USBDescriptorType