USB Host: Unreliable Unplug Event Detection

[samblenny]

There's currently (10.0.0-beta.2) no good way to detect an unplugged USB device using the usb.core.Device API. Unplugging will occasionally raise an immediate usb.core.USBError, but often it just results in a delayed usb.core.USBTimeoutError when you next try to poll the USB device. There's nothing about such USBTimeoutError objects to distinguish them from other timeouts that happen in the normal course of polling some USB devices (e.g. USB receivers for wireless gamepads).

Desktop PyUSB handles unplug events and other error conditions by setting usb.core.USBError.errno and usb.core.USBTimeoutError.errno with values that correlate to different USB bus conditions. CircuitPython's usb.core implementation generally does not set .errno in a useful way, and its exception string descriptions don't provide enough information to identify unplug events.

I'm posting this issue at tannewt's request to split out one of the points I mentioned in USB Host Improvement Quest Umbrella Issue #10551. The point of this issue is to let people know I'm planning to work on this myself and to ask for comments and feedback.

[tannewt]

What are the errno's that pyusb uses?

[samblenny]

What are the errno's that pyusb uses?

This is the script I wrote last year when I was trying out PyUSB on Debian: samblenny/usbgamepad/usbgamepad.py. The start_xpad() and find_and_connect() functions have the interesting try/except blocks. Summary:

• usb.core.USBTimeoutError.errno == 75 during read() is a normal timeout where a retry usually works
• usb.core.USBTimeoutError.errno != 75 during read() may happen for an unplugged device
• usb.core.USBError.errno == 19 may happen for an unplugged device

I assume many other errno values are possible, and I have no idea if they are consistent for PyUSB across different operating systems. I don't remember finding documentation that explained this stuff. I just found these values by trial and error.

[samblenny]

I finally figured out a serviceable workaround for this, at least for gamepads. Basic idea is to count the number of consecutive calls to Device.read() that raise a USBTimeoutError exception. I haven't encountered a gamepad that will return more than maybe one or two timeouts in a row unless it's been unplugged. Keyboards on the other hand will do many timeouts until you press a key, so timeout counting doesn't work as well. This is a working example of the consecutive timeout counting method: https://github.com/samblenny/fruit-jam-two-gamepad-demo/blob/v0.1.1/sb_gamepad.py#L518-L576

[samblenny]

This seems to be fixed by:

• Improve usb.core.Device error handling #10611

[samblenny]

This was resolved by the merging of

• Improve usb.core.Device error handling REV 2 #10616

Unplug events will now raise USBError.