Skip to content

Commit 5441ea4

Browse files
cmaglieper1234
cmaglie
and
per1234
authored
Add documentation (#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]>
1 parent fd14435 commit 5441ea4

9 files changed

+359
-40
lines changed

‎arduino/cores/cores.go

+11-11
Original file line numberDiff line numberDiff line change
@@ -52,17 +52,17 @@ type PlatformRelease struct {
5252
ToolDependencies ToolDependencies
5353
DiscoveryDependencies DiscoveryDependencies
5454
MonitorDependencies MonitorDependencies
55-
Help PlatformReleaseHelp `json:"-"`
56-
Platform *Platform `json:"-"`
57-
Properties *properties.Map `json:"-"`
58-
Boards map[string]*Board `json:"-"`
59-
Programmers map[string]*Programmer `json:"-"`
60-
Menus *properties.Map `json:"-"`
61-
InstallDir *paths.Path `json:"-"`
62-
IsIDEBundled bool `json:"-"`
63-
IsTrusted bool `json:"-"`
64-
PluggableDiscoveryAware bool `json:"-"` // true if the Platform supports pluggable discovery (no compatibility layer required)
65-
Monitors map[string]*MonitorDependency
55+
Help PlatformReleaseHelp `json:"-"`
56+
Platform *Platform `json:"-"`
57+
Properties *properties.Map `json:"-"`
58+
Boards map[string]*Board `json:"-"`
59+
Programmers map[string]*Programmer `json:"-"`
60+
Menus *properties.Map `json:"-"`
61+
InstallDir *paths.Path `json:"-"`
62+
IsIDEBundled bool `json:"-"`
63+
IsTrusted bool `json:"-"`
64+
PluggableDiscoveryAware bool `json:"-"` // true if the Platform supports pluggable discovery (no compatibility layer required)
65+
Monitors map[string]*MonitorDependency `json:"-"`
6666
}
6767

6868
// BoardManifest contains information about a board. These metadata are usually

‎arduino/monitor/monitor.go

+3-10
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@
1313
// Arduino software without disclosing the source code of your own applications.
1414
// To purchase a commercial license, send an email to [email protected].
1515

16+
// Package monitor provides a client for Pluggable Monitors.
17+
// Documentation is available here:
18+
// https://arduino.github.io/arduino-cli/latest/pluggable-monitor-specification/
1619
package monitor
1720

1821
import (
@@ -30,16 +33,6 @@ import (
3033
"github.com/sirupsen/logrus"
3134
)
3235

33-
// To work correctly a Pluggable Monitor must respect the state machine specifed on the documentation:
34-
// https://arduino.github.io/arduino-cli/latest/pluggable-monitor-specification/#state-machine
35-
// States a PluggableMonitor can be in
36-
const (
37-
Alive int = iota
38-
Idle
39-
Opened
40-
Dead
41-
)
42-
4336
// PluggableMonitor is a tool that communicates with a board through a communication port.
4437
type PluggableMonitor struct {
4538
id string

‎docs/package_index_json-specification.md

+15-7
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ Each tool describes a binary distribution of a command line tool. A tool can be:
8181
- a debugger
8282
- a program that performs a firmware upgrade
8383
- a [pluggable discovery](pluggable-discovery-specification.md)
84+
- a [pluggable monitor](pluggable-monitor-specification.md)
8485

8586
basically anything that can run on the user's host PC and do something useful.
8687

@@ -220,6 +221,9 @@ Finally, let's see how `PLATFORMS` are made.
220221
"discoveryDependencies": [
221222
{ "packager": "arduino", "name": "serial-discovery" },
222223
{ "packager": "arduino", "name": "mdns-discovery" }
224+
],
225+
"monitorDependencies": [
226+
{ "packager": "arduino", "name": "serial-monitor" }
223227
]
224228
},
225229
```
@@ -236,13 +240,17 @@ Each PLATFORM describes a core for a specific architecture. The fields needed ar
236240
TOOLS
237241
- `boards`: the list of boards supported (note: just the names to display on the Arduino IDE and Arduino Pro IDE's
238242
Boards Manager GUI! the real boards definitions are inside `boards.txt` inside the core archive file)
239-
- `toolsDependencies`: the tools needed by this core. They will be installed by Boards Manager along with the platform.
240-
Each tool is referenced by the triple (`packager`, `name`, `version`) as previously said. Note that you can reference
241-
tools available in other packages as well, even if no platform of that package is installed.
242-
- `discoveryDependencies`: the Pluggable Discoveries needed by this core. Each discovery is referenced by `packager` and
243-
`name`, the `version` is not specified because the latest installed discovery tool will always be used. Like
244-
`toolsDependencies` they will be installed by Boards Manager along with the platform and can reference tools available
245-
in other packages as well, even if no platform of that package is installed.
243+
- `toolsDependencies`: the tools needed by this platform. They will be installed by Boards Manager along with the
244+
platform. Each tool is referenced by the triple (`packager`, `name`, `version`) as previously said. Note that you can
245+
reference tools available in other packages as well, even if no platform of that package is installed.
246+
- `discoveryDependencies`: the Pluggable Discoveries needed by this platform. Each discovery is referenced by the pair
247+
(`packager`, `name`), the `version` is not specified because the latest installed discovery tool will always be used.
248+
Like `toolsDependencies` they will be installed by Boards Manager along with the platform and can reference tools
249+
available in other packages as well, even if no platform of that package is installed.
250+
- `monitorDependencies`: the Pluggable Monitors needed by this platform. Each monitor is referenced by the pair
251+
(`packager`, `name`), the `version` is not specified because the latest installed monitor tool will always be used.
252+
Like `toolsDependencies` they will be installed by Boards Manager along with the platform and can reference tools
253+
available in other packages as well, even if no platform of that package is installed.
246254

247255
The `version` field is validated by both Arduino IDE and [JSemVer](https://github.com/zafarkhaja/jsemver). Here are the
248256
rules Arduino IDE follows for parsing versions

‎docs/platform-specification.md

+66-2
Original file line numberDiff line numberDiff line change
@@ -698,7 +698,7 @@ The tool configuration properties are available globally without the prefix. For
698698
property can be used as **{cmd.path}** inside the recipe, and the same happens for all the other avrdude configuration
699699
variables.
700700

701-
#### Pluggable discovery
701+
### Pluggable discovery
702702

703703
Discovery tools are a special kind of tool used to find supported boards. A platform must declare one or more Pluggable
704704
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).
755755

756756
For detailed information, see the [Pluggable Discovery specification](pluggable-discovery-specification.md).
757757

758-
#### Verbose parameter
758+
### Pluggable monitor
759+
760+
Monitor tools are a special kind of tool used to let the user communicate with the supported boards.
761+
762+
A platform must declare one or more Pluggable Monitor in its [`platform.txt`](#platformtxt) and bind them to a specific
763+
port protocol. Monitors can be referenced from other packages.
764+
765+
The following directive is used to bind a specific monitor tool to a specific port protocol:
766+
767+
```
768+
pluggable_monitor.required.PROTOCOL=VENDOR_ID:MONITOR_NAME
769+
```
770+
771+
where `PROTOCOL` must be replaced with the port protocol identifier and `VENDOR_ID:MONITOR_NAME` must be replaced with
772+
the monitor tool identifier.
773+
774+
The platform can support as many protocols as needed:
775+
776+
```
777+
pluggable_monitor.required.PROTOCOL1=VENDOR_ID:MONITOR_NAME1
778+
pluggable_monitor.required.PROTOCOL2=VENDOR_ID:MONITOR_NAME2
779+
...
780+
```
781+
782+
The above syntax requires specifying a monitor tool via the `monitorDependencies` field of the platform's
783+
[package index](package_index_json-specification.md). Since it might be cumbersome to use with manual installations, we
784+
provide another syntax to ease development and beta testing:
785+
786+
```
787+
pluggable_monitor.pattern.PROTOCOL=MONITOR_RECIPE
788+
```
789+
790+
where `MONITOR_RECIPE` must be replaced by the command line to launch the monitor tool for the specific `PROTOCOL`. An
791+
example could be:
792+
793+
```
794+
pluggable_monitor.pattern.custom-ble="{runtime.tools.my-ble-monitor.path}/my-ble-monitor" -H
795+
```
796+
797+
in this case the platform provides a new hypothetical `custom-ble` protocol monitor tool and the command line tool named
798+
`my-ble-monitor` is launched with the `-H` parameter to start the monitor tool. In this case the command line pattern
799+
may contain any extra parameter in the formula: this is different from the monitor tools installed through the
800+
`monitorDependencies` field that must run without any command line parameter.
801+
802+
We strongly recommend using this syntax only for development purposes and not on released platforms.
803+
804+
#### Built-in monitors
805+
806+
If a platform supports only boards connected via serial ports it can easily use the `builtin:serial-monitor` tool
807+
without creating a custom pluggable monitor:
808+
809+
```
810+
pluggable_monitor.required.serial=builtin:serial-monitor
811+
```
812+
813+
#### Backward compatibility
814+
815+
For backward compatibility, if a platform does not declare any discovery or monitor tool (using the
816+
`pluggable_discovery.*` or `pluggable_monitor.*` properties in `platform.txt` respectively) it will automatically
817+
inherit `builtin:serial-monitor` (but not other `builtin` monitor tools that may be possibly added in the future). This
818+
will allow all legacy non-pluggable platforms to migrate to pluggable monitor without disruption.
819+
820+
For detailed information, see the [Pluggable Monitor specification](pluggable-monitor-specification.md).
821+
822+
### Verbose parameter
759823

760824
It is possible for the user to enable verbosity from the Preferences panel of the IDEs or Arduino CLI's `--verbose`
761825
flag. This preference is transferred to the command line using the **ACTION.verbose** property (where ACTION is the

‎docs/pluggable-discovery-specification.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,8 @@ the response to the command is:
4343
The `protocolVersion` field represents the protocol version that will be used in the rest of the communication. There
4444
are three possible cases:
4545

46-
- if the client/IDE supports the same or a more recent version of the protocol than the discovery, then the IDE should
47-
go into a compatibility mode and use the protocol level supported by the discovery.
46+
- if the client/IDE supports the same or a more recent version of the protocol than the discovery, then the client/IDE
47+
should go into a compatibility mode and use the protocol level supported by the discovery.
4848
- if the discovery supports a more recent version of the protocol than the client/IDE: the discovery should downgrade
4949
itself into compatibility mode and report a `protocolVersion` that is less than or equal to the one supported by the
5050
client/IDE.

0 commit comments

Comments
 (0)