PlatformIO Community

Enabling USB Serial on ESP32-C3

Hi all,

I’ve built a custom board with the ESP32-C3. I have my USB connection directly connected to the USB D+/D- on the ESP32 (I’m not using a serial converter) and based on the documentation and limitations here, I enabled the following option in my Platform IO menuconfig:


From the limitations, I know I need to hold IO9/BOOT and reset to kick into Download Mode the first time, so I can program my board. When I do this, my code loads successfully. However, I assumed after the first time programming with the option above, the USB serial module should be able reset and kick into Download Mode automatically.

Instead, if I try programming again without manually entering the bootloader, it fails to program. Do I need to do something else in Platform IO to get USB serial mode to work correctly?


I’ve gotten a little further. It sounds like isn’t auto detecting that I need a USB reset. I tried adding --before usb_reset in the upload_flags section of platform.ini but it doesn’t seem to accept that.

Looking at the verbose upload command, I see that --before is already specified and it’s tied to CONFIG_ESPTOOLPY_BEFORE in the menuconfig. However, there’s no usb_reset option in menuconfig. Is there a way to add that option?

platform-espressif32 has the default_reset hardcoded.

does it work if you modify it right there to usb_reset? The file should be in C:\Users\<user>\.platformio\platforms\espressif32\builder\

Thanks maxgerhardt! That worked really well, now I don’t need the custom build command. Much appreciated.


Can you file an issue in Issues · platformio/platform-espressif32 · GitHub so that this may be taken from the board’s JSON file (e.g. board_upload.reset_method). I’m sure this will benefit future boards.

No Problem, submitted on Git as Issue #874.

You have to set a flag to switch the serial console to the inbuilt modem. For example this boards manifest (Adafruit) to use CDC. Can be used in general for C3 boards when CDC is used.

  "build": {
      "ldscript": "esp32c3_out.ld"
    "core": "esp32",
    "extra_flags": [
    "f_cpu": "160000000L",
    "f_flash": "80000000L",
    "flash_mode": "dout",
    "hwids": [
    "mcu": "esp32c3",
    "variant": "adafruit_qtpy_esp32c3"
  "connectivity": [
  "debug": {
    "openocd_target": "esp32c3.cfg"
  "frameworks": [
  "name": "Adafruit QT Py ESP32-C3",
  "upload": {
    "flash_size": "4MB",
    "maximum_ram_size": 327680,
    "maximum_size": 4194304,
    "require_upload_port": true,
    "speed": 460800
  "url": "",
  "vendor": "Adafruit"

EDIT: This approach only works for JTAG mode not for usual USB.