ESP-IDF v5.3.3 TinyUSB can't be switched back to USB/JTAG (regression since 5.3.2) (IDFGH-15248)

[johnboiles]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

IDF version.

v5.3.3

Espressif SoC revision.

ESP32-S3 v0.1

Operating System used.

macOS

How did you build your project?

Command line with Make

If you are using Windows, please specify command line type.

None

Development Kit.

Custom Board

Power Supply used.

USB

What is the expected behavior?

Related to #9826, previously it was possible to switch out the device from being a TinyUSB peripheral and go back to the built-in USB/JTAG peripheral (e.g. for programming). You could do that with this code:

tusb_cdc_acm_deinit(TINYUSB_CDC_ACM_0);
tinyusb_driver_uninstall();
usb_phy_config_t phy_config = {.controller = USB_PHY_CTRL_SERIAL_JTAG,
                               .target = USB_PHY_TARGET_INT};
usb_phy_handle_t jtag_phy;
usb_new_phy(&phy_config, &jtag_phy);

What is the actual behavior?

This no longer works in v5.3.3 (but works in v5.3.2). I also tested v5.4.1 and master (v5.5-dev-3510-gaaebc37467) and those don't work either.

Steps to reproduce.

Build and flash my attached sample project on an ESP32-S3 device using various IDF versions. Push the GPIO0 button to switch from TinyUSB CDC mode back to USB/JTAG mode. On v5.3.2 the Espressif Device will go away and the USB JTAG/serial debug unit will show up. On v5.3.3 and above, this won't happen.

20250506_tinyusb_usb_jtag_regression_v2.zip

Debug Logs.

I (328) main_task: Calling app_main()
I (328) usb_jtag_repro: USB JTAG Reproduction Test
I (328) usb_jtag_repro: tinyusb_driver_install(&tusb_cfg)
W (338) tusb_desc: No Device descriptor provided, using default.
W (338) tusb_desc: No FullSpeed configuration descriptor provided, using default.
W (348) tusb_desc: No String descriptors provided, using default.
I (358) tusb_desc:
┌─────────────────────────────────┐
│  USB Device Descriptor Summary  │
├───────────────────┬─────────────┤
│bDeviceClass       │ 239         │
├───────────────────┼─────────────┤
│bDeviceSubClass    │ 2           │
├───────────────────┼─────────────┤
│bDeviceProtocol    │ 1           │
├───────────────────┼─────────────┤
│bMaxPacketSize0    │ 64          │
├───────────────────┼─────────────┤
│idVendor           │ 0x303a      │
├───────────────────┼─────────────┤
│idProduct          │ 0x4001      │
├───────────────────┼─────────────┤
│bcdDevice          │ 0x100       │
├───────────────────┼─────────────┤
│iManufacturer      │ 0x1         │
├───────────────────┼─────────────┤
│iProduct           │ 0x2         │
├───────────────────┼─────────────┤
│iSerialNumber      │ 0x3         │
├───────────────────┼─────────────┤
│bNumConfigurations │ 0x1         │
└───────────────────┴─────────────┘
I (528) TinyUSB: TinyUSB Driver installed
I (528) gpio: GPIO[0]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:2
I (538) usb_jtag_repro: GPIO initialized, press button on GPIO0 to switch to JTAG mode
I (548) usb_jtag_repro: USB initialized
I (548) usb_jtag_repro: Press the button on GPIO0 to switch to JTAG mode
I (558) usb_jtag_repro: Waiting for button press...
I (5558) usb_jtag_repro: Waiting for button press...
I (8748) usb_jtag_repro: tusb_cdc_acm_deinit(TINYUSB_CDC_ACM_0)
I (8748) usb_jtag_repro: tinyusb_driver_uninstall()
I (8748) usb_jtag_repro: usb_new_phy(&phy_config, &jtag_phy)
I (8748) usb_jtag_repro: usb_new_phy succeeded```

### Diagnostic report archive.

_No response_

### More Information.

I'm testing on macOS but I doubt this is host OS specific, since the USB/JTAG device typically works consistently on every platform.

[jrahlf]

Try this:

esp_err_t tinyusb_driver_uninstall()
{
    tinyusb_free_descriptors();
    usb_phy_action(phy_hdl, USB_PHY_ACTION_HOST_FORCE_DISCONN);  <<<< added
    return usb_del_phy(phy_hdl);
}

[johnboiles]

@jrahlf same behavior with that change unfortunately. I'm not seeing any non-null esp_err_t from any of those functions either (via logging on the hardware UART). It happily succeeds but doesn't bring back the USB/JTAG device.

[atanisoft]

What I've seen was /dev/ttyACM0 would become /dev/ttyACM2 (/dev/ttyACM1 is a non-espressif device). There is no persistence unfortunately which causes problems for tools which are trying to toggle DTR/RTS etc bits to reboot the device automatically (which is detected and handled).

[atanisoft]

I should note, this is with the above "fix" in place btw

[johnboiles]

@atanisoft do you think that's related to the ability to switch between the USB_ACM TinyUSB device and USB/JTAG built-in device? Or is that a separate issue?

[atanisoft]

I'm leaning towards related, the switch of the device definitely creates a new ttyACMx device due to the shift from TinyUSB to USB/JTag. There is also a related problem though with ESPHome web installer or esptool.py in that neither of them detect the port change which is problematic as well.

[atanisoft]

it should really persist the device name (ttyACMx) between restarts regardless of the TinyUSB or USB/JTag. That should fix most of the issues from what I've seen.

[jrahlf]

When we had this problem (only tested on Windows), we noticed that the switching actually worked, but the PC would not re-enumerate the device. So if you unplugged it and plugged it in again (we have battery power), it worked fine. The added line above fixed the problem for us.
Also on Windows it is normal to have different com ports for TinyUSB and JTAG modes, they use different USB PIDs.

[atanisoft]

Unfortunately reiterating / changing the port will fail the use case of either bit twiddling of DTR/RTS OR simply changing from TinyUSB to/from USB/JTag.

That is one core difference here unfortunately that was working in v5.3.2 but seems broken in v5.3.3/v5.4.1/v5.5.x (master).

[johnboiles]

if you unplugged it and plugged it in again (we have battery power), it worked fine

I tried that just now on macOS with your USB_PHY_ACTION_HOST_FORCE_DISCONN change and a battery. Same behavior for me -- the device no longer enumerates at all. I'll try Windows too when I'm back in the office.

@atanisoft I bet the behavior of the port staying the same is a very Linux-specific thing. From my experience, that's never been the behavior on macOS or Windows. It may be a clue -- perhaps the TinyUSB interface doesn't get released entirely when going away and that's why the kernel is incrementing the tty #.

I'm going to bite the bullet and bisect the IDF changes :/ (sidenote: I'm so close to having Claude Code be able to do this for me automatically, except that when the USB device goes away I have no way to restart the MCU!)

[atanisoft]

You are likely right in that the tool isn't releasing the connection immediately (known bug in the tool) but there is still the esptool.py / esphome web tool that also fail similarly for bit twiddling which should work and result in the same TTY device upon completion. I think if we solve the issue of sorting out restarting reliably we can fix the tool issues in parallel.