feat: Clarify/improve handling of "generic" VID/PID values (or other identifiers)

[Daniel Egnor]

Describe the request

The pluggable discovery specification and platform specification describe how board definitions can give a board's USB VID and PID, or more generally identifiers. This note is given:

The Arduino development software uses the vid and pid properties to automatically identify the boards connected to the computer. This convenience feature isn't available for boards that don't present a unique VID/PID pair.

A lot of boards have "semi generic" VID/PIDs that are derived from a serial converter chip (FT232, CH340, CP2102, etc) OR from the microcontroller's own USB support (e.g. the ESP32 "USB Serial/JTAG" peripheral). They can't be used to reliably identify a board but they CAN generally be used to guide which serial port a given board is connected to.

The various platform boards.txt files out there are quite inconsistent on how they handle this! Some happily list "generic" VID/PID pairs, some only list truly board-specific VID/PID pairs, others are inconsistent and list some of them but not others (espressif/arduino-esp32#9702 vs espressif/arduino-esp32#9690).

Proposal...

• clarify whether boards.txt file should/not list these semi generic identifiers; if "not", maybe try to clean that up
• ideally support generic identifiers as a way to determine which serial port a given board might be on
• have arduino-cli list ALL matching boards, in order? or at least the FIRST matching board, so the first one can be a generic archetype listing (possibly hidden by default)?

Describe the current behavior

When there are multiple known boards that match a given VID/PID, arduino-cli (and thus tools that use it) tend to just kind of pick one at random.

For example, right now my computer (Ubuntu 24.04) has four USB serial ports (/dev/ACM0-3). Three of them are not Arduino boards at all but random devices I'd love to "filter out". The other one is a Seeed XIAO ESP32-C3, with VID:PID 0x303a:0x1001, which is the generic VID:PID for the ESP32-C3's "USB Serial/JTAG" peripheral. A number of boards list that VID/PID, but for whatever reason arduino-cli board list picks one of them (not the first, not the last):

% arduino-cli board list
Port         Protocol Type              Board Name FQBN                 Core
/dev/ttyACM0 serial   Serial Port (USB) Unknown
/dev/ttyACM1 serial   Serial Port (USB) Unknown
/dev/ttyACM2 serial   Serial Port (USB) Unknown
/dev/ttyACM3 serial   Serial Port (USB) LOLIN S3   esp32:esp32:lolin_s3 esp32:esp32

If I ask for JSON output, I get this, which is a bit confusing, because it SEEMS designed to allow multiple matches to be reported:

  {
    "matching_boards": [
      {
        "name": "LOLIN S3",
        "fqbn": "esp32:esp32:lolin_s3"
      }
    ],
    "port": {
      "address": "/dev/ttyACM3",
      "label": "/dev/ttyACM3",
      "protocol": "serial",
      "protocol_label": "Serial Port (USB)",
      "properties": {
        "pid": "0x1001",
        "serialNumber": "A0:76:4E:44:F2:28",
        "vid": "0x303a"
      },
      "hardware_id": "A0:76:4E:44:F2:28"
    }
  },

Arduino CLI version

(applies to all)

Operating system

N/A

Operating system version

(applies to all)

Additional context

Also see the forum thread "What if two different boards has same PID and VID"...

Issue checklist

• I searched for previous requests in the issue tracker
• I verified the feature was still missing when using the nightly build
• My request contains all necessary details