Prioritise ports with vid==12346 (Espressif) (ESPTOOL-1183)

[nebkat]

Is your feature request related to a problem?

Esptool (and monitor) frequently waste time attempting to connect to random COM ports.

Describe the solution you'd like

Prioritise ports where vid==12346 (Espressif) in esptool.get_port_list so that there is a higher chance of first connection being successful.

Describe alternatives you've considered

Manual --port-filter or ability to specify it using an environment variable.

Additional context

The VID may be missing or can be customised by the user - but this is ESPtool after all 😆

[github-actions]

Hi @nebkat! 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.

---

Thanks for the suggestion!

A few notes and options based on current esptool capabilities and our USB guidance:

• The Espressif USB VID is 0x303A. If your request refers to “12346” as a decimal placeholder, the corresponding hex value would be 0x303A. Prioritizing or filtering by this VID is already supported via the existing port filtering feature. [USB VID/PID]

• Today, you can explicitly prefer Espressif ports using:

  • Command-line: --port-filter vid=0x303A (and optionally add pid, name, or serial filters). [Advanced options]
  • This works across chips (ESP32, ESP32-S2/S3, ESP32-Cx, ESP32-H2, ESP32-P4, etc.), and you can combine filters if you need to distinguish USB-OTG vs USB-Serial/JTAG (e.g., pid=0x0002 for ESP32-S2 OTG, pid=0x1001 for USB-Serial/JTAG). [[Advanced options](https://docs.espressif.com/projects/esptool/en/latest/esp32s2/esptool/advanced-options.html#filtering-serial-ports-port-filter; https://docs.espressif.com/projects/esptool/en/latest/esp32s3/esptool/advanced-options.html#filtering-serial-ports-port-filter)]

• Regarding your request to “prioritise” such ports automatically in esptool.get_port_list:

  • The knowledge sources do not mention a built-in priority mechanism or default preference for a particular VID inside esptool’s autodetection. They only document --port-filter as the supported way to constrain candidates. I’m sorry, but there’s no information about an existing automatic prioritization feature in the provided sources. [Advanced options]

• Environment variable alternative:

  • esptool recognizes several environment variables for defaults (chip/port/baud/flash parameters), but there’s no documented environment variable for --port-filter. You’d need to pass the filter on the command line (or via your build tool/wrapper). [Copilot instr.]

• Windows-specific tip (if you’re seeing a lot of COM variants for the same boards):

  • On S3/Cx/etc., Windows increments COM numbers because the USB-Serial/JTAG serial number differs per device (MAC-based). You can set a registry flag to ignore the hardware serial number for Espressif’s VID/PID (0x303A/0x1001), which helps reduce COM proliferation. [Const COM]

Proposal you can use immediately:

• Use --port-filter vid=0x303A in your esptool or monitor invocation to strongly bias selection toward Espressif devices.
• If you also want to narrow to a specific sub-type, add --port-filter pid=0x1001 (USB-Serial/JTAG) or --port-filter pid=0x0002 (ESP32-S2 OTG). [[Advanced options](https://docs.espressif.com/projects/esptool/en/latest/esp32s2/esptool/advanced-options.html#filtering-serial-ports-port-filter; https://docs.espressif.com/projects/esptool/en/latest/esp32c3/esptool/advanced-options.html#filtering-serial-ports-port-filter)]

Feedback acknowledged:

• Your feature request to internally prioritize ports with the Espressif VID makes sense, especially when many serial devices are present. Based on the docs available, this isn’t implemented or documented as a default behavior today. If you open a PR or issue proposing a ranked sorting (e.g., prefer VID=0x303A first, then others), that could complement the existing --port-filter for users who don’t want to specify filters each time. [Advanced options]

[radimkarnis]

Hi @nebkat,
Thanks for the feature request. It's a good idea, we'll look into it!

[Dzarda7]

Hi @nebkat, thanks for the suggestion, fix is ready, we even introduced filtering for ttyUSBx and ttyACMx, will be merged in a few day.