feat: Improve ports sorting when autodetection is used

Closes #1124

Author: Dzarda7

.gitlab-ci.yml

@@ -94,6 +94,7 @@ host_tests:
     - coverage run --parallel-mode -m pytest ${CI_PROJECT_DIR}/test/test_image_info.py
     - coverage run --parallel-mode -m pytest ${CI_PROJECT_DIR}/test/test_modules.py
     - coverage run --parallel-mode -m pytest ${CI_PROJECT_DIR}/test/test_logger.py
+    - coverage run --parallel-mode -m pytest ${CI_PROJECT_DIR}/test/test_port_sorting.py
     # some .coverage files in sub-directories are not collected on some runners, move them firs
     - find . -mindepth 2 -type f -name ".coverage*" -print -exec mv --backup=numbered {} . \;
 
@@ -135,6 +136,7 @@ host_tests_latest_python:
     -  pytest ${CI_PROJECT_DIR}/test/test_image_info.py
     -  pytest ${CI_PROJECT_DIR}/test/test_modules.py
     -  pytest ${CI_PROJECT_DIR}/test/test_logger.py
+    -  pytest ${CI_PROJECT_DIR}/test/test_port_sorting.py
     -  pytest ${CI_PROJECT_DIR}/test/test_espefuse.py --chip esp32
 
 # A new job "host_test_hsm" is created for the test "test_espsecure_hsm.py" which runs an ubuntu image,
@@ -487,6 +489,7 @@ host_tests_windows:
     - python -m coverage run --parallel-mode -m pytest ${CI_PROJECT_DIR}/test/test_modules.py
     - python -m coverage run --parallel-mode -m pytest ${CI_PROJECT_DIR}/test/test_merge_bin.py
     - python -m coverage run --parallel-mode -m pytest ${CI_PROJECT_DIR}/test/test_logger.py
+    - python -m coverage run --parallel-mode -m pytest ${CI_PROJECT_DIR}/test/test_port_sorting.py
 
 target_tests_windows:
   extends: .windows_test

CONTRIBUTING.rst

@@ -131,6 +131,7 @@ The following tests run automatically by GitHub Actions for each Pull Request. Y
 *  ``test_imagegen.py`` tests the ``elf2image`` command
 *  ``test_image_info.py`` tests the ``image-info`` command
 *  ``test_mergebin.py`` tests the ``merge-bin`` command
+*  ``test_port_sorting.py`` tests the port sorting algorithm of ``esptool``
 *  ``test_modules.py`` tests the modules used by ``esptool`` for regressions
 *  ``test_espsecure.py`` tests ``espsecure`` functionality
 *  ``test_espsecure_hsm.py`` tests support of external HSM signing in ``espsecure``. These tests require additional prerequisites, see ``SoftHSM2 setup`` in the `tests workflow definition <https://github.com/espressif/esptool/blob/master/.github/workflows/test_esptool.yml>`_ for more information.

esptool/__init__.py

