feature: Detect board port change after upload (#2253)

* UploadResponse now has 'oneof' clause for better API design

* Added scaffolding to return updated-port after upload

* Upload port change detection (first draft)

* Simplified port detection using a Future-style abstraction

* Perform watcher-flush higher in the call tree

* Do not infer upload port if 'upload.wait_for_upload_port' is false

* Further simplified port detection subroutine structure

* fixed linter issue

* Always return an updatedUploadPort.

Arduino CLI should always return the port after an upload, even in the case
where no port change is expected. The consumer shouldn't be required to
implement "if not updated_upload_port, use original port" logic.

The whole point is that all the logic for determining which port should be
selected after an upload should be implemented in Arduino CLI. The consumer
should be able to simply select the port Arduino CLI tells it to select in
all cases.

* Updated docs

* Perform a deep-copy of upload ports where needed.

Previously only the pointer was copied, thus making changes in
`actualPort` to be reflected also to `port`. This lead to some weird
result in the `updatedUploadPort` result:

{
  "stdout": "Verify 11344 bytes of flash with checksum.\nVerify successful\ndone in 0.010 seconds\nCPU reset.\n",
  "stderr": "",
  "updated_upload_port": {
    "address": "/dev/tty.usbmodem14101",     <------- this address...
    "label": "/dev/cu.usbmodem14101",        <------- ...is different from the label
    "protocol": "serial",
    "protocol_label": "Serial Port (USB)",
    "properties": {
      "pid": "0x804E",
      "serialNumber": "94A3397C5150435437202020FF150838",
      "vid": "0x2341"
    },
    "hardware_id": "94A3397C5150435437202020FF150838"
  }
}

* When updating `actualPort` address, update also the address label.

* Fixed some potential nil pointer exceptions

* Further simplified board watcher

We must acesss the gRPC API only until we cross the `command` package
border. Once we are inside the `command` package we should use the
internal API only.

* Before returning from upload, check if the port is still alive

Now the upload detects cases when the upload port is "unstable", i.e.
the port changes even if it shouldn't (because the wait_for_upload_port
property in boards.txt is set to false).

This change should make the upload process more resilient.

* Apply suggestions from code review

Co-authored-by: per1234 <[email protected]>

* Fixed nil exception

* Improved tracking algorithm for upload-port reconnection

The new algorithm takes into account the case where a single board may
expose multiple ports, in this case the selection will increase priority
to ports that:

  1. have the same HW id as the user specified port for upload
  2. have the same protocol as the user specified port for upload
  3. have the same address as the user specified port for upload

---------

Co-authored-by: per1234 <[email protected]>

Author: cmaglie

arduino/discovery/discovery.go

