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:
- If exactly one attached port matches the env's family → pick it.
- 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.
- 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".
- 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.
Symptom
When multiple devices are attached and no
-p/--portis 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:Adding
-p COM21works fine and the Teensy flashes in ~16s. So the build/upload path is correct — the only thing wrong is candidate selection.Ask
When
-pis 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:teensy40,teensy41,teensylc,teensy36, ...)0x16C0(PJRC)0x303A(Espressif)0x2341,0x2A03,0x1A86(CH340 clones),0x10C4(CP210x),0x0403(FTDI)0x1FC9,0x0D280x2E8ASelection rules:
-p, or (b) pick the first deterministically (port name sort) but log loudly.-p COMxalways wins, unchanged.Nice-to-haves
fbuild devices(orfbuild deploy --list-ports) that prints each port'sVID:PID, serial, description, matched-envsso users can see what fbuild would pick for a given env.platformio.ini(or fbuild's own config) so weird boards / dev kits can declare their VID/PID without code changes.Repro env
.venv\Scripts\fbuild.exeFastLED/FastLEDmaster (fastled3checkout)bash autoresearch teensy40 --object-fled(autoresearch shells out tofbuild deploy -e teensy40with 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.