ESP32-S3+CONFIG_CONSOLE_USB_SERIAL_JTAG: System hangs unless host serial port is opened (IDFGH-8906)

[ncmiller]

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.1-dev-2186-g454aeb3a48

Operating System used.

Linux

How did you build your project?

Command line with idf.py

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

None

Development Kit.

Adafruit ESP32-S3 Feather

Power Supply used.

USB

What is the expected behavior?

Given the following:

• An Adafruit ESP32-S3 Feather board, and
• CONFIG_CONSOLE_USB_SERIAL_JTAG=y, and
• the code modifications described in the "Steps to reproduce" section to examples/system/console/basic

It's expected that the system should operate normally, regardless of whether the host machine has opened the USB serial port (via idf.py monitor or other serial terminal).

The indication of "operating normally" in that modified console example is that the red LED should come on for 1 second, then turn off, indicating that the system is not stuck/hanging.

What is the actual behavior?

If the host machine has opened the serial port to the device, the system operates normally (red LED comes on for 1 second, then turns off).

If the host machine has not opened the serial port to the device, the system hangs. The red LED comes on, then never shuts off. However, if at any point in time the host machine connects with a serial terminal (e.g picocom), then the system begins normal operation (red LED turned off, console shell is usable).

Steps to reproduce.

1. Apply the following patch to examples/system/console/basic:

diff --git a/examples/system/console/basic/main/console_example_main.c b/examples/system/console/basic/main/console_example_main.c
index f22b92d570..9b84debe05 100644
--- a/examples/system/console/basic/main/console_example_main.c
+++ b/examples/system/console/basic/main/console_example_main.c
@@ -19,6 +19,7 @@
 #include "cmd_system.h"
 #include "cmd_wifi.h"
 #include "cmd_nvs.h"
+#include "driver/gpio.h"

 static const char* TAG = "example";
 #define PROMPT_STR CONFIG_IDF_TARGET
@@ -100,4 +101,16 @@ void app_main(void)
 #endif

     ESP_ERROR_CHECK(esp_console_start_repl(repl));
+
+    /* Initialize GPIO for red LED on Adafruit ESP32-S3 Feather board */
+    gpio_set_direction(GPIO_NUM_13, GPIO_MODE_OUTPUT);
+    gpio_set_level(GPIO_NUM_13, 1); /* LED on */
+    vTaskDelay(1000 / portTICK_PERIOD_MS);
+    ESP_LOGI(TAG, "End of app_main");
+    /*
+     * If host serial port is connected, we get here.
+     *
+     * Otherwise, we never get here! (LED never turned off)
+     */
+    gpio_set_level(GPIO_NUM_13, 0);
 }

2. Build and flash the example to an Adafruit ESP32-S3 Feather board.
3. After the board has been flashed, do not open the serial port. The red LED should come on, then stay on, indicating the system is stuck.

Debug Logs.

N/A

More Information.

I've distilled the issue down to the simplest example I could think of.

I suspect any ESP32-S3 board with CONFIG_CONSOLE_USB_SERIAL_JTAG=y will exhibit this issue, but I've only tested with the Adafruit board, so I don't know for sure.

I originally discovered this issue when trying to build an ESP32-S3 application with CONFIG_CONSOLE_USB_SERIAL_JTAG=y. I noticed that everything worked perfectly when using idf.py monitor with a USB-C cable connected to my host machine, but it would hang in either of these scenarios:

• USB-C cable to host machine, but serial port never opened
• No USB-C cable to host machine, board powered from USB-C power adapter.

[chipweinberger]

Yes, I find it a very annoying limitation too.

I have a PR to fix it. #10208

You can cherry-pick the commit / copy it and fix your issue.

@igrr, can we review it?

[ncmiller]

Thanks @chipweinberger . I confirmed that PR fixes the issue.

[chipweinberger]

The fix was merged. 720b8d9

[cyberhuman]

Hi!
I think I have the same issue but with ESP32-C3.
It still hangs when using esp-idf 5.1, which contains the fix referenced above.
Looking at the code, I'm not sure how it can work. It's supposed to set the tx_tried_blocking flag when usb_serial_jtag_write_bytes returns zero, but this can never happen. Am I missing something?

[cyberhuman]

It looks like the fix in c39be8b was correct but the next commit 720b8d9 broke it.

[mvermand22]

Any status update on this? Any temporary fixes? This is a really annoying issue.

[chipweinberger]

Looking at the code, I'm not sure how it can work. It's supposed to set the tx_tried_blocking flag when usb_serial_jtag_write_bytes returns zero, but this can never happen. Am I missing something?

c926153

fixed in v5.1.2 (ea5e749)

[cyberhuman]

Indeed, thank you! I had had a local fix locally. I need to upgrade.

[mvermand22]

Ok, thanks, I'm not that experienced...
I'm using Arduino IDE 2.2.1, I have "esp32 by Espressif Systems" 2.0.11 installed in Boards Manager and I have a ESP32-S3 from Wirelesstag (wt32-sc01-plus 3.5 inch display). The board has no Boot-button, only a reset button.
What should I do to get the issue fixed in this configuration (Arduino IDE 2.x)?
Thanks a lot!

[chipweinberger]

@mvermand22 not sure if you can fix it yourself. You'll need to wait for Arduino to update to v5.1.2

[mvermand22]

• The v5.1.2, of what package is that the version?
• Is it right to say that the issue is caused by some firmware installed on the esp32 board (by flashing it)? (*)
• Is there any #define, or other api call I can make to change behaviour? ()
  () I'm not that experienced... maybe I'm saying nonsens...

[mvermand22]

Is it this one? https://github.com/espressif/arduino-esp32