@@ -1050,7 +1050,7 @@ def get_port_list(
     ports = []
     for port in list_ports.comports():
         if sys.platform == "darwin" and port.device.endswith(
-            ("Bluetooth-Incoming-Port", "wlan-debug")
+            ("Bluetooth-Incoming-Port", "wlan-debug", "cu.debug-console")
         ):
             continue
         if vids and (port.vid is None or port.vid not in vids):
@@ -1066,8 +1066,52 @@ def get_port_list(
             or all(serial not in port.serial_number for serial in serials)
         ):
             continue
-        ports.append(port.device)
-    return sorted(ports)
+        ports.append((port.device, port.vid))
+
+    # Constants for sorting optimization
+    ESPRESSIF_VID = 0x303A
+    LINUX_DEVICE_PATTERNS = ("ttyUSB", "ttyACM")
+    MACOS_DEVICE_PATTERNS = ("usbserial", "usbmodem")
+
+    def _port_sort_key_linux(port_info):
+        device, vid = port_info
+
+        if vid == ESPRESSIF_VID:
+            return (3, device)
+
+        if any(pattern in device for pattern in LINUX_DEVICE_PATTERNS):
+            return (2, device)
+
+        return (1, device)
+
+    def _port_sort_key_macos(port_info):
+        device, vid = port_info
+
+        if vid == ESPRESSIF_VID:
+            return (3, device)
+
+        if any(pattern in device for pattern in MACOS_DEVICE_PATTERNS):
+            return (2, device)
+
+        return (1, device)
+
+    def _port_sort_key_windows(port_info):
+        device, vid = port_info
+
+        if vid == ESPRESSIF_VID:
+            return (2, device)
+
+        return (1, device)
+
+    if sys.platform == "win32":
+        key_func = _port_sort_key_windows
+    elif sys.platform == "darwin":
+        key_func = _port_sort_key_macos
+    else:
+        key_func = _port_sort_key_linux
+
+    sorted_port_info = sorted(ports, key=key_func)
+    return [device for device, _ in sorted_port_info]
 
 
 def expand_file_arguments(argv: list[str]) -> list[str]:

test/test_port_sorting.py

@@ -0,0 +1,175 @@
+import pytest
+from unittest.mock import patch
+import esptool
+
+# Espressif VID constant (same as in esptool/__init__.py)
+ESPRESSIF_VID = 0x303A
+
+
+class MockPort:
+    """Mock serial port object that mimics pyserial's ListPortInfo"""
+
+    def __init__(self, device, vid=None, pid=None, name=None, serial_number=None):
+        self.device = device
+        self.vid = vid
+        self.pid = pid
+        self.name = name
+        self.serial_number = serial_number
+
+
+@pytest.mark.host_test
+class TestPortSorting:
+    """Test the port sorting algorithm in get_port_list function"""
+
+    def test_linux_port_sorting(self):
+        """Test port sorting on Linux platform"""
+        mock_ports = [
+            MockPort("/dev/ttyS0", vid=0x1234),
+            MockPort("/dev/ttyS1", vid=0x1234),
+            MockPort("/dev/ttyUSB0", vid=0x1234),
+            MockPort("/dev/ttyUSB1", vid=0x1234),
+            MockPort("/dev/ttyACM1", vid=ESPRESSIF_VID),
+            MockPort("/dev/ttyACM0", vid=0x1234),
+        ]
+
+        with (
+            patch("sys.platform", "linux"),
+            patch("esptool.list_ports") as mock_list_ports,
+        ):
+            mock_list_ports.comports.return_value = mock_ports
+
+            result = esptool.get_port_list()
+
+            # Expected sorting order (alphabetically within each group):
+            # 1. Other devices (priority 1)
+            # 2. ttyUSB*/ttyACM* devices (priority 2)
+            # 3. Espressif VID devices (priority 3) - highest priority, appear LAST
+            expected = [
+                "/dev/ttyS0",  # Other
+                "/dev/ttyS1",  # Other
+                "/dev/ttyACM0",  # USB/ACM
+                "/dev/ttyUSB0",  # USB/ACM
+                "/dev/ttyUSB1",  # USB/ACM
+                "/dev/ttyACM1",  # Espressif VID
+            ]
+
+            assert result == expected
+
+    def test_macos_port_sorting(self):
+        """Test port sorting on macOS platform"""
+        mock_ports = [
+            MockPort("/dev/cu.wlan-debug", vid=0x1234),  # Excluded by macOS filter
+            MockPort(
+                "/dev/cu.Bluetooth-Incoming-Port", vid=0x1234
+            ),  # Excluded by macOS filter
+            MockPort("/dev/cu.debug-console", vid=0x1234),  # Excluded by macOS filter
+            MockPort("/dev/cu.usbserial2", vid=0x1234),
+            MockPort("/dev/cu.usbmodem1", vid=0x1234),
+            MockPort("/dev/cu.usbmodem2", vid=ESPRESSIF_VID),
+            MockPort("/dev/cu.usbserial1", vid=0x1234),
+        ]
+
+        with (
+            patch("sys.platform", "darwin"),
+            patch("esptool.list_ports") as mock_list_ports,
+        ):
+            mock_list_ports.comports.return_value = mock_ports
+
+            result = esptool.get_port_list()
+
+            # Expected sorting order (alphabetically within each group):
+            # 1. Other devices (priority 1)
+            # 2. usbserial*/usbmodem* devices (priority 2)
+            # 3. Espressif VID devices (priority 3) - highest priority, appear LAST
+            # Note: wlan-debug, Bluetooth-Incoming-Port, debug-console are excluded
+            expected = [
+                "/dev/cu.usbmodem1",  # usbmodem
+                "/dev/cu.usbserial1",  # usbserial
+                "/dev/cu.usbserial2",  # usbserial
+                "/dev/cu.usbmodem2",  # Espressif VID
+            ]
+
+            assert result == expected
+
+    def test_windows_port_sorting(self):
+        """Test port sorting on Windows platform"""
+        mock_ports = [
+            MockPort("COM3", vid=0x1234),
+            MockPort("COM1", vid=0x1234),
+            MockPort("COM10", vid=0x1234),
+            MockPort("COM5", vid=ESPRESSIF_VID),
+            MockPort("COM2", vid=0x1234),
+        ]
+
+        with (
+            patch("sys.platform", "win32"),
+            patch("esptool.list_ports") as mock_list_ports,
+        ):
+            mock_list_ports.comports.return_value = mock_ports
+
+            result = esptool.get_port_list()
+
+            # Expected sorting order (alphabetically within each group):
+            # 1. All other COM ports (priority 1)
+            # 2. Espressif VID devices (priority 2) - highest priority, appear LAST
+            expected = [
+                "COM1",  # Other
+                "COM10",  # Other
+                "COM2",  # Other
+                "COM3",  # Other
+                "COM5",  # Espressif VID
+            ]
+
+            assert result == expected
+
+    def test_port_filtering_parameters(self):
+        """Test port filtering with various parameters while maintaining sorting"""
+        mock_ports = [
+            MockPort(
+                "/dev/ttyUSB0",
+                vid=0x1234,
+                pid=0x5678,
+                name="USB Serial",
+                serial_number="ABC123",
+            ),
+            MockPort(
+                "/dev/ttyUSB1",
+                vid=ESPRESSIF_VID,
+                pid=0x1001,
+                name="ESP32",
+                serial_number="ESP001",
+            ),
+            MockPort(
+                "/dev/ttyUSB2",
+                vid=ESPRESSIF_VID,
+                pid=0x1002,
+                name="ESP32-S3",
+                serial_number="ESP002",
+            ),
+        ]
+
+        with (
+            patch("sys.platform", "linux"),
+            patch("esptool.list_ports") as mock_list_ports,
+        ):
+            mock_list_ports.comports.return_value = mock_ports
+
+            # Test VID filtering - Espressif devices appear last
+            result = esptool.get_port_list(vids=[ESPRESSIF_VID])
+            expected = ["/dev/ttyUSB1", "/dev/ttyUSB2"]
+            assert result == expected
+
+            # Test PID filtering
+            result = esptool.get_port_list(pids=[0x1001])
+            expected = ["/dev/ttyUSB1"]
+            assert result == expected
+
+            # Test name filtering
+            result = esptool.get_port_list(names=["ESP32"])
+            expected = ["/dev/ttyUSB1", "/dev/ttyUSB2"]
+            assert result == expected
+
+            # Test serial filtering
+            result = esptool.get_port_list(serials=["ESP"])
+            expected = ["/dev/ttyUSB1", "/dev/ttyUSB2"]
+            assert result == expected