Added 'hardwareId' support to pluggable discovery (#2065)

* Added 'hardwareId' support to pluggable discovery

* Added hardwareId output in 'board list -w' too

* Update docs/pluggable-discovery-specification.md

Co-authored-by: Luca Bianconi <[email protected]>

---------

Co-authored-by: Luca Bianconi <[email protected]>

Author: cmaglie

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(),
 	}
 }

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",

internal/cli/board/list.go

@@ -105,6 +105,7 @@ func watchList(cmd *cobra.Command, inst *rpc.Instance) {
 			Address:       event.Port.Port.Address,
 			Protocol:      event.Port.Port.Protocol,
 			ProtocolLabel: event.Port.Port.ProtocolLabel,
+			HardwareID:    event.Port.Port.HardwareId,
 			Properties:    event.Port.Port.Properties,
 			Boards:        event.Port.MatchingBoards,
 			Error:         event.Error,
@@ -181,6 +182,7 @@ type watchEvent struct {
 	Label         string               `json:"label,omitempty"`
 	Protocol      string               `json:"protocol,omitempty"`
 	ProtocolLabel string               `json:"protocol_label,omitempty"`
+	HardwareID    string               `json:"hardwareId,omitempty"`
 	Properties    map[string]string    `json:"properties"`
 	Boards        []*rpc.BoardListItem `json:"boards,omitempty"`
 	Error         string               `json:"error,omitempty"`

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

@@ -31,4 +31,6 @@ message Port {
   string protocol_label = 4;
   // A set of properties of the port
   map<string, string> properties = 5;
+  // The hardware ID (serial number) of the board attached to the port
+  string hardware_id = 6;
 }