Identify final board port address in machine readable `upload` command response

[per1234]

Describe the request

In some cases, it is possible that the address of the board's port is different at the end of an upload operation. Arduino CLI should identify the final address of the target board's port and provide this information in the machine readable upload command responses:

• Response of the cc.arduino.cli.commands.v1.ArduinoCoreService.Upload method
• Command line output when non-text format is specified

🙂 This information will be useful to consumers of Arduino CLI such as development tools and scripts.

Describe the current behavior

A common scenario under which the port address can change through an upload operation is uploading to a "native USB" board, where the primary microcontroller produces the USB CDC serial port. The typical upload procedure for these boards:

1. Arduino CLI signals to the target board that it should activate the bootloader.
2. The board switches from application into bootloader mode, which causes its CDC serial port to disappear for a short time.
3. Arduino CLI watches for a new port to be discovered.
4. Arduino CLI determines the port to use for the upload and provides it for use in the upload pattern via the upload.port.address property.
   • If a new port was discovered, that port is used.
   • If the timeout was reached without a new discovery, the original port is used as a fallback.
5. Arduino CLI invokes the upload command.
6. The board switches from bootloader to application mode, which causes its CDC serial port to disappear for a short time.

The port address may change following steps (2) and (6) in the above procedure. A system has already been implemented for Arduino CLI to effectively follow the address change after step (2), but there is no such following of the port after step (6). The reason for this is that, unlike the address change at step (2), Arduino CLI itself doesn't have a need to know the final address.

🙁 A final address identification system (which is fairly complex) must be implemented separately in each of the tools that do need this information.

Arduino CLI version

df12786

Operating system

All

Operating system version

Any

Additional context

This is somewhat related to arduino/arduino-ide#1319 in that it would enable the complete removal of automatic port selection code from the Arduino IDE codebase rather than only the partial removal that is required for the resolution of arduino/arduino-ide#1319.

Examples of tools not correctly determining the final port address:

• Following an upload, port selection lost when reset causes port address cycle arduino-ide#1648
• Selection of port lost on upload when protocol other than serial/network and no "recognized" board arduino-ide#1366
• Port changes on native USB upload when two ports are associated with the selected board name arduino-ide#710
• Serial port re-enumerates after upload with SAMD boards (probably other USB native) arduino-ide#287
• Adafruit Trinket M0 won't persist port arduino-ide#82
• Port selection of Portenta H7 (M4 Core) is lost on every upload arduino-ide#43

These issues highlight the value of maintaining a single reliable final port identification system instead of duplicating the effort of implementing the system in each individual downstream project.

Issue checklist

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

[kittaakos]

Once the feature is available and the CLI can provide the new port (if it has changed) after the upload, I propose eliminating the hardwareId from the gRPC API before the 1.0 release. I do not see why this should be exposed to the public. See the downstream change at arduino/arduino-ide#1913:

From here:

This PR has been created to support the "auto-reconnecting" to a board in DFU mode, which the R4 Minima goes into during upload and reset. The primary motivation was to make IDE2 compatible with the Uno R4 board.

Related API:

arduino-cli/rpc/cc/arduino/cli/commands/v1/port.proto

Lines 34 to 35 in 62bb4c4

	// The hardware ID (serial number) of the board attached to the port
	string hardware_id = 6;

I can open a separate issue if it's needed.