Added 'hardwareId' support to pluggable discovery

arduino · cmaglie · Feb 9, 2023 · Feb 6, 2023 · Feb 7, 2023 · Feb 7, 2023
commit c14e2484f2cca50bd67eee2bc1fc92cfde3060eb
diff --git a/arduino/discovery/discovery.go b/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 --git a/docs/pluggable-discovery-specification.md b/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",

diff --git a/rpc/cc/arduino/cli/commands/v1/port.pb.go b/rpc/cc/arduino/cli/commands/v1/port.pb.go
diff --git a/rpc/cc/arduino/cli/commands/v1/port.proto b/rpc/cc/arduino/cli/commands/v1/port.proto
@@ -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;
 }