Missing documentation on 'monitor -c' configuration settings

[silaswaxter]

As a side note, an example of changing the baudrate should be added to the documentation.
Originally posted by @romainreignier in #1562 (comment)

The official docs are missing documentation on the available configuration options for the monitor command's -c option. At a minimum, the baudrate option should be documented.

[per1234]

Hi @silaswaxter. Thanks for your suggestion.

I agree that this should be documented. However, I would like to note that it is not possible to do so as you have framed it:

missing documentation on the available configuration options for the monitor command's -c option

The reason is that Arduino CLI uses a flexible and powerful "pluggable monitor" system, where anyone can create monitor tools for arbitrary communication channels (AKA "port") between the computer and the Arduino board. Each pluggable monitor tool defines its own arbitrary configuration parameters.

The traditional and most common of these communication channels is the serial port and Arduino provides a serial-monitor pluggable monitor tool for that protocol. For this specific protocol, baud rate is relevant, so serial-monitor has a baudrate configuration parameter, but other pluggable monitor tools (e.g., teensy-monitor) may not have this configuration parameter and may have other configuration parameters serial-monitor does not.

So there is no way to provide a comprehensive list of all configuration parameters in the documentation. However, this is not a problem because the user can ask Arduino CLI to tell them which configuration parameters are available for a given port by using arduino-cli monitor --describe. So the primary way to address this is making it clear that the "configuration" passed via the --config flag is done according to the "settings" returned by the --describe flag. I note that the different terms used in the documentation of these flags does not create a conceptual linkage for the reader.

Even though it is important for the command reference to document the use of the --config flag in a general way that will be applicable to any monitor tool, the reality is that 99% of users will be using a serial port and only need to set the baud rate. So I would also add an item to the FAQ about this specific use case.

Related

• Q: monitor baud rate argument? #1441

[silaswaxter]

@per1234 Okay that makes sense.

I'm not sure what the formatting and content restrictions are for the command reference documentation, but as a user it would've saved me a google search if there was a link to the serial monitor baud rate FAQ section you are talking about adding. Regardless, adding it to the FAQ is a great solution. Thanks!