Skip to content

deploy: auto-select serial port by USB VID/PID matching the target env's board #591

@zackees

Description

@zackees

Symptom

When multiple devices are attached and no -p/--port is given, fbuild deploy -e <env> picks whatever port it sees first, even when that port's USB identity has nothing to do with the requested environment. Reproduced just now on Windows:

> pio device list
COM21  USB VID:PID=16C0:0489 SER=15821020     # Teensy 4.0 (PJRC, VID 0x16C0)
COM22  USB VID:PID=303A:1001 SER=D8:3B:DA:...  # ESP32-S3 native USB (VID 0x303A)
COM9   USB VID:PID=303A:1001 SER=8C:BF:EA:...  # another ESP32-S3
COM10  USB VID:PID=1FC9:0132 SER=0B03400A     # LPC-Link (NXP)

> fbuild deploy -e teensy40        # no -p
# picks COM22 (ESP32-S3), times out at 180s trying to flash Teensy firmware to an ESP32
deploy error: timeout: command timed out after 180s

Adding -p COM21 works fine and the Teensy flashes in ~16s. So the build/upload path is correct — the only thing wrong is candidate selection.

Ask

When -p is not provided, match the candidate serial ports' USB VID/PID against the env's board family and prefer a port whose VID/PID matches. Concretely:

Family VID(s) to match
Teensy (teensy40, teensy41, teensylc, teensy36, ...) 0x16C0 (PJRC)
ESP32 / ESP32-S2/S3/C3/C6/H2/P4 native-USB envs 0x303A (Espressif)
Arduino UNO/Mega/Nano-classic (CDC) 0x2341, 0x2A03, 0x1A86 (CH340 clones), 0x10C4 (CP210x), 0x0403 (FTDI)
NXP LPC-Link / mbed CDC 0x1FC9, 0x0D28
RP2040 (USB CDC) 0x2E8A

Selection rules:

  1. If exactly one attached port matches the env's family → pick it.
  2. If more than one matches → emit a warning listing the matches and either: (a) ask for -p, or (b) pick the first deterministically (port name sort) but log loudly.
  3. If none match → fall back to current behavior, but log a warning like "no port matched VID/PID for env=teensy40 (expected 0x16C0); falling back to COM22".
  4. Explicit -p COMx always wins, unchanged.

Nice-to-haves

  • fbuild devices (or fbuild deploy --list-ports) that prints each port's VID:PID, serial, description, matched-envs so users can see what fbuild would pick for a given env.
  • Per-board override in platformio.ini (or fbuild's own config) so weird boards / dev kits can declare their VID/PID without code changes.

Repro env

  • Host: Windows 10, fbuild bundled in FastLED .venv\Scripts\fbuild.exe
  • Project: FastLED/FastLED master (fastled3 checkout)
  • Attached: Teensy 4.0 + 2× ESP32-S3 + LPC-Link, all on USB
  • Triggered by: bash autoresearch teensy40 --object-fled (autoresearch shells out to fbuild deploy -e teensy40 with no -p)

Filed at the user's request after the wrong-port pick wasted a 180 s timeout. Happy to send a PR if there's appetite for one.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status
    Triage

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions