Pluggable monitor specification

Monitor tools are a special kind of tool used to let the user communicate with the supported boards. A platform developer can create their own tools following the specification below. These tools must be in the form of command line executables that can be launched as a subprocess.

They will communicate to the parent process via stdin/stdout, in particular a monitor tool 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 open and control communication ports for a specific protocol as specified in this document. The actual I/O data stream from the communication port will be transferred to the parent process through a separate channel via TCP/IP.

Pluggable monitor API via stdin/stdout

All the commands listed in this specification must be implemented in the monitor tool.

After startup, the tool will just stay idle waiting for commands. The available commands are:

HELLO

DESCRIBE

CONFIGURE

OPEN

CLOSE

QUIT

After each command the client always expects a response from the monitor. The monitor must not introduce any delay and must respond to all commands as fast as possible.

HELLO command

HELLO

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. It must not contain double-quotes (

  "

  ).

some examples:

• HELLO 1 "Arduino IDE 1.8.13"

• HELLO 1 "arduino-cli 1.2.3"

the response to the command is:

1{
2  "eventType": "hello",
3  "protocolVersion": 1,
4  "message": "OK"
5}

The

protocolVersion

• if the client/IDE supports the same or a more recent version of the protocol than the monitor tool, then the client/IDE should go into a compatibility mode and use the protocol level supported by the monitor tool.
• if the monitor tool supports a more recent version of the protocol than the client/IDE, then the monitor tool 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 monitor tool cannot go into compatibility mode, it must 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 monitor tool or produce an error/warning.

DESCRIBE command

The

DESCRIBE

1{
2  "eventType": "describe",
3  "message": "ok",
4  "port_description": {
5    "protocol": "serial",
6    "configuration_parameters": {
7      "baudrate": {
8        "label": "Baudrate",
9        "type": "enum",
10        "value": [
11          "300", "600", "750", "1200", "2400", "4800", "9600",
12          "19200", "38400", "57600", "115200", "230400", "460800",
13          "500000", "921600", "1000000", "2000000"
14        ],
15        "selected": "9600"
16      },
17      "parity": {
18        "label": "Parity",
19        "type": "enum",
20        "value": [ "N", "E", "O", "M", "S" ],
21        "selected": "N"
22      },
23      "bits": {
24        "label": "Data bits",
25        "type": "enum",
26        "value": [ "5", "6", "7", "8", "9" ],
27        "selected": "8"
28      },
29      "stop_bits": {
30        "label": "Stop bits",
31        "type": "enum",
32        "value": [ "1", "1.5", "2" ],
33        "selected": "1"
34      }
35    }
36  }
37}

The field

protocol

configuration_parameters

Each parameter has a unique name (

baudrate

parity

type

enum

selected

The parameter name can not contain spaces, the allowed characters are alphanumerics, underscore

_

.

-

The

enum

value

The client/IDE may expose these configuration values to the user via a config file or a GUI, in this case the

label

CONFIGURE command

The

CONFIGURE

CONFIGURE <PARAMETER_NAME> <VALUE>

The response to the command is:

1{
2  "eventType": "configure",
3  "message": "ok"
4}

or if there is an error:

1{
2  "eventType": "configure",
3  "error": true,
4  "message": "invalid value for parameter baudrate: 123456"
5}

The currently selected parameters or their default value may be obtained using the

DESCRIBE

OPEN command

The

OPEN

The Client/IDE must first TCP-Listen to a randomly selected TCP port and send the address to connect it to the monitor tool as part of the

OPEN

OPEN

OPEN <CLIENT_TCPIP_ADDRESS> <BOARD_PORT>

For example, let's suppose that the Client/IDE wants to communicate with the serial port

/dev/ttyACM0

serial-monitor

1. the Client/IDE must first listen to a random TCP port (let's suppose it chose

   32123

   )
2. the Client/IDE runs the

   serial-monitor

   tool and initializes it with the

   HELLO

   command
3. the Client/IDE sends the command

   OPEN 127.0.0.1:32123 /dev/ttyACM0

   to the monitor tool
4. the monitor tool opens

   /dev/ttyACM0

5. the monitor tool connects via TCP/IP to

   127.0.0.1:32123

   and starts streaming data back and forth

The answer to the

OPEN

1{
2  "eventType": "open",
3  "message": "ok"
4}

If the monitor tool cannot communicate with the board, or if the tool can not connect back to the TCP port, or if any other error condition happens:

1{
2  "eventType": "open",
3  "error": true,
4  "message": "unknown port /dev/ttyACM23"
5}

The board port will be opened using the parameters previously set through the

CONFIGURE

Once the port is opened, it may be unexpectedly closed at any time due to hardware failure, or because the Client/IDE closes the TCP/IP connection, etc. In this case an asynchronous

port_closed

1{
2  "eventType": "port_closed",
3  "message": "serial port disappeared!"
4}

or

1{
2  "eventType": "port_closed",
3  "message": "lost TCP/IP connection with the client!"
4}

CLOSE command

The

CLOSE

1{
2  "eventType": "close",
3  "message": "ok"
4}

or in case of error

1{
2  "eventType": "close",
3  "error": true,
4  "message": "port already closed"
5}

QUIT command

The

QUIT

QUIT

1{
2  "eventType": "quit",
3  "message": "OK"
4}

after this output the monitor exits. This command must always succeed.

Invalid commands

If the client sends an invalid or malformed command, the monitor should answer with:

1{
2  "eventType": "command_error",
3  "error": true,
4  "message": "Unknown command XXXX"
5}