You must enter download mode to flash the program; this wasn't the case before (ESPTOOL-1187).

[TinyuZhao]

Operating System

macOS 15.4.1

Esptool Version

esptool.py v4.9.0

Python Version

Python 3.13.3

Chip Description

ESP32S3

Device Description

M5StackCoreS3

Hardware Configuration

https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/490/Sch_M5_CoreS3_v1.0.pdf

How is Esptool Run

No IDE

Full Esptool Command Line that Was Run

esptool.py --chip esp32s3 --port /dev/cu.usbmodem211101 --baud 1500000 write_flash 0x0 /Users/tinyu/Developer/Code/uiflow_micropython/uiflow_develop/m5stack/build-M5STACK_CoreS3/uiflow-885edad6.bin

Esptool Output

~ esptool.py --chip esp32s3 --port /dev/cu.usbmodem211101 --baud 1500000 write_flash 0x0 /Users/tinyu/Developer/Code/uiflow_micropython/uiflow_develop/m5stack/build-M5STACK_CoreS3/uiflow-885edad6.bin
esptool.py v4.9.0
Serial port /dev/cu.usbmodem211101
Connecting....

A serial exception error occurred: Could not configure port: (6, 'Device not configured')
Note: This error originates from pySerial. It is likely not a problem with esptool, but with the hardware connection or drivers.
For troubleshooting steps visit: https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html

More Information

➜ ~ ls /dev/cu.*
/dev/cu.Bluetooth-Incoming-Port /dev/cu.usbmodem211101
/dev/cu.debug-console

---

Before Run esptool write_flash command

---

➜ ~ esptool.py --chip esp32s3 --port /dev/cu.usbmodem211101 --baud 1500000 write_flash 0x0 /Users/tinyu/Developer/Code/uiflow_micropython/uiflow_develop/m5stack/build-M5STACK_CoreS3/uiflow-885edad6.bin
esptool.py v4.9.0
Serial port /dev/cu.usbmodem211101
Connecting....

A serial exception error occurred: Could not configure port: (6, 'Device not configured')
Note: This error originates from pySerial. It is likely not a problem with esptool, but with the hardware connection or drivers.
For troubleshooting steps visit: https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html

---

After Run esptool write_flash command

---

➜ ~ ls /dev/cu.*
/dev/cu.Bluetooth-Incoming-Port /dev/cu.debug-console

Other Steps to Reproduce

No response

I Have Read the Troubleshooting Guide

• I confirm I have read the troubleshooting guide.

[github-actions]

Hi @Tinyu-Zhao! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

Thank you for providing detailed information. Based on the knowledge sources and your description, here’s an analysis and guidance for your issue:

Problem Summary

You are experiencing a situation where the ESP32-S3 (M5Stack CoreS3) must be manually put into download mode to flash firmware, whereas previously this was not required. The error from esptool is:

A serial exception error occurred: Could not configure port: (6, 'Device not configured')
Note: This error originates from pySerial. It is likely not a problem with esptool, but with the hardware connection or drivers.

After running the command, the device port disappears from /dev/cu.*.

---

Analysis

1. USB-Serial/JTAG Download Mode Behavior

For ESP32-S3, if the flash is empty, corrupted, or contains non-bootable firmware, the chip will continuously reset every few seconds. This causes the USB-Serial/JTAG port to repeatedly disconnect and reconnect, making it difficult for esptool to establish a stable connection. This is a known behavior and is documented by Espressif:

If it cannot start normally (due to empty flash, no correct data/firmware in flash, the power-on sequence problem of flash, etc.), the internal timer will trigger the chip to restart every few seconds. The chip cannot connect stably until the program starts normally or enters the download mode.
... You need to boot the chip to enter the download mode manually before the first download or after flash is erased, so that the chip can be connected stably.
ESP FAQ: USB Serial/JTAG Controller issues

2. Serial Port Disappearing

The fact that /dev/cu.usbmodem211101 disappears after running the command further supports that the chip is resetting and the USB peripheral is being re-initialized, which is expected if the device is not in download mode or the flash is empty/corrupted.

3. Manual Download Mode Required

This is why you must now manually enter download mode (usually by holding BOOT and pressing RESET) to flash the device. Once valid firmware is flashed, the USB port should remain stable for subsequent operations.

4. Driver/Permission Issues

The error message from pySerial can also be caused by:

• The port being in use by another process.
• Missing or faulty drivers.
• Insufficient permissions.

However, since the port disappears after the failed attempt, the root cause is most likely the chip’s reset behavior, not a driver or permission issue. For completeness, ensure you have the correct drivers installed and the necessary permissions, as described in the documentation for macOS usersCheck Port on Linux and macOS.

---

Recommendations

1. Manually Enter Download Mode:
   Before flashing, press and hold the BOOT button, press RESET, then release BOOT. This will put the ESP32-S3 into a stable download mode for flashing.
   Flashing Troubleshooting

2. Flash Valid Firmware:
   After successful flashing, the device should boot normally and the USB port should remain stable.

3. Subsequent Flashes:
   Once valid firmware is present, you should be able to flash without manual intervention, unless the flash is erased or corrupted again.

4. If Issues Persist:

   • Double-check USB cable quality and try a different cable.
   • Ensure no other process is using the serial port.
   • Verify drivers and permissions as per Espressif’s documentation.

---

References

• ESP FAQ: USB Serial/JTAG Controller issues
• Flashing Troubleshooting (ESP32-S3)
• Check Port on Linux and macOS
• Esptool Troubleshooting: Common Errors

