Merge branch 'master' into discoveries_fix

Author: Bikappa

Diff for: arduino/discovery/discovery.go

@@ -91,6 +91,7 @@ type Port struct {
 	AddressLabel  string          `json:"label"`
 	Protocol      string          `json:"protocol"`
 	ProtocolLabel string          `json:"protocolLabel"`
+	HardwareID    string          `json:"hardwareId,omitempty"`
 	Properties    *properties.Map `json:"properties"`
 }
 
@@ -107,6 +108,7 @@ func (p *Port) ToRPC() *rpc.Port {
 		Label:         p.AddressLabel,
 		Protocol:      p.Protocol,
 		ProtocolLabel: p.ProtocolLabel,
+		HardwareId:    p.HardwareID,
 		Properties:    props.AsMap(),
 	}
 }

Diff for: commands/sketch/new.go

@@ -75,14 +75,13 @@ func validateSketchName(name string) error {
 		return &arduino.CantCreateSketchError{Cause: errors.New(tr("sketch name cannot be empty"))}
 	}
 	if len(name) > sketchNameMaxLength {
-		return &arduino.CantCreateSketchError{Cause: errors.New(tr("sketch name too long (%d characters). Maximum allowed length is %d",
+		return &arduino.CantCreateSketchError{Cause: errors.New(tr("sketch name too long (%[1]d characters). Maximum allowed length is %[2]d",
 			len(name),
 			sketchNameMaxLength))}
 	}
 	if !sketchNameValidationRegex.MatchString(name) {
-		return &arduino.CantCreateSketchError{Cause: errors.New(tr("invalid sketch name \"%s\". Required pattern %s",
-			name,
-			sketchNameValidationRegex.String()))}
+		return &arduino.CantCreateSketchError{Cause: errors.New(tr(`invalid sketch name "%[1]s": the first character must be alphanumeric, the following ones can also contain "_", "-", and ".".`,
+			name))}
 	}
 	return nil
 }

Diff for: commands/sketch/new_test.go

@@ -2,6 +2,7 @@ package sketch
 
 import (
 	"context"
+	"fmt"
 	"testing"
 
 	"github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1"
@@ -11,7 +12,6 @@ import (
 func Test_SketchNameWrongPattern(t *testing.T) {
 	invalidNames := []string{
 		"&",
-		"",
 		".hello",
 		"_hello",
 		"-hello",
@@ -24,11 +24,9 @@ func Test_SketchNameWrongPattern(t *testing.T) {
 			SketchName: name,
 			SketchDir:  t.TempDir(),
 		})
-		require.NotNil(t, err)
 
-		require.Error(t, err, `Can't create sketch: invalid sketch name "%s". Required pattern %s`,
-			name,
-			sketchNameValidationRegex)
+		require.EqualError(t, err, fmt.Sprintf(`Can't create sketch: invalid sketch name "%s": the first character must be alphanumeric, the following ones can also contain "_", "-", and ".".`,
+			name))
 	}
 }
 
@@ -38,9 +36,8 @@ func Test_SketchNameEmpty(t *testing.T) {
 		SketchName: emptyName,
 		SketchDir:  t.TempDir(),
 	})
-	require.NotNil(t, err)
 
-	require.Error(t, err, `Can't create sketch: sketch name cannot be empty`)
+	require.EqualError(t, err, `Can't create sketch: sketch name cannot be empty`)
 }
 
 func Test_SketchNameTooLong(t *testing.T) {
@@ -52,11 +49,10 @@ func Test_SketchNameTooLong(t *testing.T) {
 		SketchName: string(tooLongName),
 		SketchDir:  t.TempDir(),
 	})
-	require.NotNil(t, err)
 
-	require.Error(t, err, `Can't create sketch: sketch name too long (%d characters). Maximum allowed length is %d`,
+	require.EqualError(t, err, fmt.Sprintf(`Can't create sketch: sketch name too long (%d characters). Maximum allowed length is %d`,
 		len(tooLongName),
-		sketchNameMaxLength)
+		sketchNameMaxLength))
 }
 
 func Test_SketchNameOk(t *testing.T) {

Diff for: docs/pluggable-discovery-specification.md

@@ -127,6 +127,7 @@ call. The format of the response is the following:
       "label":         <-- HOW THE PORT IS DISPLAYED ON THE GUI
       "protocol":      <-- THE PROTOCOL USED BY THE BOARD
       "protocolLabel": <-- HOW THE PROTOCOL IS DISPLAYED ON THE GUI
+      "hardwareId":    <-- A STRING THAT UNIQUELY IDENTIFIES A BOARD INSTANCE
       "properties": {
                        <-- A LIST OF PROPERTIES OF THE PORT
       }
@@ -147,7 +148,15 @@ Each port has:
   `SSH on 192.168.10.100`)
 - `protocol` is the protocol identifier (such as `serial` or `dfu` or `ssh`)
 - `protocolLabel` is the `protocol` in human readable form (for example `Serial port` or `DFU USB` or `Network (ssh)`)
-- `properties` is a list of key/value pairs that represent information relative to the specific port
+- `hardwareId` (optional) a string that uniquely identifies a specific board instance (even among other boards of the
+  same model). Different ports with the same `hardwareId` must belong to the same board instance. The identifier should
+  be sufficiently long to uniquely identify the board instance and reduce the probability of collisions. Good examples
+  of `hardwareId` values are: Ethernet MAC Address, USB Serial Number, CPU-ID number, etc.
+
+  This value **should not** be used to identify the board **model** (see the
+  [board identification](#board-identification) section for more information about identification of the board model).
+
+- `properties` is a list of key/value pairs that represent information relative to the specific port.
 
 To make the above more clear let's show an example output from the `serial-discovery` builtin in the Arduino CLI:
 
@@ -160,6 +169,7 @@ To make the above more clear let's show an example output from the `serial-disco
       "label": "ttyACM0",
       "protocol": "serial",
       "protocolLabel": "Serial Port (USB)",
+      "hardwareId": "EBEABFD6514D32364E202020FF10181E",
       "properties": {
         "pid": "0x804e",
         "vid": "0x2341",
@@ -175,6 +185,9 @@ In this case the serial port metadata comes from a USB serial converter. Inside
 properties of the port, and some of them may be useful for product identification (in this case only USB VID/PID is
 useful to identify the board model).
 
+The `hardwareId` field is populated with the USB `serialNumber` since this value is useful to identify the board
+instance.
+
 The `LIST` command performs a one-shot polling of the ports. The discovery should answer as soon as reasonably possible,
 without any additional delay.
 
@@ -231,6 +244,7 @@ The `add` event looks like the following:
   "port": {
     "address": "/dev/ttyACM0",
     "label": "ttyACM0",
+    "hardwareId": "EBEABFD6514D32364E202020FF10181E",
     "properties": {
       "pid": "0x804e",
       "vid": "0x2341",