The functionality documented in this module is designed to help with the following operations:

• Enumerating the USB devices currently attached to the system.
• Choosing a device to operate from your software.
• Opening and closing the chosen device.

Returns a list of USB devices currently attached to the system.

This is your entry point into finding a USB device to operate.

Exceptions:

• NoMemException on a memory allocation failure.

Convenience function to retrieve the max packet size for a particular endpoint in the active device configuration.

This is useful for setting up isochronous transfers.

Exceptions:

• NotFoundException if the endpoint does not exist.
• OtherException on another exception.

Open a device and obtain a device handle.

A handle allows you to perform I/O on the device in question.

This is a non-blocking function; no requests are sent over the bus.

It is advised to use withDeviceHandle because it automatically closes the device when the computation terminates.

Exceptions:

• NoMemException if there is a memory allocation failure.
• AccessException if the user has insufficient permissions.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Close a device handle.

Should be called on all open handles before your application exits.

This is a non-blocking function; no requests are sent over the bus.

Identifier for configurations.

Can be retrieved by getConfig or by configValue.

Determine the bConfigurationValue of the currently active configuration.

You could formulate your own control request to obtain this information, but this function has the advantage that it may be able to retrieve the information from operating system caches (no I/O involved).

If the OS does not cache this information, then this function will block while a control transfer is submitted to retrieve the information.

This function will return a value of 0 if the device is in unconfigured state.

Exceptions:

• NoDeviceException if the device has been disconnected.
• Aanother USBException.

Set the active configuration for a device.

The operating system may or may not have already set an active configuration on the device. It is up to your application to ensure the correct configuration is selected before you attempt to claim interfaces and perform other operations.

If you call this function on a device already configured with the selected configuration, then this function will act as a lightweight device reset: it will issue a SET_CONFIGURATION request using the current configuration, causing most USB-related device state to be reset (altsetting reset to zero, endpoint halts cleared, toggles reset).

You cannot change/reset configuration if your application has claimed interfaces - you should free them with releaseInterface first. You cannot change/reset configuration if other applications or drivers have claimed interfaces.

A configuration value of -1 will put the device in unconfigured state. The USB specifications state that a configuration value of 0 does this, however buggy devices exist which actually have a configuration 0.

You should always use this function rather than formulating your own SET_CONFIGURATION control request. This is because the underlying operating system needs to know when such changes happen.

This is a blocking function.

Exceptions:

• NotFoundException if the requested configuration does not exist.
• BusyException if interfaces are currently claimed.
• NoDeviceException if the device has been disconnected
• Another USBException.

Identifier for interfaces.

Can be retrieved by interfaceNumber.

Claim an interface on a given device handle.

You must claim the interface you wish to use before you can perform I/O on any of its endpoints.

It is legal to attempt to claim an already-claimed interface, in which case libusb just returns without doing anything.

Claiming of interfaces is a purely logical operation; it does not cause any requests to be sent over the bus. Interface claiming is used to instruct the underlying operating system that your application wishes to take ownership of the interface.

This is a non-blocking function.

It is advised to use withInterface because it automatically releases an interface when the computation terminates.

Exceptions:

• NotFoundException if the requested interface does not exist.
• BusyException if another program or driver has claimed the interface.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Release an interface previously claimed with claimInterface.

You should release all claimed interfaces before closing a device handle.

This is a blocking function. A SET_INTERFACE control request will be sent to the device, resetting interface state to the first alternate setting.

Exceptions:

• NotFoundException if the interface was not claimed.
• NoDeviceException if the device has been disconnected
• Another USBException.

Identifier for interface alternate settings.

Can be retrieved by interfaceAltSetting.

Activate an alternate setting for an interface.

The interface must have been previously claimed with claimInterface or withInterface.

You should always use this function rather than formulating your own SET_INTERFACE control request. This is because the underlying operating system needs to know when such changes happen.

This is a blocking function.

Exceptions:

• NotFoundException if the interface was not claimed or the requested alternate setting does not exist.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Clear the halt/stall condition for an endpoint.

Endpoints with halt status are unable to receive or transmit data until the halt condition is stalled.

You should cancel all pending transfers before attempting to clear the halt condition.

This is a blocking function.

Exceptions:

• NotFoundException if the endpoint does not exist.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Perform a USB port reset to reinitialize a device.

The system will attempt to restore the previous configuration and alternate settings after the reset has completed.

If the reset fails, the descriptors change, or the previous state cannot be restored, the device will appear to be disconnected and reconnected. This means that the device handle is no longer valid (you should close it) and rediscover the device. A NotFoundException is raised to indicate that this is the case.

This is a blocking function which usually incurs a noticeable delay.

Exceptions:

• NotFoundException if re-enumeration is required, or if the device has been disconnected.
• Another USBException.

Determine if a kernel driver is active on an interface.

If a kernel driver is active, you cannot claim the interface, and libusb will be unable to perform I/O.

Exceptions:

• NoDeviceException if the device has been disconnected.
• Another USBException.

Detach a kernel driver from an interface.

If successful, you will then be able to claim the interface and perform I/O.

Exceptions:

• NotFoundException if no kernel driver was active.
• InvalidParamException if the interface does not exist.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Re-attach an interface's kernel driver, which was previously detached using detachKernelDriver.

Exceptions:

• NotFoundException if no kernel driver was active.
• InvalidParamException if the interface does not exist.
• NoDeviceException if the device has been disconnected.
• BusyException if the driver cannot be attached because the interface is claimed by a program or driver.
• Another USBException.

If a kernel driver is active on the specified interface the driver is detached and the given action is executed. If the action terminates, whether by normal termination or by raising an exception, the kernel driver is attached again. If a kernel driver is not active on the specified interface the action is just executed.

Exceptions:

• NoDeviceException if the device has been disconnected.
• Another USBException.