Skip to content

Conversation

Josverl
Copy link
Contributor

@Josverl Josverl commented Jul 31, 2025

Summary

With modern ESPxxx boards switching to native USB , and less reliance on 3rd party UART drivers I think it is a good time to implement a better detection if a device is likely to have an MCU of the ESP32 or ESP8266 femilies

This PR adds:

  • a list of VIDs-PIDs that require "ESP-Handling" on Windows.
  • this list can be extended through the mpremote configuration file
    when connecting to a decices port on Windows - mpremote can check if it needs ESP-Handling - and then act accordingly
    if / when needed new vids/pids can be added to the default list via PRs, and included in the next release
    personal / interim changes can be done by editing the mpremote config file.

In this draft the detection is based on a list of 4-tuples,
Current implementation only used the VID and PID to identify ,
the vendor could be used if if there is a need to extend matches.

The list of VIDs and PIDs has been gathered through

  • inspection and testing of some devices
  • documentation research on the internet

user configuration:

the user configuration allows to add additional PID/VIDs.
currently overriding the built-in list is not implemented

#config.py - mpremote configuration file 

esp_detection = [
    # chipset , VID, PID, Vendor
    ("CP2102 / CP2104", 0x10C4, 0xEA60, "Silicon Labs"),
    ( "foobar" , 0xFFFFF, 0xFFFFF, "Unknown")
]

Testing

Manual testing can be done by attaching devices and running the following script:

from mpremote.transport_serial import is_esp_device
import serial.tools.list_ports

ports = serial.tools.list_ports.comports()
for port in ports:
    if port.vid is None:
        continue
    print(f"{port.device} {port.vid:04x}:{port.pid:04x} {port.description} - {"ESP device" if is_esp_device(port.device) else "Non-ESP device"}")

Positive identification of:

  • Espressif USB-CDC
    • COM8 303a:1001 USB Serial Device (COM8) - ESP device. - ESP32-C3
    • COM18 303a:1001 USB Serial Device (COM18) - ESP32-C3 Mini device
    • COM21 303a:4001 USB Serial Device (COM21) - ESP device - ESP32-S3
    • COM14 303a:4001 USB Serial Device (COM14) - ESP device - ESP32-S2
  • CP2102 / CP2104
    • COM17 4292:60000 Silicon Labs CP210x USB to UART Bridge (COM17) - ESP32 device
  • CP210x
    • COM9 10c4:ea60 Silicon Labs CP210x USB to UART Bridge (COM9) - ESP8266 device
    • COM23 10c4:ea60 Silicon Labs CP210x USB to UART Bridge (COM23) - ESP32 device
  • CH340K - COM15 1a86:7522 USB-SERIAL CH340K (COM15) - ESP-C3 UART device
  • FT232R / FTDI -
  • CH340
    • COM5 1a86:7523 USB-SERIAL CH340 (COM5) - ESP8266 device
    • COM5 1a86:7523 USB-SERIAL CH340 (COM5) - ESP8266 device
  • CH341 -
  • Prolific PL2303 -
  • Microchip MCP2200 -
  • CH9102 / CH9102F -
  • Pycom -

not detected as ESPxx device.

  • rpi pico/picow
  • rpi pico2
    • COM26 2e8a:0005 USB Serial Device (COM26) - Non-ESP device
  • pimorino pico lipo
  • PYBDv1.1
    • COM24 f055:9800 USB Serial Device (COM24) - Non-ESP device
  • NRF5240
    • COM25 239a:8029 USB Serial Device (COM25) - Non-ESP device
  • Micro:bit v1
    • COM27 0d28:0204 USB Serial Device (COM27) - Non-ESP device
  • to test more

Trade-offs and Alternatives

VID/PID versus Vendor name
Up to now the determination was done just based on the Vendor name.
See #9659

Cherry-picking
This PR contains a few cherry-picked commits from other PRs that are required to allow this PR to work.
They should be automatically dropped when this PR is rebased before merging.

Signed-off-by: Jos Verlinde Jos_Verlinde@hotmail.com

Copy link

Code size report:

   bare-arm:    +0 +0.000% 
minimal x86:    +0 +0.000% 
   unix x64:    +0 +0.000% standard
      stm32:    +0 +0.000% PYBV10
     mimxrt:    +0 +0.000% TEENSY40
        rp2:    +0 +0.000% RPI_PICO_W
       samd:    +0 +0.000% ADAFRUIT_ITSYBITSY_M4_EXPRESS
  qemu rv32:    +0 +0.000% VIRT_RV32

Copy link

codecov bot commented Jul 31, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.38%. Comparing base (c0252d7) to head (8aa4844).

Additional details and impacted files
@@           Coverage Diff           @@
##           master   #17800   +/-   ##
=======================================
  Coverage   98.38%   98.38%           
=======================================
  Files         171      171           
  Lines       22283    22283           
=======================================
  Hits        21924    21924           
  Misses        359      359           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@Josverl Josverl force-pushed the mpr/esp_detect_configurable branch 2 times, most recently from 329ccbb to f4f540a Compare July 31, 2025 21:08
@Josverl Josverl changed the title Mpr/esp_detect_configurable mpremote: Improve ESPxx board detection and user configuration. Jul 31, 2025
@dpgeorge dpgeorge added the tools Relates to tools/ directory in source, or other tooling label Aug 1, 2025
@Josverl Josverl force-pushed the mpr/esp_detect_configurable branch from f4f540a to 48c07d6 Compare August 2, 2025 23:25
@Josverl
Copy link
Contributor Author

Josverl commented Aug 2, 2025

Added the ESP32-C6 that uses a CH343 which was not detected.:

  • COM29 303a:1001 USB Serial Device (COM29) - ESP device
  • COM28 1a86:55d3 USB-Enhanced-SERIAL CH343 (COM28) - Non-ESP device

@Josverl Josverl force-pushed the mpr/esp_detect_configurable branch from 48c07d6 to 923363a Compare August 2, 2025 23:30
Josverl added 2 commits August 3, 2025 01:31
Signed-off-by: Jos Verlinde <Jos_Verlinde@hotmail.com>
Signed-off-by: Jos Verlinde <Jos_Verlinde@hotmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
tools Relates to tools/ directory in source, or other tooling
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants