Add documentation (arduino#1499)

* Added documentation for pluggable monitor * Apply suggestions from code review Co-authored-by: per1234 <[email protected]> * Add pluggable monitor spec in nav bar; fixed link in source code comments * fix i18n and lint warnings Co-authored-by: per1234 <[email protected]>
MatteoPologruto · Oct 7, 2021 · 5441ea4 · 5441ea4
1 parent fd14435
commit 5441ea4
Show file tree

Hide file tree

Showing 9 changed files with 359 additions and 40 deletions.
diff --git a/arduino/cores/cores.go b/arduino/cores/cores.go
@@ -52,17 +52,17 @@ type PlatformRelease struct {
 	ToolDependencies        ToolDependencies
 	DiscoveryDependencies   DiscoveryDependencies
 	MonitorDependencies     MonitorDependencies
-	Help                    PlatformReleaseHelp    `json:"-"`
-	Platform                *Platform              `json:"-"`
-	Properties              *properties.Map        `json:"-"`
-	Boards                  map[string]*Board      `json:"-"`
-	Programmers             map[string]*Programmer `json:"-"`
-	Menus                   *properties.Map        `json:"-"`
-	InstallDir              *paths.Path            `json:"-"`
-	IsIDEBundled            bool                   `json:"-"`
-	IsTrusted               bool                   `json:"-"`
-	PluggableDiscoveryAware bool                   `json:"-"` // true if the Platform supports pluggable discovery (no compatibility layer required)
-	Monitors                map[string]*MonitorDependency
+	Help                    PlatformReleaseHelp           `json:"-"`
+	Platform                *Platform                     `json:"-"`
+	Properties              *properties.Map               `json:"-"`
+	Boards                  map[string]*Board             `json:"-"`
+	Programmers             map[string]*Programmer        `json:"-"`
+	Menus                   *properties.Map               `json:"-"`
+	InstallDir              *paths.Path                   `json:"-"`
+	IsIDEBundled            bool                          `json:"-"`
+	IsTrusted               bool                          `json:"-"`
+	PluggableDiscoveryAware bool                          `json:"-"` // true if the Platform supports pluggable discovery (no compatibility layer required)
+	Monitors                map[string]*MonitorDependency `json:"-"`
 }
 
 // BoardManifest contains information about a board. These metadata are usually

diff --git a/arduino/monitor/monitor.go b/arduino/monitor/monitor.go
@@ -13,6 +13,9 @@
 // Arduino software without disclosing the source code of your own applications.
 // To purchase a commercial license, send an email to [email protected].
 
+// Package monitor provides a client for Pluggable Monitors.
+// Documentation is available here:
+// https://arduino.github.io/arduino-cli/latest/pluggable-monitor-specification/
 package monitor
 
 import (
@@ -30,16 +33,6 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
-// To work correctly a Pluggable Monitor must respect the state machine specifed on the documentation:
-// https://arduino.github.io/arduino-cli/latest/pluggable-monitor-specification/#state-machine
-// States a PluggableMonitor can be in
-const (
-	Alive int = iota
-	Idle
-	Opened
-	Dead
-)
-
 // PluggableMonitor is a tool that communicates with a board through a communication port.
 type PluggableMonitor struct {
 	id                   string

diff --git a/docs/package_index_json-specification.md b/docs/package_index_json-specification.md
@@ -81,6 +81,7 @@ Each tool describes a binary distribution of a command line tool. A tool can be:
 - a debugger
 - a program that performs a firmware upgrade
 - a [pluggable discovery](pluggable-discovery-specification.md)
+- a [pluggable monitor](pluggable-monitor-specification.md)
 
 basically anything that can run on the user's host PC and do something useful.
 
@@ -220,6 +221,9 @@ Finally, let's see how `PLATFORMS` are made.
           "discoveryDependencies": [
             { "packager": "arduino", "name": "serial-discovery" },
             { "packager": "arduino", "name": "mdns-discovery" }
+          ],
+          "monitorDependencies": [
+            { "packager": "arduino", "name": "serial-monitor" }
           ]
         },
 ```
@@ -236,13 +240,17 @@ Each PLATFORM describes a core for a specific architecture. The fields needed ar
   TOOLS
 - `boards`: the list of boards supported (note: just the names to display on the Arduino IDE and Arduino Pro IDE's
   Boards Manager GUI! the real boards definitions are inside `boards.txt` inside the core archive file)
-- `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.
+- `toolsDependencies`: the tools needed by this platform. 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 platform. Each discovery is referenced by the pair
+  (`packager`, `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.
+- `monitorDependencies`: the Pluggable Monitors needed by this platform. Each monitor is referenced by the pair
+  (`packager`, `name`), the `version` is not specified because the latest installed monitor 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

diff --git a/docs/platform-specification.md b/docs/platform-specification.md
@@ -698,7 +698,7 @@ 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
+### Pluggable discovery
 
 Discovery tools are a special kind of tool used to find supported boards. A platform must declare one or more Pluggable
 Discoveries in its [`platform.txt`](#platformtxt). Discoveries can be referenced from other packages, including the
@@ -755,7 +755,71 @@ builtin discoveries that may be possibly added in the future).
 
 For detailed information, see the [Pluggable Discovery specification](pluggable-discovery-specification.md).
 
-#### Verbose parameter
+### Pluggable monitor
+
+Monitor tools are a special kind of tool used to let the user communicate with the supported boards.
+
+A platform must declare one or more Pluggable Monitor in its [`platform.txt`](#platformtxt) and bind them to a specific
+port protocol. Monitors can be referenced from other packages.
+
+The following directive is used to bind a specific monitor tool to a specific port protocol:
+
+```
+pluggable_monitor.required.PROTOCOL=VENDOR_ID:MONITOR_NAME
+```
+
+where `PROTOCOL` must be replaced with the port protocol identifier and `VENDOR_ID:MONITOR_NAME` must be replaced with
+the monitor tool identifier.
+
+The platform can support as many protocols as needed:
+
+```
+pluggable_monitor.required.PROTOCOL1=VENDOR_ID:MONITOR_NAME1
+pluggable_monitor.required.PROTOCOL2=VENDOR_ID:MONITOR_NAME2
+...
+```
+
+The above syntax requires specifying a monitor tool via the `monitorDependencies` field of the platform's
+[package index](package_index_json-specification.md). Since it might be cumbersome to use with manual installations, we
+provide another syntax to ease development and beta testing:
+
+```
+pluggable_monitor.pattern.PROTOCOL=MONITOR_RECIPE
+```
+
+where `MONITOR_RECIPE` must be replaced by the command line to launch the monitor tool for the specific `PROTOCOL`. An
+example could be:
+
+```
+pluggable_monitor.pattern.custom-ble="{runtime.tools.my-ble-monitor.path}/my-ble-monitor" -H
+```
+
+in this case the platform provides a new hypothetical `custom-ble` protocol monitor tool and the command line tool named
+`my-ble-monitor` is launched with the `-H` parameter to start the monitor tool. In this case the command line pattern
+may contain any extra parameter in the formula: this is different from the monitor tools installed through the
+`monitorDependencies` field that must run without any command line parameter.
+
+We strongly recommend using this syntax only for development purposes and not on released platforms.
+
+#### Built-in monitors
+
+If a platform supports only boards connected via serial ports it can easily use the `builtin:serial-monitor` tool
+without creating a custom pluggable monitor:
+
+```
+pluggable_monitor.required.serial=builtin:serial-monitor
+```
+
+#### Backward compatibility
+
+For backward compatibility, if a platform does not declare any discovery or monitor tool (using the
+`pluggable_discovery.*` or `pluggable_monitor.*` properties in `platform.txt` respectively) it will automatically
+inherit `builtin:serial-monitor` (but not other `builtin` monitor tools that may be possibly added in the future). This
+will allow all legacy non-pluggable platforms to migrate to pluggable monitor without disruption.
+
+For detailed information, see the [Pluggable Monitor specification](pluggable-monitor-specification.md).
+
+### Verbose parameter
 
 It is possible for the user to enable verbosity from the Preferences panel of the IDEs or Arduino CLI's `--verbose`
 flag. This preference is transferred to the command line using the **ACTION.verbose** property (where ACTION is the

diff --git a/docs/pluggable-discovery-specification.md b/docs/pluggable-discovery-specification.md
@@ -43,8 +43,8 @@ the response to the command is:
 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 client/IDE supports the same or a more recent version of the protocol than the discovery, then the client/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.