---

Summary:
This is expected behavior for ESP32-S3 when the flash is empty or invalid. Manually entering download mode is required in this state. Once valid firmware is flashed, the device should behave as before. If you continue to have issues, check your USB cable, drivers, and permissions.

[radimkarnis]

Hello @Tinyu-Zhao,

can you please specify what you mean by this wasn't the case before?
Have you recently updated esptool, or has this started with a new build of your app?

If the app reconfigures the GPIO pins used for the USB communication, the port can become unusable (until download mode is entered manually, then the ROM reconfigures the pins back to a usable USB-CDC device).

The fact that the port disappears after you run esptool signals either to faulty HW configuration (mentioned above) or faulty USB drivers. After opening the port fails, it seems to get de-enumerated because the OS deems it unusable.

This is definitely not an issue in esptool. It is dependent on a working serial connection. In this case, the serial port cannot even be opened.

[TinyuZhao]

Hello @Tinyu-Zhao,

can you please specify what you mean by this wasn't the case before? Have you recently updated esptool, or has this started with a new build of your app?

If the app reconfigures the GPIO pins used for the USB communication, the port can become unusable (until download mode is entered manually, then the ROM reconfigures the pins back to a usable USB-CDC device).

The fact that the port disappears after you run esptool signals either to faulty HW configuration (mentioned above) or faulty USB drivers. After opening the port fails, it seems to get de-enumerated because the OS deems it unusable.

This is definitely not an issue in esptool. It is dependent on a working serial connection. In this case, the serial port cannot even be opened.

Previously, I could use esptool to flash the ESP32S3 without putting it into download mode.

I haven't updated esptool recently, and I'm getting errors whether I use the esptool built into esp-idf or the one installed via pip install esptool.

However, if I use idc.py flash, this issue won't occur.

this is hardware sch

[radimkarnis]

However, if I use idc.py flash, this issue won't occur.

This command still runs the esptool that's bundled with ESP-IDF, but you say I'm getting errors whether I use the esptool built into esp-idf. Can you check if there is a difference between esptool version or in the way esptool is invoked (you can see the full esptool command in the idf.py output log)?

You can also try adding the --before usb_reset argument (after esptool.py).

[dobairoland]

However, if I use idc.py flash, this issue won't occur.

Also please let us know what esptool version is printed there.

[TinyuZhao]

I just reproduced it again

1. Re-power on the device that just failed to flash via esptool.py and flash the esp-idf/examples/get-started/hello_world program using idf.py flash ----> I get the same error

2. After the device enters download mode, use `idf.py flash`` to burn the program again. --> Burn successfully

3. Without putting the device into download mode, execute idf.py flash to flash the program. The flash is successful (I have tried multiple times and all are successful).

4. Without putting the device into download mode, execute esptool.py -p /dev/cu.usbmodem211101 -b 1500000 write_flash 0x0 ~/Developer/Code/uiflow_micropython/uiflow_develop/m5stack/build-M5STACK_CoreS3/uiflow-4eb4f152.bin --> Burn successfully

5. After flashing the firmware, without putting the device into download mode, execute idf.py flash flash program --> Flashing fails, and the same error message as Figure 1 is displayed

I don't know why this happened

[TinyuZhao]

However, if I use idc.py flash, this issue won't occur.

This command still runs the esptool that's bundled with ESP-IDF, but you say I'm getting errors whether I use the esptool built into esp-idf. Can you check if there is a difference between esptool version or in the way esptool is invoked (you can see the full esptool command in the idf.py output log)?

You can also try adding the --before usb_reset argument (after esptool.py).

If --before usb_reset is used, no data will be received. However, there is an improvement. After executing this command, my serial port will not disappear.

[radimkarnis]

Please see that the switching into download mode:

1. Works when the "hello world" app is loaded
2. Stops working when you load your app

This means your app is compiled without the USB-Serial/JTAG support, or it reconfigures the USB pins (GPIO19 and 20). Can you please check that? Without this support activated the USB-Serial/JTAG HW cannot detect and act on the reset sequence.

[TinyuZhao]

Please see that the switching into download mode:

1. Works when the "hello world" app is loaded
2. Stops working when you load your app

This means your app is compiled without the USB-Serial/JTAG support, or it reconfigures the USB pins (GPIO19 and 20). Can you please check that? Without this support activated the USB-Serial/JTAG HW cannot detect and act on the reset sequence.

🤔My SDKConfig has USB JTAG enabled, and I haven't changed the USB pins.

But I think this might indeed be a viable approach. The affected firmware is an extension we built on top of MicroPython, and the ESP32 portion of MicroPython is also an IDF project.

[dobairoland]

Do you see the misspelling in the config name? I.e. USJ instead of USB. The config value will be ignored by the build system if it is misspelled. So you don't have USB Serial/JTAG enabled.

Oh, sorry. I was wrong: https://github.com/espressif/esp-idf/blob/25c40d4563be7d4caf375b59c52283ff80c62d08/components/esp_driver_usb_serial_jtag/Kconfig#L4

[radimkarnis]

@Tinyu-Zhao there is nothing we can do on the side of esptool. Please check the correct configuration of your app. You can try to compare the working case of Hello World with your app. Look into recently changed parts of your code, which might have caused the issue.

[TinyuZhao]

@radimkarnis @dobairoland
Thank you for your enthusiastic responses, but since this issue isn't caused by esptool, I've closed the question. If my research yields any results, I'll post an update here.