Merge branch 'chore/json-schema' of github.com:arduino/arduino-cli into chore/json-schema

Luca Bianconi · Luca Bianconi · commit ca67a90813fe · 2023-02-16T12:49:10.000+01:00
diff --git a/.github/workflows/release-go-task.yml b/.github/workflows/release-go-task.yml
@@ -253,7 +253,7 @@ jobs:
       - name: Collect proto files
         run: task protoc:collect
 
-      - name: Add configuration jsonschema
+      - name: Add configuration JSON schema
         run: |
           TAG=${{ needs.create-release-artifacts.outputs.version }}
           cp ./configuration/configuration.schema.json ${{ env.DIST_DIR}}/${TAG}-configuration.schema.json
diff --git a/DistTasks.yml b/DistTasks.yml
@@ -253,7 +253,7 @@ tasks:
       PACKAGE_NAME: "{{.PROJECT_NAME}}_{{.VERSION}}_{{.PACKAGE_PLATFORM}}.tar.gz"
 
   jsonschema:
-    desc: Copy the jsonschema to dist folder
+    desc: Copy the JSON schema to dist folder
     cmds:
       - mkdir --parents {{.DIST_DIR}}
       - cp ./configuration/configuration.schema.json {{.DIST_DIR}}/{{.PROJECT_NAME}}_{{.VERSION}}_configuration.schema.json
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/configuration/configuration.schema.json b/configuration/configuration.schema.json
@@ -107,7 +107,7 @@
         "level": {
           "description": "messages with this level and above will be logged. Valid levels are: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`.",
           "type": "string",
-          "enum": ["trace", "debug", "info", "warn", "error", "fatal"]
+          "enum": ["trace", "debug", "info", "warn", "error", "fatal", "panic"]
         }
       },
       "type": "object"
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 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",
diff --git a/internal/cli/board/list.go b/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"`
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;
 }

Original file line number	Diff line number	Diff line change
`@@ -91,6 +91,7 @@ type Port struct {`
`91`	`91`	AddressLabel string `json:"label"`
`92`	`92`	Protocol string `json:"protocol"`
`93`	`93`	ProtocolLabel string `json:"protocolLabel"`
	`94`	+ HardwareID string `json:"hardwareId,omitempty"`
`94`	`95`	Properties *properties.Map `json:"properties"`
`95`	`96`	`}`
`96`	`97`
`@@ -107,6 +108,7 @@ func (p Port) ToRPC() rpc.Port {`
`107`	`108`	`Label: p.AddressLabel,`
`108`	`109`	`Protocol: p.Protocol,`
`109`	`110`	`ProtocolLabel: p.ProtocolLabel,`
	`111`	`+ HardwareId: p.HardwareID,`
`110`	`112`	`Properties: props.AsMap(),`
`111`	`113`	`}`
`112`	`114`	`}`
Original file line number	Diff line number	Diff line change
`@@ -107,7 +107,7 @@`
`107`	`107`	`"level": {`
`108`	`108`	"description": "messages with this level and above will be logged. Valid levels are: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`.",
`109`	`109`	`"type": "string",`
`110`		`- "enum": ["trace", "debug", "info", "warn", "error", "fatal"]`
	`110`	`+ "enum": ["trace", "debug", "info", "warn", "error", "fatal", "panic"]`
`111`	`111`	`}`
`112`	`112`	`},`
`113`	`113`	`"type": "object"`
Original file line number	Diff line number	Diff line change
`@@ -31,4 +31,6 @@ message Port {`
`31`	`31`	`string protocol_label = 4;`
`32`	`32`	`// A set of properties of the port`
`33`	`33`	`map<string, string> properties = 5;`
	`34`	`+ // The hardware ID (serial number) of the board attached to the port`
	`35`	`+ string hardware_id = 6;`
`34`	`36`	`}`