@@ -97,6 +97,12 @@ type Port struct {
 
 var tr = i18n.Tr
 
+// Equals returns true if the given port has the same address and protocol
+// of the current port.
+func (p *Port) Equals(o *Port) bool {
+	return p.Address == o.Address && p.Protocol == o.Protocol
+}
+
 // ToRPC converts Port into rpc.Port
 func (p *Port) ToRPC() *rpc.Port {
 	props := p.Properties
@@ -113,13 +119,43 @@ func (p *Port) ToRPC() *rpc.Port {
 	}
 }
 
+// PortFromRPCPort converts an *rpc.Port to a *Port
+func PortFromRPCPort(o *rpc.Port) (p *Port) {
+	if o == nil {
+		return nil
+	}
+	res := &Port{
+		Address:       o.Address,
+		AddressLabel:  o.Label,
+		Protocol:      o.Protocol,
+		ProtocolLabel: o.ProtocolLabel,
+		HardwareID:    o.HardwareId,
+	}
+	if o.Properties != nil {
+		res.Properties = properties.NewFromHashmap(o.Properties)
+	}
+	return res
+}
+
 func (p *Port) String() string {
 	if p == nil {
 		return "none"
 	}
 	return p.Address
 }
 
+// Clone creates a copy of this Port
+func (p *Port) Clone() *Port {
+	if p == nil {
+		return nil
+	}
+	var res Port = *p
+	if p.Properties != nil {
+		res.Properties = p.Properties.Clone()
+	}
+	return &res
+}
+
 // Event is a pluggable discovery event
 type Event struct {
 	Type        string

arduino/discovery/discovery_client/main.go

@@ -51,10 +51,12 @@ func main() {
 		fmt.Printf("   Address: %s\n", port.Address)
 		fmt.Printf("  Protocol: %s\n", port.Protocol)
 		if ev.Type == "add" {
-			keys := port.Properties.Keys()
-			sort.Strings(keys)
-			for _, k := range keys {
-				fmt.Printf("            %s=%s\n", k, port.Properties.Get(k))
+			if port.Properties != nil {
+				keys := port.Properties.Keys()
+				sort.Strings(keys)
+				for _, k := range keys {
+					fmt.Printf("            %s=%s\n", k, port.Properties.Get(k))
+				}
 			}
 		}
 		fmt.Println()

commands/board/list.go

@@ -34,6 +34,7 @@ import (
 	"github.com/arduino/arduino-cli/commands"
 	"github.com/arduino/arduino-cli/internal/inventory"
 	rpc "github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1"
+	"github.com/arduino/go-properties-orderedmap"
 	"github.com/pkg/errors"
 	"github.com/sirupsen/logrus"
 )
@@ -128,20 +129,22 @@ func apiByVidPid(vid, pid string) ([]*rpc.BoardListItem, error) {
 	}, nil
 }
 
-func identifyViaCloudAPI(port *discovery.Port) ([]*rpc.BoardListItem, error) {
+func identifyViaCloudAPI(props *properties.Map) ([]*rpc.BoardListItem, error) {
 	// If the port is not USB do not try identification via cloud
-	id := port.Properties
-	if !id.ContainsKey("vid") || !id.ContainsKey("pid") {
+	if !props.ContainsKey("vid") || !props.ContainsKey("pid") {
 		return nil, nil
 	}
 
 	logrus.Debug("Querying builder API for board identification...")
-	return cachedAPIByVidPid(id.Get("vid"), id.Get("pid"))
+	return cachedAPIByVidPid(props.Get("vid"), props.Get("pid"))
 }
 
 // identify returns a list of boards checking first the installed platforms or the Cloud API
 func identify(pme *packagemanager.Explorer, port *discovery.Port) ([]*rpc.BoardListItem, error) {
 	boards := []*rpc.BoardListItem{}
+	if port.Properties == nil {
+		return boards, nil
+	}
 
 	// first query installed cores through the Package Manager
 	logrus.Debug("Querying installed cores for board identification...")
@@ -167,7 +170,7 @@ func identify(pme *packagemanager.Explorer, port *discovery.Port) ([]*rpc.BoardL
 	// if installed cores didn't recognize the board, try querying
 	// the builder API if the board is a USB device port
 	if len(boards) == 0 {
-		items, err := identifyViaCloudAPI(port)
+		items, err := identifyViaCloudAPI(port.Properties)
 		if err != nil {
 			// this is bad, but keep going
 			logrus.WithError(err).Debug("Error querying builder API")

commands/board/list_test.go

@@ -103,10 +103,7 @@ func TestGetByVidPidMalformedResponse(t *testing.T) {
 }
 
 func TestBoardDetectionViaAPIWithNonUSBPort(t *testing.T) {
-	port := &discovery.Port{
-		Properties: properties.NewMap(),
-	}
-	items, err := identifyViaCloudAPI(port)
+	items, err := identifyViaCloudAPI(properties.NewMap())
 	require.NoError(t, err)
 	require.Empty(t, items)
 }

commands/daemon/daemon.go

@@ -297,15 +297,27 @@ func (s *ArduinoCoreServerImpl) PlatformList(ctx context.Context, req *rpc.Platf
 // Upload FIXMEDOC
 func (s *ArduinoCoreServerImpl) Upload(req *rpc.UploadRequest, stream rpc.ArduinoCoreService_UploadServer) error {
 	syncSend := NewSynchronizedSend(stream.Send)
-	outStream := feedStreamTo(func(data []byte) { syncSend.Send(&rpc.UploadResponse{OutStream: data}) })
-	errStream := feedStreamTo(func(data []byte) { syncSend.Send(&rpc.UploadResponse{ErrStream: data}) })
-	err := upload.Upload(stream.Context(), req, outStream, errStream)
+	outStream := feedStreamTo(func(data []byte) {
+		syncSend.Send(&rpc.UploadResponse{
+			Message: &rpc.UploadResponse_OutStream{OutStream: data},
+		})
+	})
+	errStream := feedStreamTo(func(data []byte) {
+		syncSend.Send(&rpc.UploadResponse{
+			Message: &rpc.UploadResponse_ErrStream{ErrStream: data},
+		})
+	})
+	res, err := upload.Upload(stream.Context(), req, outStream, errStream)
 	outStream.Close()
 	errStream.Close()
-	if err != nil {
-		return convertErrorToRPCStatus(err)
+	if res != nil {
+		syncSend.Send(&rpc.UploadResponse{
+			Message: &rpc.UploadResponse_Result{
+				Result: res,
+			},
+		})
 	}
-	return nil
+	return convertErrorToRPCStatus(err)
 }
 
 // UploadUsingProgrammer FIXMEDOC

commands/upload/burnbootloader.go

@@ -39,7 +39,7 @@ func BurnBootloader(ctx context.Context, req *rpc.BurnBootloaderRequest, outStre
 	}
 	defer release()
 
-	err := runProgramAction(
+	_, err := runProgramAction(
 		pme,
 		nil, // sketch
 		"",  // importFile

commands/upload/upload.go

@@ -21,16 +21,19 @@ import (
 	"io"
 	"path/filepath"
 	"strings"
+	"time"
 
 	"github.com/arduino/arduino-cli/arduino"
 	"github.com/arduino/arduino-cli/arduino/cores"
 	"github.com/arduino/arduino-cli/arduino/cores/packagemanager"
+	"github.com/arduino/arduino-cli/arduino/discovery"
 	"github.com/arduino/arduino-cli/arduino/globals"
 	"github.com/arduino/arduino-cli/arduino/serialutils"
 	"github.com/arduino/arduino-cli/arduino/sketch"
 	"github.com/arduino/arduino-cli/commands"
 	"github.com/arduino/arduino-cli/executils"
 	"github.com/arduino/arduino-cli/i18n"
+	f "github.com/arduino/arduino-cli/internal/algorithms"
 	rpc "github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1"
 	paths "github.com/arduino/go-paths-helper"
 	properties "github.com/arduino/go-properties-orderedmap"
@@ -123,24 +126,24 @@ func getUserFields(toolID string, platformRelease *cores.PlatformRelease) []*rpc
 }
 
 // Upload FIXMEDOC
-func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, errStream io.Writer) error {
+func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, errStream io.Writer) (*rpc.UploadResult, error) {
 	logrus.Tracef("Upload %s on %s started", req.GetSketchPath(), req.GetFqbn())
 
 	// TODO: make a generic function to extract sketch from request
 	// and remove duplication in commands/compile.go
 	sketchPath := paths.New(req.GetSketchPath())
 	sk, err := sketch.New(sketchPath)
 	if err != nil && req.GetImportDir() == "" && req.GetImportFile() == "" {
-		return &arduino.CantOpenSketchError{Cause: err}
+		return nil, &arduino.CantOpenSketchError{Cause: err}
 	}
 
-	pme, release := commands.GetPackageManagerExplorer(req)
+	pme, pmeRelease := commands.GetPackageManagerExplorer(req)
 	if pme == nil {
-		return &arduino.InvalidInstanceError{}
+		return nil, &arduino.InvalidInstanceError{}
 	}
-	defer release()
+	defer pmeRelease()
 
-	if err := runProgramAction(
+	updatedPort, err := runProgramAction(
 		pme,
 		sk,
 		req.GetImportFile(),
@@ -155,11 +158,14 @@ func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, er
 		errStream,
 		req.GetDryRun(),
 		req.GetUserFields(),
-	); err != nil {
-		return err
+	)
+	if err != nil {
+		return nil, err
 	}
 
-	return nil
+	return &rpc.UploadResult{
+		UpdatedUploadPort: updatedPort,
+	}, nil
 }
 
 // UsingProgrammer FIXMEDOC
@@ -169,7 +175,7 @@ func UsingProgrammer(ctx context.Context, req *rpc.UploadUsingProgrammerRequest,
 	if req.GetProgrammer() == "" {
 		return &arduino.MissingProgrammerError{}
 	}
-	err := Upload(ctx, &rpc.UploadRequest{
+	_, err := Upload(ctx, &rpc.UploadRequest{
 		Instance:   req.GetInstance(),
 		SketchPath: req.GetSketchPath(),
 		ImportFile: req.GetImportFile(),
@@ -186,36 +192,38 @@ func UsingProgrammer(ctx context.Context, req *rpc.UploadUsingProgrammerRequest,
 
 func runProgramAction(pme *packagemanager.Explorer,
 	sk *sketch.Sketch,
-	importFile, importDir, fqbnIn string, port *rpc.Port,
+	importFile, importDir, fqbnIn string, userPort *rpc.Port,
 	programmerID string,
 	verbose, verify, burnBootloader bool,
 	outStream, errStream io.Writer,
-	dryRun bool, userFields map[string]string) error {
-
-	if burnBootloader && programmerID == "" {
-		return &arduino.MissingProgrammerError{}
-	}
+	dryRun bool, userFields map[string]string,
+) (*rpc.Port, error) {
+	port := discovery.PortFromRPCPort(userPort)
 	if port == nil || (port.Address == "" && port.Protocol == "") {
 		// For no-port uploads use "default" protocol
-		port = &rpc.Port{Protocol: "default"}
+		port = &discovery.Port{Protocol: "default"}
 	}
 	logrus.WithField("port", port).Tracef("Upload port")
 
+	if burnBootloader && programmerID == "" {
+		return nil, &arduino.MissingProgrammerError{}
+	}
+
 	fqbn, err := cores.ParseFQBN(fqbnIn)
 	if err != nil {
-		return &arduino.InvalidFQBNError{Cause: err}
+		return nil, &arduino.InvalidFQBNError{Cause: err}
 	}
 	logrus.WithField("fqbn", fqbn).Tracef("Detected FQBN")
 
 	// Find target board and board properties
 	_, boardPlatform, board, boardProperties, buildPlatform, err := pme.ResolveFQBN(fqbn)
 	if boardPlatform == nil {
-		return &arduino.PlatformNotFoundError{
+		return nil, &arduino.PlatformNotFoundError{
 			Platform: fmt.Sprintf("%s:%s", fqbn.Package, fqbn.PlatformArch),
 			Cause:    err,
 		}
 	} else if err != nil {
-		return &arduino.UnknownFQBNError{Cause: err}
+		return nil, &arduino.UnknownFQBNError{Cause: err}
 	}
 	logrus.
 		WithField("boardPlatform", boardPlatform).
@@ -232,7 +240,7 @@ func runProgramAction(pme *packagemanager.Explorer,
 			programmer = buildPlatform.Programmers[programmerID]
 		}
 		if programmer == nil {
-			return &arduino.ProgrammerNotFoundError{Programmer: programmerID}
+			return nil, &arduino.ProgrammerNotFoundError{Programmer: programmerID}
 		}
 	}
 
@@ -253,7 +261,7 @@ func runProgramAction(pme *packagemanager.Explorer,
 	}
 	uploadToolID, err := getToolID(props, action, port.Protocol)
 	if err != nil {
-		return err
+		return nil, err
 	}
 
 	var uploadToolPlatform *cores.PlatformRelease
@@ -268,7 +276,7 @@ func runProgramAction(pme *packagemanager.Explorer,
 		Trace("Upload tool")
 
 	if split := strings.Split(uploadToolID, ":"); len(split) > 2 {
-		return &arduino.InvalidPlatformPropertyError{
+		return nil, &arduino.InvalidPlatformPropertyError{
 			Property: fmt.Sprintf("%s.tool.%s", action, port.Protocol), // TODO: Can be done better, maybe inline getToolID(...)
 			Value:    uploadToolID}
 	} else if len(split) == 2 {
@@ -277,12 +285,12 @@ func runProgramAction(pme *packagemanager.Explorer,
 			PlatformArchitecture: boardPlatform.Platform.Architecture,
 		})
 		if p == nil {
-			return &arduino.PlatformNotFoundError{Platform: split[0] + ":" + boardPlatform.Platform.Architecture}
+			return nil, &arduino.PlatformNotFoundError{Platform: split[0] + ":" + boardPlatform.Platform.Architecture}
 		}
 		uploadToolID = split[1]
 		uploadToolPlatform = pme.GetInstalledPlatformRelease(p)
 		if uploadToolPlatform == nil {
-			return &arduino.PlatformNotFoundError{Platform: split[0] + ":" + boardPlatform.Platform.Architecture}
+			return nil, &arduino.PlatformNotFoundError{Platform: split[0] + ":" + boardPlatform.Platform.Architecture}
 		}
 	}
 
@@ -309,7 +317,7 @@ func runProgramAction(pme *packagemanager.Explorer,
 	}
 
 	if !uploadProperties.ContainsKey("upload.protocol") && programmer == nil {
-		return &arduino.ProgrammerRequiredForUploadError{}
+		return nil, &arduino.ProgrammerRequiredForUploadError{}
 	}
 
 	// Set properties for verbose upload
@@ -357,18 +365,35 @@ func runProgramAction(pme *packagemanager.Explorer,
 	if !burnBootloader {
 		importPath, sketchName, err := determineBuildPathAndSketchName(importFile, importDir, sk, fqbn)
 		if err != nil {
-			return &arduino.NotFoundError{Message: tr("Error finding build artifacts"), Cause: err}
+			return nil, &arduino.NotFoundError{Message: tr("Error finding build artifacts"), Cause: err}
 		}
 		if !importPath.Exist() {
-			return &arduino.NotFoundError{Message: tr("Compiled sketch not found in %s", importPath)}
+			return nil, &arduino.NotFoundError{Message: tr("Compiled sketch not found in %s", importPath)}
 		}
 		if !importPath.IsDir() {
-			return &arduino.NotFoundError{Message: tr("Expected compiled sketch in directory %s, but is a file instead", importPath)}
+			return nil, &arduino.NotFoundError{Message: tr("Expected compiled sketch in directory %s, but is a file instead", importPath)}
 		}
 		uploadProperties.SetPath("build.path", importPath)
 		uploadProperties.Set("build.project_name", sketchName)
 	}
 
+	// This context is kept alive for the entire duration of the upload
+	uploadCtx, uploadCompleted := context.WithCancel(context.Background())
+	defer uploadCompleted()
+
+	// Start the upload port change detector.
+	watcher, err := pme.DiscoveryManager().Watch()
+	if err != nil {
+		return nil, err
+	}
+	defer watcher.Close()
+	updatedUploadPort := f.NewFuture[*discovery.Port]()
+	go detectUploadPort(
+		uploadCtx,
+		port, watcher.Feed(),
+		uploadProperties.GetBoolean("upload.wait_for_upload_port"),
+		updatedUploadPort)
+
 	// Force port wait to make easier to unbrick boards like the Arduino Leonardo, or similar with native USB,
 	// when a sketch causes a crash and the native USB serial port is lost.
 	// See https://github.com/arduino/arduino-cli/issues/1943 for the details.
@@ -385,7 +410,7 @@ func runProgramAction(pme *packagemanager.Explorer,
 
 	// If not using programmer perform some action required
 	// to set the board in bootloader mode
-	actualPort := port
+	actualPort := port.Clone()
 	if programmer == nil && !burnBootloader && (port.Protocol == "serial" || forcedSerialPortWait) {
 		// Perform reset via 1200bps touch if requested and wait for upload port also if requested.
 		touch := uploadProperties.GetBoolean("upload.use_1200bps_touch")
@@ -439,6 +464,7 @@ func runProgramAction(pme *packagemanager.Explorer,
 		} else {
 			if newPortAddress != "" {
 				actualPort.Address = newPortAddress
+				actualPort.AddressLabel = newPortAddress
 			}
 		}
 	}
@@ -455,34 +481,144 @@ func runProgramAction(pme *packagemanager.Explorer,
 
 	// Get Port properties gathered using pluggable discovery
 	uploadProperties.Set("upload.port.address", port.Address)
-	uploadProperties.Set("upload.port.label", port.Label)
+	uploadProperties.Set("upload.port.label", port.AddressLabel)
 	uploadProperties.Set("upload.port.protocol", port.Protocol)
 	uploadProperties.Set("upload.port.protocolLabel", port.ProtocolLabel)
-	for prop, value := range actualPort.Properties {
-		uploadProperties.Set(fmt.Sprintf("upload.port.properties.%s", prop), value)
+	if actualPort.Properties != nil {
+		for prop, value := range actualPort.Properties.AsMap() {
+			uploadProperties.Set(fmt.Sprintf("upload.port.properties.%s", prop), value)
+		}
 	}
 
 	// Run recipes for upload
 	toolEnv := pme.GetEnvVarsForSpawnedProcess()
 	if burnBootloader {
 		if err := runTool("erase.pattern", uploadProperties, outStream, errStream, verbose, dryRun, toolEnv); err != nil {
-			return &arduino.FailedUploadError{Message: tr("Failed chip erase"), Cause: err}
+			return nil, &arduino.FailedUploadError{Message: tr("Failed chip erase"), Cause: err}
 		}
 		if err := runTool("bootloader.pattern", uploadProperties, outStream, errStream, verbose, dryRun, toolEnv); err != nil {
-			return &arduino.FailedUploadError{Message: tr("Failed to burn bootloader"), Cause: err}
+			return nil, &arduino.FailedUploadError{Message: tr("Failed to burn bootloader"), Cause: err}
 		}
 	} else if programmer != nil {
 		if err := runTool("program.pattern", uploadProperties, outStream, errStream, verbose, dryRun, toolEnv); err != nil {
-			return &arduino.FailedUploadError{Message: tr("Failed programming"), Cause: err}
+			return nil, &arduino.FailedUploadError{Message: tr("Failed programming"), Cause: err}
 		}
 	} else {
 		if err := runTool("upload.pattern", uploadProperties, outStream, errStream, verbose, dryRun, toolEnv); err != nil {
-			return &arduino.FailedUploadError{Message: tr("Failed uploading"), Cause: err}
+			return nil, &arduino.FailedUploadError{Message: tr("Failed uploading"), Cause: err}
 		}
 	}
 
+	uploadCompleted()
 	logrus.Tracef("Upload successful")
-	return nil
+
+	updatedPort := updatedUploadPort.Await()
+	if updatedPort == nil {
+		return nil, nil
+	}
+	return updatedPort.ToRPC(), nil
+}
+
+func detectUploadPort(
+	uploadCtx context.Context,
+	uploadPort *discovery.Port, watch <-chan *discovery.Event,
+	waitForUploadPort bool,
+	result f.Future[*discovery.Port],
+) {
+	log := logrus.WithField("task", "port_detection")
+	log.Tracef("Detecting new board port after upload")
+
+	candidate := uploadPort.Clone()
+	defer func() {
+		result.Send(candidate)
+	}()
+
+	// Ignore all events during the upload
+	for {
+		select {
+		case ev, ok := <-watch:
+			if !ok {
+				log.Error("Upload port detection failed, watcher closed")
+				return
+			}
+			if candidate != nil && ev.Type == "remove" && ev.Port.Equals(candidate) {
+				log.WithField("event", ev).Trace("User-specified port has been disconnected, forcing wait for upload port")
+				waitForUploadPort = true
+				candidate = nil
+			} else {
+				log.WithField("event", ev).Trace("Ignored watcher event before upload")
+			}
+			continue
+		case <-uploadCtx.Done():
+			// Upload completed, move to the next phase
+		}
+		break
+	}
+
+	// Pick the first port that is detected after the upload
+	timeout := time.After(5 * time.Second)
+	if !waitForUploadPort {
+		timeout = time.After(time.Second)
+	}
+	for {
+		select {
+		case ev, ok := <-watch:
+			if !ok {
+				log.Error("Upload port detection failed, watcher closed")
+				return
+			}
+			if candidate != nil && ev.Type == "remove" && candidate.Equals(ev.Port) {
+				log.WithField("event", ev).Trace("Candidate port is no longer available")
+				candidate = nil
+				if !waitForUploadPort {
+					waitForUploadPort = true
+					timeout = time.After(5 * time.Second)
+					log.Trace("User-specified port has been disconnected, now waiting for upload port, timeout extended by 5 seconds")
+				}
+				continue
+			}
+			if ev.Type != "add" {
+				log.WithField("event", ev).Trace("Ignored non-add event")
+				continue
+			}
+
+			portPriority := func(port *discovery.Port) int {
+				if port == nil {
+					return 0
+				}
+				prio := 0
+				if port.HardwareID == uploadPort.HardwareID {
+					prio += 1000
+				}
+				if port.Protocol == uploadPort.Protocol {
+					prio += 100
+				}
+				if port.Address == uploadPort.Address {
+					prio += 10
+				}
+				return prio
+			}
+			evPortPriority := portPriority(ev.Port)
+			candidatePriority := portPriority(candidate)
+			if evPortPriority <= candidatePriority {
+				log.WithField("event", ev).Tracef("New upload port candidate is worse than the current one (prio=%d)", evPortPriority)
+				continue
+			}
+			log.WithField("event", ev).Tracef("Found new upload port candidate (prio=%d)", evPortPriority)
+			candidate = ev.Port
+
+			// If the current candidate have the desired HW-ID return it quickly.
+			if candidate.HardwareID == ev.Port.HardwareID {
+				timeout = time.After(time.Second)
+				log.Trace("New candidate port match the desired HW ID, timeout reduced to 1 second.")
+				continue
+			}
+
+		case <-timeout:
+			log.WithField("selected_port", candidate).Trace("Timeout waiting for candidate port")
+			return
+		}
+	}
 }
 
 func runTool(recipeID string, props *properties.Map, outStream, errStream io.Writer, verbose bool, dryRun bool, toolEnv []string) error {

commands/upload/upload_test.go

@@ -184,7 +184,7 @@ func TestUploadPropertiesComposition(t *testing.T) {
 	testRunner := func(t *testing.T, test test, verboseVerify bool) {
 		outStream := &bytes.Buffer{}
 		errStream := &bytes.Buffer{}
-		err := runProgramAction(
+		_, err := runProgramAction(
 			pme,
 			nil,                     // sketch
 			"",                      // importFile

docs/UPGRADING.md

@@ -4,6 +4,58 @@ Here you can find a list of migration guides to handle breaking changes between
 
 ## 0.34.0
 
+### The gRPC `cc.arduino.cli.commands.v1.UploadRepsonse` command response has been changed.
+
+Previously the `UploadResponse` was used only to stream the tool output:
+
+```
+message UploadResponse {
+  // The output of the upload process.
+  bytes out_stream = 1;
+  // The error output of the upload process.
+  bytes err_stream = 2;
+}
+```
+
+Now the API logic has been clarified using the `oneof` clause and another field has been added providing an
+`UploadResult` message that is sent when a successful upload completes.
+
+```
+message UploadResponse {
+  oneof message {
+    // The output of the upload process.
+    bytes out_stream = 1;
+    // The error output of the upload process.
+    bytes err_stream = 2;
+    // The upload result
+    UploadResult result = 3;
+  }
+}
+
+message UploadResult {
+  // When a board requires a port disconnection to perform the upload, this
+  // field returns the port where the board reconnects after the upload.
+  Port updated_upload_port = 1;
+}
+```
+
+### golang API: method `github.com/arduino/arduino-cli/commands/upload.Upload` changed signature
+
+The `Upload` method signature has been changed from:
+
+```go
+func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, errStream io.Writer) error { ... }
+```
+
+to:
+
+```go
+func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, errStream io.Writer) (*rpc.UploadResult, error) { ... }
+```
+
+Now an `UploadResult` structure is returned together with the error. If you are not interested in the information
+contained in the structure you can safely ignore it.
+
 ### golang package `github.com/arduino/arduino-cli/inventory` removed from public API
 
 The package `inventory` is no more a public golang API.

internal/algorithms/channels.go

@@ -0,0 +1,55 @@
+// This file is part of arduino-cli.
+//
+// Copyright 2023 ARDUINO SA (http://www.arduino.cc/)
+//
+// This software is released under the GNU General Public License version 3,
+// which covers the main part of arduino-cli.
+// The terms of this license can be found at:
+// https://www.gnu.org/licenses/gpl-3.0.en.html
+//
+// You can be released from the requirements of the above licenses by purchasing
+// a commercial license. Buying such a license is mandatory if you want to
+// modify or otherwise use the software for commercial activities involving the
+// Arduino software without disclosing the source code of your own applications.
+// To purchase a commercial license, send an email to license@arduino.cc.
+
+package f
+
+import "sync"
+
+// DiscardCh consumes all incoming messages from the given channel until it's closed.
+func DiscardCh[T any](ch <-chan T) {
+	for range ch {
+	}
+}
+
+// Future is an object that holds a result value. The value may be read and
+// written asynchronously.
+type Future[T any] interface {
+	Send(T)
+	Await() T
+}
+
+type future[T any] struct {
+	wg    sync.WaitGroup
+	value T
+}
+
+// NewFuture creates a new Future[T]
+func NewFuture[T any]() Future[T] {
+	res := &future[T]{}
+	res.wg.Add(1)
+	return res
+}
+
+// Send a result in the Future. Threads waiting for result will be unlocked.
+func (f *future[T]) Send(value T) {
+	f.value = value
+	f.wg.Done()
+}
+
+// Await for a result from the Future, blocks until a result is available.
+func (f *future[T]) Await() T {
+	f.wg.Wait()
+	return f.value
+}

internal/cli/compile/compile.go

@@ -236,6 +236,8 @@ func runCompileCommand(cmd *cobra.Command, args []string) {
 		DoNotExpandBuildProperties:    showProperties == arguments.ShowPropertiesUnexpanded,
 	}
 	compileRes, compileError := compile.Compile(context.Background(), compileRequest, stdOut, stdErr, nil)
+
+	var uploadRes *rpc.UploadResult
 	if compileError == nil && uploadAfterCompile {
 		userFieldRes, err := upload.SupportedUserFields(context.Background(), &rpc.SupportedUserFieldsRequest{
 			Instance: inst,
@@ -268,8 +270,10 @@ func runCompileCommand(cmd *cobra.Command, args []string) {
 			UserFields: fields,
 		}
 
-		if err := upload.Upload(context.Background(), uploadRequest, stdOut, stdErr); err != nil {
+		if res, err := upload.Upload(context.Background(), uploadRequest, stdOut, stdErr); err != nil {
 			feedback.Fatal(tr("Error during Upload: %v", err), feedback.ErrGeneric)
+		} else {
+			uploadRes = res
 		}
 	}
 
@@ -330,6 +334,7 @@ func runCompileCommand(cmd *cobra.Command, args []string) {
 		CompilerOut:        stdIO.Stdout,
 		CompilerErr:        stdIO.Stderr,
 		BuilderResult:      compileRes,
+		UploadResult:       uploadRes,
 		ProfileOut:         profileOut,
 		Success:            compileError == nil,
 		showPropertiesMode: showProperties,
@@ -375,6 +380,7 @@ type compileResult struct {
 	CompilerOut   string               `json:"compiler_out"`
 	CompilerErr   string               `json:"compiler_err"`
 	BuilderResult *rpc.CompileResponse `json:"builder_result"`
+	UploadResult  *rpc.UploadResult    `json:"upload_result"`
 	Success       bool                 `json:"success"`
 	ProfileOut    string               `json:"profile_out,omitempty"`
 	Error         string               `json:"error,omitempty"`

internal/cli/upload/upload.go

@@ -168,8 +168,31 @@ func runUploadCommand(command *cobra.Command, args []string) {
 		DryRun:     dryRun,
 		UserFields: fields,
 	}
-	if err := upload.Upload(context.Background(), req, stdOut, stdErr); err != nil {
+	if res, err := upload.Upload(context.Background(), req, stdOut, stdErr); err != nil {
 		feedback.FatalError(err, feedback.ErrGeneric)
+	} else {
+		io := stdIOResult()
+		feedback.PrintResult(&uploadResult{
+			Stdout:            io.Stdout,
+			Stderr:            io.Stderr,
+			UpdatedUploadPort: res.UpdatedUploadPort,
+		})
 	}
-	feedback.PrintResult(stdIOResult())
+}
+
+type uploadResult struct {
+	Stdout            string    `json:"stdout"`
+	Stderr            string    `json:"stderr"`
+	UpdatedUploadPort *rpc.Port `json:"updated_upload_port,omitempty"`
+}
+
+func (r *uploadResult) Data() interface{} {
+	return r
+}
+
+func (r *uploadResult) String() string {
+	if r.UpdatedUploadPort == nil {
+		return ""
+	}
+	return tr("New upload port: %[1]s (%[2]s)", r.UpdatedUploadPort.Address, r.UpdatedUploadPort.Protocol)
 }

rpc/cc/arduino/cli/commands/v1/upload.pb.go

@@ -62,10 +62,20 @@ message UploadRequest {
 }
 
 message UploadResponse {
-  // The output of the upload process.
-  bytes out_stream = 1;
-  // The error output of the upload process.
-  bytes err_stream = 2;
+  oneof message {
+    // The output of the upload process.
+    bytes out_stream = 1;
+    // The error output of the upload process.
+    bytes err_stream = 2;
+    // The upload result
+    UploadResult result = 3;
+  }
+}
+
+message UploadResult {
+  // When a board requires a port disconnection to perform the upload, this
+  // field returns the port where the board reconnects after the upload.
+  Port updated_upload_port = 1;
 }
 
 message ProgrammerIsRequiredForUploadError {}