Add documentation

Author: silvanocerza

docs/package_index_json-specification.md

@@ -80,6 +80,7 @@ Each tool describes a binary distribution of a command line tool. A tool can be:
 - a file preprocessor
 - a debugger
 - a program that performs a firmware upgrade
+- a [Pluggable Discovery](pluggable-discovery-specification.md)
 
 basically anything that can run on the user's host PC and do something useful.
 
@@ -215,7 +216,11 @@ Finally, let's see how `PLATFORMS` are made.
           "toolsDependencies": [
             { "packager": "arduino", "name": "avr-gcc", "version": "4.8.1-arduino5" },
             { "packager": "arduino", "name": "avrdude", "version": "6.0.1-arduino5" }
-          ]
+          ],
+         "discoveryDependencies": [
+           { "packager": "arduino", "name": "serial-discovery" },
+           { "packager": "arduino", "name": "mdns-discovery" }
+         ]
         },
 ```
 
@@ -234,6 +239,10 @@ Each PLATFORM describes a core for a specific architecture. The fields needed ar
 - `toolsDependencies`: the tools needed by this core. They will be installed by Boards Manager along with the platform.
   Each tool is referenced by the triple (`packager`, `name`, `version`) as previously said. Note that you can reference
   tools available in other packages as well, even if no platform of that package is installed.
+- `discoveryDependencies`: the Pluggable Discoveries needed by this core. Each discovery is referenced by `packager` and
+  `name`, the `version` is not specified because the latest installed discovery tool will always be used. Like
+  `toolsDependencies` they will be installed by Boards Manager along with the platform and can reference tools available
+  in other packages as well, even if no platform of that package is installed.
 
 The `version` field is validated by both Arduino IDE and [JSemVer](https://github.com/zafarkhaja/jsemver). Here are the
 rules Arduino IDE follows for parsing versions

docs/platform-specification.md

@@ -615,7 +615,7 @@ A tool may have some actions not defined (it's not mandatory to define all four
     tools.avrdude.cmd.path={path}/bin/avrdude
     tools.avrdude.config.path={path}/etc/avrdude.conf
 
-    tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" -p{build.mcu} -c{upload.protocol} -P{serial.port} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
+    tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" -p{build.mcu} -c{upload.port.protocol} -P{upload.port.address} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
 
 A **{runtime.tools.TOOL_NAME.path}** and **{runtime.tools.TOOL_NAME-TOOL_VERSION.path}** property is generated for the
 tools of Arduino AVR Boards and any other platform installed via Boards Manager. **{runtime.tools.TOOL_NAME.path}**
@@ -625,6 +625,64 @@ The tool configuration properties are available globally without the prefix. For
 property can be used as **{cmd.path}** inside the recipe, and the same happens for all the other avrdude configuration
 variables.
 
+#### Pluggable Discovery
+
+Discovery tools are a special kind of tools that are used to find supported boards, a platform must declare one or more
+Pluggable Discoveries in its `platform.txt`. It's ok to use another platform discovery or the builtin ones if necessary.
+
+There are two different syntaxes to declare discoveries, if the platform uses just one discovery:
+
+```
+discovery.required=PLATFORM:DISCOVERY_NAME
+```
+
+instead if it needs multiple discoveries:
+
+```
+discovery.required.0=PLATFORM:DISCOVERY_ID_1
+discovery.required.1=PLATFORM:DISCOVERY_ID_2
+```
+
+A platform that supports only boards connected to the serial can easily use the builtin `serial-discovery` without
+creating a custom Pluggable Discovery:
+
+```
+discovery.required=builtin:serial-discovery
+```
+
+if it supports also boards connected to the network it can use the builtin `mdns-discovery`:
+
+```
+discovery.required.0=builtin:serial-discovery
+discovery.required.1=builtin:mdns-discovery
+```
+
+Since the above syntax requires adding a discovery in the `discoveryDependencies` field in the platform
+`package_index.json` it might be cumbersome to do it before releasing it so we also provide another syntax to ease
+development:
+
+```
+discovery.DISCOVERY_ID.pattern=DISCOVERY_RECIPE
+```
+
+`DISCOVERY_ID` must be replaced by a unique identifier for the particular discovery and `DISCOVERY_RECIPE` must be
+replaced by the command line to launch the discovery. An example could be:
+
+```
+## Teensy Ports Discovery
+discovery.teensy.pattern="{runtime.tools.teensy_ports.path}/hardware/tools/teensy_ports" -J2
+```
+
+We strongly recommend not using this syntax on released platforms but only for development purposes.
+
+For backward compatibility, if a platform does not declare any discovery (using the `discovery.*` properties in
+`platform.txt`) it will automatically inherits `builtin:serial-discovery` and `builtin:mdns-discovery` (but not other
+builtin discoveries that may be possibly added in the future). This will allow all legacy non-pluggable platforms to
+migrate to pluggable discovery without disruption.
+
+For detailed information see the [Pluggable Discovery specification](pluggable-discovery-specification.md)
+documentation.
+
 #### Verbose parameter
 
 It is possible for the user to enable verbosity from the Preferences panel of the IDEs or Arduino CLI's `--verbose`
@@ -651,26 +709,48 @@ The Upload action is triggered when the user clicks on the "Upload" button on th
 [`arduino-cli upload`](commands/arduino-cli_upload.md). Arduino uses the term "upload" for the process of transferring a
 program to the Arduino board.
 
-The **upload.tool** property determines the tool to be used for upload. A specific **upload.tool** property should be
-defined for every board in boards.txt:
+The **upload.tool.<protocol_name\>** property determines the tool to be used for upload. A specific
+**upload.tool.<protocol_name\>** property should be defined for every board in boards.txt:
 
     [......]
-    uno.upload.tool=avrdude
+    uno.upload.tool.serial=avrdude
     [......]
-    leonardo.upload.tool=avrdude
+    leonardo.upload.tool.serial=avrdude
+    leonardo.upload.tool.network=arduino_ota
     [......]
 
+When the user tries to upload using a certain protocol but the board doesn't support it it will fallback to `default` if
+specified. A board can always specify a `default` protocol even if others are defined:
+
+    [......]
+    uno.upload.tool.default=avrdude
+    [......]
+    leonardo.upload.tool.default=avrdude
+    leonardo.upload.tool.network=arduino_ota
+    [......]
+
+`default` is also used when no upload address is provided by the user, this can be done only for boards that use upload
+tools with builtin port detection like `openocd`.
+
+For backward compatibility with IDE 1.8.15 and older the previous syntax is still supported:
+
+    uno.upload.tool=avrdude
+
+The previous syntax is equivalent to:
+
+    uno.upload.tool.default=avrdude
+
 Other upload parameters can also be defined for the board. For example, in the Arduino AVR Boards boards.txt we have:
 
     [.....]
     uno.name=Arduino Uno
-    uno.upload.tool=avrdude
+    uno.upload.tool.serial=avrdude
     uno.upload.protocol=arduino
     uno.upload.maximum_size=32256
     uno.upload.speed=115200
     [.....]
     leonardo.name=Arduino Leonardo
-    leonardo.upload.tool=avrdude
+    leonardo.upload.tool.serial=avrdude
     leonardo.upload.protocol=avr109
     leonardo.upload.maximum_size=28672
     leonardo.upload.speed=57600
@@ -681,9 +761,112 @@ Other upload parameters can also be defined for the board. For example, in the A
 Most **{upload.XXXX}** variables are used later in the avrdude upload recipe in platform.txt:
 
     [.....]
-    tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" {upload.verbose} -p{build.mcu} -c{upload.protocol} -P{serial.port} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
+    tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" {upload.verbose} -p{build.mcu} -c{upload.port.protocol} -P{upload.port.address} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
     [.....]
 
+If necessary the same property can be defined multiple times for different protocols:
+
+    leonardo.upload.serial.maximum_size=28672
+    leonardo.upload.network.maximum_size=256
+
+The two above properties will be available as **{upload.serial.maximum_size}** and **{upload.network.maximum_size}**.
+
+#### Properties from Pluggable Discovery
+
+If a platform supports Pluggable Discovery it can also use the port's properties returned by a discovery. For example,
+the following port metadata coming from a pluggable discovery:
+
+    {
+        "eventType": "add",
+        "port": {
+            "address": "/dev/ttyACM0",
+            "label": "ttyACM0",
+            "protocol": "serial",
+            "protocolLabel": "Serial Port (USB)",
+            "properties": {
+                "pid": "0x804e",
+                "vid": "0x2341",
+                "serialNumber": "EBEABFD6514D32364E202020FF10181E",
+                "name": "ttyACM0"
+            }
+        }
+    }
+
+will be available on the recipe as the variables:
+
+    {upload.port.address} = /dev/ttyACM0
+    {upload.port.label} = ttyACM0
+    {upload.port.protocol} = serial
+    {upload.port.protocolLabel} = Serial Port (USB)
+    {upload.port.properties.pid} = 0x8043
+    {upload.port.properties.vid} = 0x2341
+    {upload.port.properties.serialNumber} = EBEABFD6514D32364E202020FF10181E
+    {upload.port.properties.name} = ttyACM0
+    {serial.port} = /dev/ttyACM0                # for backward compatibility
+    {serial.port.file} = ttyACM0                # only because protocol=serial
+
+Here another example:
+
+    {
+    "eventType": "add",
+    "port": {
+        "address": "192.168.1.232",
+        "label": "SSH on my-board (192.168.1.232)",
+        "protocol": "ssh",
+        "protocolLabel": "SSH Network port",
+        "properties": {
+        "macprefix": "AA:BB:CC",
+        "macaddress": "AA:BB:CC:DD:EE:FF"
+        }
+    }
+    }
+
+that is translated to:
+
+    {upload.port.address} = 192.168.1.232
+    {upload.port.label} = SSH on my-board (192.168.1.232)
+    {upload.port.protocol} = ssh
+    {upload.port.protocolLabel} = SSH Network port
+    {upload.port.properties.macprefix} = AA:BB:CC
+    {upload.port.properties.macaddress} = AA:BB:CC:DD:EE:FF
+    {serial.port} = 192.168.1.232                  # for backward compatibility
+
+This configuration, together with protocol selection, allows to remove the hardcoded `network_pattern`, now we can
+replace the legacy recipe (split into multiple lines for clarity):
+
+    tools.bossac.upload.network_pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA"
+                                        -address {serial.port} -port 65280
+                                        -sketch "{build.path}/{build.project_name}.bin"
+
+with:
+
+    tools.arduino_ota.upload.pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA"
+                                    -address {upload.port.address} -port 65280
+                                    -sketch "{build.path}/{build.project_name}.bin"
+
+#### User provided fields
+
+Some upload recipes might require custom fields that must be provided by the user, like username and password to upload
+over the network. In this case the recipe must use the special placeholder {upload.field.FIELD_NAME} where FIELD_NAME
+must be declared separately in the recipe using the following format:
+
+    tools.UPLOAD_RECIPE_ID.upload.field.FIELD_NAME=FIELD_LABEL
+    tools.UPLOAD_RECIPE_ID.upload.field.FIELD_NAME.secret=true
+
+FIELD_LABEL is the label shown in the graphical prompt to ask the user to enter the value of the field. The secret
+property is optional and it should be set to true if the field is a secret (like passwords or token).
+
+Let’s see how a complete example will look like:
+
+    tools.arduino_ota.upload.field.username=Username
+    tools.arduino_ota.upload.field.password=Password
+    tools.arduino_ota.upload.field.password.secret=true
+    tools.arduino_ota.upload.pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA"
+                                    -address {upload.port.address} -port 65280
+                                    -username "{upload.field.username}
+                                    -password "{upload.field.password}"
+                                    -sketch "{build.path}/{build.project_name}.bin"
+
 #### Upload verification
 
 Upload verification can be enabled via the Arduino IDE's **File > Preferences > Verify code after upload** or
@@ -744,10 +927,14 @@ support uploading via programmer.
 
 The full path (e.g., `/dev/ttyACM0`) of the port selected via the IDE or
 [`arduino-cli upload`](commands/arduino-cli_upload.md)'s `--port` option is available as a configuration property
-**{serial.port}**.
+**{upload.port.address}**.
 
 The file component of the port's path (e.g., `ttyACM0`) is available as the configuration property
-**{serial.port.file}**.
+**{upload.port.label}**.
+
+For backward compatibility with IDE 1.8.15 and older the old property **serial.port** is still available and is
+identical to **{upload.port.address}**. Instead **serial.port.file** is identical to **{upload.port.label}** and
+available only if protocol in use is **serial**.
 
 ### Upload using an external programmer
 
@@ -756,7 +943,17 @@ The `program` action is triggered via the **Sketch > Upload Using Programmer** f
 compiled sketch to a board using an external programmer.
 
 The **program.tool** property determines the tool to be used for this action. This property is typically defined for
-each programmer in [programmers.txt](#programmerstxt):
+each programmer in [programmers.txt](#programmerstxt) and uses the same syntax as `upload` action:
+
+    [......]
+    usbasp.program.tool.serial=avrdude
+    [......]
+    arduinoasisp.program.tool.serial=avrdude
+    [......]
+    arduinoisp.program.tool.default=avrdude
+    [......]
+
+For backward compatibility with IDE 1.8.15 and older the previous syntax is still supported:
 
     [......]
     usbasp.program.tool=avrdude
@@ -786,7 +983,18 @@ the board.
 1. `bootloader` is used to flash the bootloader to the board
 
 The **bootloader.tool** property determines the tool to be used for the `erase` and `bootloader` actions both. This
-property is typically defined for each board in boards.txt:
+property is typically defined for each board in boards.txt and uses the same syntax as `upload` action:
+
+    [......]
+    uno.bootloader.tool.serial=avrdude
+    [......]
+    leonardo.upload.tool.serial=avrdude
+    leonardo.upload.tool.network=arduino_ota
+    [......]
+    duemilanove.upload.tool.default=avrdude
+    [......]
+
+For backward compatibility with IDE 1.8.15 and older the previous syntax is still supported:
 
     [......]
     uno.bootloader.tool=avrdude
@@ -1009,3 +1217,7 @@ software is in use:
   This behavior
   [can be configured](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_core_install/#options)
 - **Arduino Pro IDE**: (since 0.1.0) runs the script for any installed platform.
+
+```
+
+```

docs/pluggable-discovery-specification.md

@@ -0,0 +1,368 @@
+These tools must be in the form of executables that can be launched as a subprocess using a `platform.txt` command line
+recipe. They will communicate to the parent process via stdin/stdout, in particular a discovery will accept commands as
+plain text strings from stdin and will send answers back in JSON format on stdout. Each tool will implement the commands
+to list and enumerate ports for a specific protocol as specified in this document.
+
+### Pluggable discovery API via stdin/stdout
+
+All the commands listed in this specification must be implemented in the discovery.
+
+After startup, the tool will just stay idle waiting for commands. The available commands are: `HELLO`, `START`, `STOP`,
+`QUIT`, `LIST` and `START_SYNC`.
+
+After each command the client always expect a response from the discovery. The discovery must not introduce any delay
+and must respond to all commands as fast as possible.
+
+#### HELLO command
+
+`HELLO` **must be the first command sent** to the discovery to tell the name of the client/IDE and the version of the
+pluggable discovery protocol that the client/IDE supports. The syntax of the command is:
+
+`HELLO <PROTOCOL_VERSION> "<USER_AGENT>"`
+
+- `<PROTOCOL_VERSION>` is the maximum protocol version supported by the client/IDE (currently `1`)
+
+- `<USER_AGENT>` is the name and version of the client (double-quotes `"` are not allowed)
+
+some examples:
+
+- `HELLO 1 "Arduino IDE 1.8.13"`
+
+- `HELLO 1 "arduino-cli 1.2.3"`
+
+the response to the command is:
+
+```JSON
+{
+  "eventType": "hello",
+  "protocolVersion": 1,
+  "message": "OK"
+}
+```
+
+The `protocolVersion` field represents the protocol version that will be used in the rest of the communication. There
+are three possible cases:
+
+- if the client/IDE supports the same or a more recent version of the protocol than the discovery, then the IDE should
+  go into a compatibility mode and use the protocol level supported by the discovery.
+- if the discovery supports a more recent version of the protocol than the client/IDE: the discovery should downgrade
+  itself into compatibility mode and report a `protocolVersion` that is less than or equal to the one supported by the
+  client/IDE.
+- if the discovery cannot go into compatibility mode, it will report the protocol version supported (even if greater
+  than the version supported by the client/IDE) and the client/IDE may decide to terminate the discovery or produce an
+  error/warning.
+
+#### START command
+
+The `START` command initializes and start the discovery internal subroutines. This command must be called before `LIST`
+or `START_SYNC`. The response to the start command is:
+
+```JSON
+{
+  "eventType": "start",
+  "message": "OK"
+}
+```
+
+If the discovery could not start, for any reason, it must report the error with:
+
+```JSON
+{
+  "eventType": "start",
+  "error": true,
+  "message": "Permission error"
+}
+```
+
+The `error` field must be set to `true` and the `message` field should contain a description of the error.
+
+#### STOP command
+
+The `STOP` command stops the discovery internal subroutines and possibly free the internally used resources. This
+command should be called if the client wants to pause the discovery for a while. The response to the command is:
+
+```JSON
+{
+  "eventType": "stop",
+  "message": "OK"
+}
+```
+
+If an error occurs:
+
+```JSON
+{
+  "eventType": "stop",
+  "error": true,
+  "message": "Resource busy"
+}
+```
+
+The `error` field must be set to `true` and the `message` field should contain a description of the error.
+
+#### QUIT command
+
+The `QUIT` command terminates the discovery. The response to `QUIT` is:
+
+```JSON
+{
+  "eventType": "quit",
+  "message": "OK"
+}
+```
+
+after this output the discovery exits. This command is supposed to always succeed.
+
+#### LIST command
+
+The `LIST` command executes an enumeration of the ports and returns a list of the available ports at the moment of the
+call. The format of the response is the following:
+
+```
+{
+  "eventType": "list",
+  "ports": [
+    {
+      "address":       <-- THE ADDRESS OF THE PORT
+      "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
+      "properties": {
+                       <-- A LIST OF PROPERTIES OF THE PORT
+      }
+    }, {
+      ...              <-- OTHER PORTS...
+    }
+  ]
+}
+```
+
+The `ports` field contains a list of the available ports.
+
+Each port has:
+
+- an `address` (for example `/dev/ttyACM0` for serial ports or `192.168.10.100` for network ports)
+
+- a `label` that is the human readable form of the `address` (it may be for example `ttyACM0` or
+  `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
+
+To make the above more clear let’s show an example with the `serial_discovery`:
+
+```JSON
+{
+  "eventType": "list",
+  "ports": [
+    {
+      "address": "/dev/ttyACM0",
+      "label": "ttyACM0",
+      "protocol": "serial",
+      "protocolLabel": "Serial Port (USB)",
+      "properties": {
+        "pid": "0x804e",
+        "vid": "0x2341",
+        "serialNumber": "EBEABFD6514D32364E202020FF10181E",
+        "name": "ttyACM0"
+      }
+    }
+  ]
+}
+```
+
+In this case the serial port metadata comes from an USB serial converter. Inside the `properties` we have all the
+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 `LIST` command performs a one-shot polling of the ports. The discovery should answer as soon as reasonably possible,
+without any additional delay.
+
+Some discoveries may require some time to discover a new port (for example network protocols like MDNS, Bluetooth, etc.
+requires some seconds to receive the broadcasts from all available clients) in that case is fine to answer with an empty
+or incomplete list.
+
+If an error occurs and the discovery can't complete the enumeration is must report the error with:
+
+```JSON
+{
+  "eventType": "list",
+  "error": true,
+  "message": "Resource busy"
+}
+```
+
+The `error` field must be set to `true` and the `message` field should contain a description of the error.
+
+#### START_SYNC command
+
+The `START_SYNC` command puts the tool in "events" mode: the discovery will send `add` and `remove` events each time a
+new port is detected or removed respectively. If the discovery goes into "events" mode successfully the response to this
+command is:
+
+```JSON
+{
+  "eventType": "start_sync",
+  "message": "OK"
+}
+```
+
+After this message the discoery will send `add` and `remove` event asyncronoushly (more on that later). If an error
+occurs and the discovery can't go in "events" mode the error must be reported as:
+
+```JSON
+{
+  "eventType": "start_sync",
+  "error": true,
+  "message": "Resource busy"
+}
+```
+
+The `error` field must be set to `true` and the `message` field should contain a description of the error.
+
+Once in "event" mode, the discovery is allowed to send `add` and `remove` messages asynchronously in realtime, this
+means that the client must be able to handle these incoming messages at any moment.
+
+The `add` event looks like the following:
+
+```JSON
+{
+  "eventType": "add",
+  "port": {
+    "address": "/dev/ttyACM0",
+    "label": "ttyACM0",
+    "properties": {
+      "pid": "0x804e",
+      "vid": "0x2341",
+      "serialNumber": "EBEABFD6514D32364E202020FF10181E",
+      "name": "ttyACM0"
+    },
+    "protocol": "serial",
+    "protocolLabel": "Serial Port (USB)"
+  }
+}
+```
+
+It basically provides the same information as the `list` event but for a single port. After calling `START_SYNC` an
+initial burst of add events must be generated in sequence to report all the ports available at the moment of the start.
+
+The `remove` event looks like the following:
+
+```JSON
+{
+  "eventType": "remove",
+  "port": {
+    "address": "/dev/ttyACM0",
+    "protocol": "serial"
+  }
+}
+```
+
+The content is straightforward, in this case only the `address` and `protocol` fields are reported.
+
+If the information about a port needs to be updated the discovery may send a new `add` message for the same port address
+and protocol without sending a `remove` first: this means that all the previous information about the port must be
+discarded and replaced with the new one.
+
+#### Invalid commands
+
+If the client sends an invalid or malformed command, the discovery should answer with:
+
+```JSON
+{
+  "eventType": "command_error",
+  "error": true,
+  "message": "Unknown command XXXX"
+}
+```
+
+### Board identification
+
+The `properties` associated to a port can be used to identify the board attached to that port. The algorithm is simple:
+
+- each board listed in the platform file `boards.txt` may declare a set of `upload_port.*` properties
+- if each `upload_port.*` property has a match in the `properties` set coming from the discovery then the board is a
+  “candidate” board attached to that port.
+
+Some port `properties` may not be precise enough to uniquely identify a board, in that case more boards may match the
+same set of `properties`, that’s why we called it “candidate”.
+
+Let’s see an example to clarify things a bit, let's suppose that we have the following `properties` coming from the
+serial discovery:
+
+```JSON
+  "port": {
+    "address": "/dev/ttyACM0",
+    "properties": {
+      "pid": "0x804e",
+      "vid": "0x2341",
+      "serialNumber": "EBEABFD6514D32364E202020FF10181E",
+      "name": "ttyACM0"
+    }
+```
+
+in this case we can use `vid` and `pid` to identify the board. The `serialNumber`, instead, is unique for that specific
+instance of the board so it can't be used to identify the board model. Let’s suppose we have the following `boards.txt`:
+
+```
+# Arduino Zero (Programming Port)
+# ---------------------------------------
+arduino_zero_edbg.name=Arduino Zero (Programming Port)
+arduino_zero_edbg.upload_port.vid=0x03eb
+arduino_zero_edbg.upload_port.pid=0x2157
+[...CUT...]
+# Arduino Zero (Native USB Port)
+# --------------------------------------
+arduino_zero_native.name=Arduino Zero (Native USB Port)
+arduino_zero_native.upload_port.0.vid=0x2341
+arduino_zero_native.upload_port.0.pid=0x804d
+arduino_zero_native.upload_port.1.vid=0x2341
+arduino_zero_native.upload_port.1.pid=0x004d
+arduino_zero_native.upload_port.2.vid=0x2341
+arduino_zero_native.upload_port.2.pid=0x824d
+arduino_zero_native.upload_port.3.vid=0x2341
+arduino_zero_native.upload_port.3.pid=0x024d
+[...CUT...]
+# Arduino MKR1000
+# -----------------------
+mkr1000.name=Arduino MKR1000
+mkr1000.upload_port.0.vid=0x2341       <------- MATCHING IDs
+mkr1000.upload_port.0.pid=0x804e       <------- MATCHING IDs
+mkr1000.upload_port.1.vid=0x2341
+mkr1000.upload_port.1.pid=0x004e
+mkr1000.upload_port.2.vid=0x2341
+mkr1000.upload_port.2.pid=0x824e
+mkr1000.upload_port.3.vid=0x2341
+mkr1000.upload_port.3.pid=0x024e
+[...CUT...]
+```
+
+As we can see the only board that has the two properties matching is the `mkr1000`, in this case the CLI knows that the
+board is surely an MKR1000.
+
+Note that `vid` and `pid` properties are just free text key/value pairs: the discovery may return basically anything,
+the board just needs to have the same properties defined in `boards.txt` as `upload_port.*` to be identified.
+
+We can also specify multiple identification properties for the same board using the `.N` suffix, for example:
+
+```
+myboard.name=My Wonderful Arduino Compatible Board
+myboard.upload_port.pears=20
+myboard.upload_port.apples=30
+```
+
+will match on `pears=20, apples=30` but:
+
+```
+myboard.name=My Wonderful Arduino Compatible Board
+myboard.upload_port.0.pears=20
+myboard.upload_port.0.apples=30
+myboard.upload_port.1.pears=30
+myboard.upload_port.1.apples=40
+```
+
+will match on both `pears=20, apples=30` and `pears=30, apples=40` but not `pears=20, apples=40`, in that sense each
+"set" of identification properties is indepentent from each other and cannot be mixed for port matching.

mkdocs.yml

@@ -70,6 +70,7 @@ nav:
       - board details: commands/arduino-cli_board_details.md
       - board list: commands/arduino-cli_board_list.md
       - board listall: commands/arduino-cli_board_listall.md
+      - board search: commands/arduino-cli_board_search.md
       - burn-bootloader: commands/arduino-cli_burn-bootloader.md
       - cache: commands/arduino-cli_cache.md
       - cache clean: commands/arduino-cli_cache_clean.md
@@ -121,6 +122,7 @@ nav:
   - sketch-specification.md
   - library-specification.md
   - platform-specification.md
+  - Pluggable Discovery specification: pluggable-discovery-specification.md
   - Package index specification: package_index_json-specification.md
 
 extra_css: