From c14e2484f2cca50bd67eee2bc1fc92cfde3060eb Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Mon, 6 Feb 2023 17:28:55 +0100 Subject: [PATCH 1/3] Added 'hardwareId' support to pluggable discovery --- arduino/discovery/discovery.go | 2 ++ docs/pluggable-discovery-specification.md | 15 ++++++++++- rpc/cc/arduino/cli/commands/v1/port.pb.go | 33 +++++++++++++++-------- rpc/cc/arduino/cli/commands/v1/port.proto | 2 ++ 4 files changed, 40 insertions(+), 12 deletions(-) diff --git a/arduino/discovery/discovery.go b/arduino/discovery/discovery.go index 1de61f3c9bb..4ecd27252e6 100644 --- 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 index 16d196c5bf0..c986bbe530d 100644 --- 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 index baedafdb82e..87da5162d55 100644 --- a/rpc/cc/arduino/cli/commands/v1/port.pb.go +++ b/rpc/cc/arduino/cli/commands/v1/port.pb.go @@ -51,6 +51,8 @@ type Port struct { ProtocolLabel string `protobuf:"bytes,4,opt,name=protocol_label,json=protocolLabel,proto3" json:"protocol_label,omitempty"` // A set of properties of the port Properties map[string]string `protobuf:"bytes,5,rep,name=properties,proto3" json:"properties,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` + // The hardware ID (serial number) of the board attached to the port + HardwareId string `protobuf:"bytes,6,opt,name=hardware_id,json=hardwareId,proto3" json:"hardware_id,omitempty"` } func (x *Port) Reset() { @@ -120,6 +122,13 @@ func (x *Port) GetProperties() map[string]string { return nil } +func (x *Port) GetHardwareId() string { + if x != nil { + return x.HardwareId + } + return "" +} + var File_cc_arduino_cli_commands_v1_port_proto protoreflect.FileDescriptor var file_cc_arduino_cli_commands_v1_port_proto_rawDesc = []byte{ @@ -127,7 +136,7 @@ var file_cc_arduino_cli_commands_v1_port_proto_rawDesc = []byte{ 0x2f, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x73, 0x2f, 0x76, 0x31, 0x2f, 0x70, 0x6f, 0x72, 0x74, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x12, 0x1a, 0x63, 0x63, 0x2e, 0x61, 0x72, 0x64, 0x75, 0x69, 0x6e, 0x6f, 0x2e, 0x63, 0x6c, 0x69, 0x2e, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x73, - 0x2e, 0x76, 0x31, 0x22, 0x8a, 0x02, 0x0a, 0x04, 0x50, 0x6f, 0x72, 0x74, 0x12, 0x18, 0x0a, 0x07, + 0x2e, 0x76, 0x31, 0x22, 0xab, 0x02, 0x0a, 0x04, 0x50, 0x6f, 0x72, 0x74, 0x12, 0x18, 0x0a, 0x07, 0x61, 0x64, 0x64, 0x72, 0x65, 0x73, 0x73, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x07, 0x61, 0x64, 0x64, 0x72, 0x65, 0x73, 0x73, 0x12, 0x14, 0x0a, 0x05, 0x6c, 0x61, 0x62, 0x65, 0x6c, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x05, 0x6c, 0x61, 0x62, 0x65, 0x6c, 0x12, 0x1a, 0x0a, 0x08, @@ -140,16 +149,18 @@ var file_cc_arduino_cli_commands_v1_port_proto_rawDesc = []byte{ 0x2e, 0x63, 0x6c, 0x69, 0x2e, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x73, 0x2e, 0x76, 0x31, 0x2e, 0x50, 0x6f, 0x72, 0x74, 0x2e, 0x50, 0x72, 0x6f, 0x70, 0x65, 0x72, 0x74, 0x69, 0x65, 0x73, 0x45, 0x6e, 0x74, 0x72, 0x79, 0x52, 0x0a, 0x70, 0x72, 0x6f, 0x70, 0x65, 0x72, 0x74, 0x69, 0x65, - 0x73, 0x1a, 0x3d, 0x0a, 0x0f, 0x50, 0x72, 0x6f, 0x70, 0x65, 0x72, 0x74, 0x69, 0x65, 0x73, 0x45, - 0x6e, 0x74, 0x72, 0x79, 0x12, 0x10, 0x0a, 0x03, 0x6b, 0x65, 0x79, 0x18, 0x01, 0x20, 0x01, 0x28, - 0x09, 0x52, 0x03, 0x6b, 0x65, 0x79, 0x12, 0x14, 0x0a, 0x05, 0x76, 0x61, 0x6c, 0x75, 0x65, 0x18, - 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x05, 0x76, 0x61, 0x6c, 0x75, 0x65, 0x3a, 0x02, 0x38, 0x01, - 0x42, 0x48, 0x5a, 0x46, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x61, - 0x72, 0x64, 0x75, 0x69, 0x6e, 0x6f, 0x2f, 0x61, 0x72, 0x64, 0x75, 0x69, 0x6e, 0x6f, 0x2d, 0x63, - 0x6c, 0x69, 0x2f, 0x72, 0x70, 0x63, 0x2f, 0x63, 0x63, 0x2f, 0x61, 0x72, 0x64, 0x75, 0x69, 0x6e, - 0x6f, 0x2f, 0x63, 0x6c, 0x69, 0x2f, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x73, 0x2f, 0x76, - 0x31, 0x3b, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x73, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, - 0x6f, 0x33, + 0x73, 0x12, 0x1f, 0x0a, 0x0b, 0x68, 0x61, 0x72, 0x64, 0x77, 0x61, 0x72, 0x65, 0x5f, 0x69, 0x64, + 0x18, 0x06, 0x20, 0x01, 0x28, 0x09, 0x52, 0x0a, 0x68, 0x61, 0x72, 0x64, 0x77, 0x61, 0x72, 0x65, + 0x49, 0x64, 0x1a, 0x3d, 0x0a, 0x0f, 0x50, 0x72, 0x6f, 0x70, 0x65, 0x72, 0x74, 0x69, 0x65, 0x73, + 0x45, 0x6e, 0x74, 0x72, 0x79, 0x12, 0x10, 0x0a, 0x03, 0x6b, 0x65, 0x79, 0x18, 0x01, 0x20, 0x01, + 0x28, 0x09, 0x52, 0x03, 0x6b, 0x65, 0x79, 0x12, 0x14, 0x0a, 0x05, 0x76, 0x61, 0x6c, 0x75, 0x65, + 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x05, 0x76, 0x61, 0x6c, 0x75, 0x65, 0x3a, 0x02, 0x38, + 0x01, 0x42, 0x48, 0x5a, 0x46, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, + 0x61, 0x72, 0x64, 0x75, 0x69, 0x6e, 0x6f, 0x2f, 0x61, 0x72, 0x64, 0x75, 0x69, 0x6e, 0x6f, 0x2d, + 0x63, 0x6c, 0x69, 0x2f, 0x72, 0x70, 0x63, 0x2f, 0x63, 0x63, 0x2f, 0x61, 0x72, 0x64, 0x75, 0x69, + 0x6e, 0x6f, 0x2f, 0x63, 0x6c, 0x69, 0x2f, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x73, 0x2f, + 0x76, 0x31, 0x3b, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x73, 0x62, 0x06, 0x70, 0x72, 0x6f, + 0x74, 0x6f, 0x33, } var ( diff --git a/rpc/cc/arduino/cli/commands/v1/port.proto b/rpc/cc/arduino/cli/commands/v1/port.proto index cc6cac07dc8..1a077a1df5a 100644 --- 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 properties = 5; + // The hardware ID (serial number) of the board attached to the port + string hardware_id = 6; } From 8c88ec89b7297076903db486dd69d0cdcab46869 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Tue, 7 Feb 2023 09:46:15 +0100 Subject: [PATCH 2/3] Added hardwareId output in 'board list -w' too --- internal/cli/board/list.go | 2 ++ 1 file changed, 2 insertions(+) diff --git a/internal/cli/board/list.go b/internal/cli/board/list.go index 0b033524221..4f810f76f5d 100644 --- 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"` From e34fffb90b1b898591684d5b87276eb397379a9b Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Tue, 7 Feb 2023 15:59:28 +0100 Subject: [PATCH 3/3] Update docs/pluggable-discovery-specification.md Co-authored-by: Luca Bianconi <71259950+Bikappa@users.noreply.github.com> --- docs/pluggable-discovery-specification.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/pluggable-discovery-specification.md b/docs/pluggable-discovery-specification.md index c986bbe530d..4854fa1968e 100644 --- a/docs/pluggable-discovery-specification.md +++ b/docs/pluggable-discovery-specification.md @@ -127,7 +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 + "hardwareId": <-- A STRING THAT UNIQUELY IDENTIFIES A BOARD INSTANCE "properties": { <-- A LIST OF PROPERTIES OF THE PORT } @@ -148,10 +148,10 @@ 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)`) -- `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. +- `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). @@ -185,7 +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 `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.