USB descriptor reads fail on RP2350 USB host with composite/dynamic devices (usb.core.USBError)

[i-am-me0-0]

CircuitPython version and board name

Adafruit CircuitPython 10.0.3 on 2025-10-17; Raspberry Pi Pico 2 with rp2350a

Raspberry Pi Pico 2 - https://www.waveshare.com/wiki/RP2350-USB-A

Code/REPL

import usb_host
import board

usb_host.Port(board.GP12, board.GP13)


# SPDX-License-Identifier: Unlicense

import usb.core


from relic_usb_host_descriptor_parser import DeviceDescriptor


for i, device in enumerate(usb.core.find(find_all=True)):

    device_descriptor = DeviceDescriptor(device)

    print(f"Device {i+1}: {device_descriptor}")

    for j, configuration in enumerate(device_descriptor.configurations):

        print(f"- Configuration {j+1}: {configuration}")

        for k, interface in enumerate(configuration.interfaces):

            print(f"  - Interface {k+1}: {interface}")

            for l, endpoint in enumerate(interface.endpoints):

                print(f"    - Endpoints {l+1}: {endpoint}")

    print()

Behavior

Traceback (most recent call last):
  File "<stdin>", line 17, in <module>
  File "relic_usb_host_descriptor_parser.py", line 285, in __init__
  File "adafruit_usb_host_descriptors.py", line 87, in get_device_descriptor
  File "adafruit_usb_host_descriptors.py", line 75, in get_descriptor
usb.core.USBError: 

that is the error message and is is related to descriptors specifically, this code does work which is only the PID and VID

import usb_host
import board

usb_host.Port(board.GP12, board.GP13)
import usb.core

for device in usb.core.find(find_all=True):
    print(device.idVendor, device.idProduct)

which results in
1118 654
in repl

Description

On RP2350-based boards acting as a USB host, attempting to read USB device descriptors using usb.core raises usb.core.USBError for certain devices that enumerate dynamically or expose multiple interfaces (e.g. 8BitDo USB Wireless Adapter 2).

Additional information

I have done a bunch of testing and debugging
Most importantly it seems to always come back to an error in the adafruit_usb_host_descriptors.py library

Further in the adafruit discord (help-with-circuitpython) there is an entire conversation history of everything I have tried and suggestions of others
I feel that is too large to add here but any questions i will answer.

Also this is my first time writing a GitHub issue, how did i do?

[RetiredWizard]

Can you try a test using a slightly modified version of Adafruit's Host descriptor library and this code snippet?

You'll need to rename any copies of adafruit_usb_host_descriptors.mpy you have in the /lib folder or the root folder of your device and then copy the adafruit_usb_host_descriptors.py from here (use the "download raw file" icon near the top of the code) to the /lib folder on your device. Once you have the .py file there on line 152 change USAGE_MOUSE to USAGE_GAMEPAD.

import usb.core
import adafruit_usb_host_descriptors
from traceback import print_exception

for device in usb.core.find(find_all=True):
# print device info
	try:
	    try:
		print(f"{device.idVendor:04x}:{device.idProduct:04x}")
	    except usb.core.USBError as e:
		print_exception(e, e, None)
	    try:
		print(device.manufacturer, device.product)
	    except usb.core.USBError as e:
		print_exception(e, e, None)
	    print()
	    config_descriptor = adafruit_usb_host_descriptors.get_configuration_descriptor(
		device, 0
	    )
	    print(config_descriptor)

	    _possible_interface_index, _possible_endpoint_address = adafruit_usb_host_descriptors.find_report_mouse_endpoint(device)
	    if _possible_interface_index is not None and _possible_endpoint_address is not None:
		mouse_device = device
		mouse_interface_index = _possible_interface_index
		mouse_endpoint_address = _possible_endpoint_address
		print(
		    f"gamepad interface: {mouse_interface_index} "
		    + f"endpoint_address: {hex(mouse_endpoint_address)}"
		)
		break
	    print(f"was not a {deviceType} gamepad")
	except usb.core.USBError as e:
	    print_exception(e, e, None)

EDIT: added missing import....

[i-am-me0-0]

I have done that
and i get

2dc8:3106
Traceback (most recent call last):
  File "<stdin>", line 49, in <module>
usb.core.USBError: 

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 51, in <module>
NameError: name 'print_exception' isn't defined

line 49 being
print(device.manufacturer, device.product)

this is the same with just the dongle no controller connected or dongle with controller connected

[RetiredWizard]

My bad, you need to add from traceback import print_exception near the top of the code snippet.... Sorry :/

[i-am-me0-0]

happens :)

2dc8:3106
usb.core.USBError: 

usb.core.USBError: 

not much more to be honest....

[RetiredWizard]

