Added 'hardwareId' support to pluggable discovery

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 SAMPLE
       "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 identify a specific board sample (even among other boards of the same
+  model). Different ports with the same `hardwareId` must belong to the same board sample. The identifier should be
+  sufficiently long to uniquely identify the board sample 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,8 @@ 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 sample.
+
 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 +243,7 @@ The `add` event looks like the following:
   "port": {
     "address": "/dev/ttyACM0",
     "label": "ttyACM0",
+    "hardwareId": "EBEABFD6514D32364E202020FF10181E",
     "properties": {
       "pid": "0x804e",
       "vid": "0x2341",

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;
 }