weird, the two errors sort of make sense but the snippet should have printed either the found interface or the "was not a gamepad" message (github isn't displaying the indention right but when I copy the code it seems okay)

[RetiredWizard]

Maybe I'm hiding too much info, can you try again with this snippet, this one let's it crash on the get_configuration call:

import usb.core
import adafruit_usb_host_descriptors
from traceback import print_exception

for device in usb.core.find(find_all=True):
# print device info
    try:
	print(f"{device.idVendor:04x}:{device.idProduct:04x}")
    except usb.core.USBError as e:
	print_exception(e, e, None)
    try:
	print(device.manufacturer, device.product)
    except usb.core.USBError as e:
	print_exception(e, e, None)
    print()
    config_descriptor = adafruit_usb_host_descriptors.get_configuration_descriptor(
	device, 0
    )
    print(config_descriptor)

    _possible_interface_index, _possible_endpoint_address = adafruit_usb_host_descriptors.find_report_mouse_endpoint(device)
    if _possible_interface_index is not None and _possible_endpoint_address is not None:
	mouse_device = device
	mouse_interface_index = _possible_interface_index
	mouse_endpoint_address = _possible_endpoint_address
	print(
	    f"gamepad interface: {mouse_interface_index} "
	    + f"endpoint_address: {hex(mouse_endpoint_address)}"
	)
	break
    print(f"was not a {deviceType} gamepad")

[i-am-me0-0]

2dc8:3106
usb.core.USBError: 

Traceback (most recent call last):
  File "<stdin>", line 53, in <module>
  File "/lib/adafruit_usb_host_descriptors.py", line 98, in get_configuration_descriptor
  File "/lib/adafruit_usb_host_descriptors.py", line 75, in get_descriptor
usb.core.USBError: 

this part fails
config_descriptor = adafruit_usb_host_descriptors.get_configuration_descriptor(
device, 0
)

[RetiredWizard]

Okay, that's a core call:

device.ctrl_transfer(
        _REQ_RCPT_DEVICE | _REQ_TYPE_STANDARD | _DIR_IN,
        _REQ_GET_DESCRIPTOR,
        wValue,
        wIndex,
        buf,
    )

I don't have any hardware that reproduces the issue but that points to a place to start looking....

[i-am-me0-0]

okay as a follow up i have tested now with a different board Waveshare RP2040-Zero and a usb a breakout
I get more successful results

using the code from
https://learn.adafruit.com/adafruit-feather-rp2040-with-usb-type-a-host/usb-host-read-data

with

import board
import usb_host
usb_host.Port(board.GP2, board.GP1)

added

i get this in repl with controller [xinput]

pid 0x2009
vid 0x57e
man Nintendo Co., Ltd.
product Pro Controller
serial E417D8019DF8
config[0]:
 value 1
 interface[0]
  class 03 subclass 00
  IN 81
  OUT 02
configuration set for Nintendo Co., Ltd., Pro Controller, E417D8019DF8
Idle state:
81 01 00 03 f8 9d 01 d8 17 e4 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 

Traceback (most recent call last):
  File "<stdin>", line 129, in <module>  [count = device.read(0x81, buf) #this line]
usb.core.USBError: 

this error seems to be the a similar error as sam blenny described in the discord

The main thing you need to do for that is wrap your USB host code in a retry loop so that if you get a USBError exception (often indicating device logically or physically unplugged), it will just sleep briefly then attempt to do a new .find() and go through the device configuration process again.
Another thing to be careful about is, particularly with wireless controllers, the speed you poll at makes a difference. If you use heavily object oriented code that goes through layers of  class method calls and other stuff that triggers heap allocations and dictionary lookups, you may end up polling too slowly to keep the wireless receiver happy.

i have tried this but cant seem to get past the first idle state read

it is also still quite inconsistent
throwing

pid 0x3106
vid 0x2dc8
Traceback (most recent call last):
  File "<stdin>", line 33, in <module>  
usb.core.USBError: 

often
but also sometimes success when no controller

pid 0x3107
vid 0x2dc8
man 8BitDo
product IDLE

i figured since the dongle defaults to switch mode i should try switch mode on my controller but that also does not work (even less so)

pid 0x3107
vid 0x2dc8
man 8BitDo
product IDLE
serial E417D8019DF8
config[0]:
 value 1
 interface[0]
  class 03 subclass 00
  IN 81
  OUT 02
configuration set for 8BitDo, IDLE, E417D8019DF8
Traceback (most recent call last):
  File "<stdin>", line 129, in <module>
usb.core.USBError: 

any ideas?

also have tried this code again with the original board rp2350-usb-a
but that fails still

pid 0x3106
vid 0x2dc8
Traceback (most recent call last):
  File "<stdin>", line 34, in <module> [print("man", device.manufacturer) #this line]
usb.core.USBError: 

this does at least confirm that there is a bug with that specific board

[samblenny]

That particular USB device (I have one) can cycle through a few USB descriptors, depending on how you talk to it. It seems to be designed with heuristic detection for which host OS USB stack it's connected to and tries to adapt to that. It can act like different devices are being unplugged and plugged in (Switch Pro, XInput, etc) over the course of several seconds.

I've had good results by using a retry loop where I just sleep for maybe 300 ms or whatever after a USBError exception then call find() again. Usually after the second or third attempt, I'll get a good usable connection (XInput) that stays up. It's very important to sleep for a while after the USBError so that TinyUSB has time to do whatever housekeeping it needs to do (possible there are some unresolved bugs there).

It's important to understand that TinyUSB will raise a USBError when you try to read from a device that has been unplugged, or when it becomes otherwise unreachable, so you need to use a try/except to plan for that. For example, that adapter will change its VID:PID when it connects to a bluetooth gamepad. During the switch, it's normal for TinyUSB to raise a USBException as if the USB device was physically unplugged.

For background and context there are some potentially related issues linked from here:

• USB Host Improvement Quest Umbrella Issue #10551

For examples of the type of retry loop that's worked for me in the past on Fruit Jam (RP2350), check out these guides:

• https://adafruit-playground.com/u/SamBlenny/pages/fruit-jam-gamepad-tester
• https://adafruit-playground.com/u/SamBlenny/pages/fruit-jam-two-gamepad-demo

In my testing, IIRC, it was pretty normal to sometimes get a Switch Pro descriptor, get part way through configuring that, be interrupted by a USBError, then get a successful XInput descriptor and setup when I sleep for a while then retry.

[qsantos]

Regarding the RP2350-USB-A specifically, my understanding is that the USB-A port is not properly pulled-down to act as a host.

Various people reported weird issues with only some devices being detected, and hot-plugging just not working. I found the cause last month. Maybe desoldering R13, like I describe in the article, will help @i-am-me0-0.

However, D+ and D- are not pulled-down anyway, which causes other issues (unplug not detect).