Skip to content

Commit 0c1edf8

Browse files
umbynoscmaglie
umbynos
authored and
cmaglie
committed
rewrite the dummy-monitor/README.md
1 parent d34b12a commit 0c1edf8

File tree

1 file changed

+147
-75
lines changed

1 file changed

+147
-75
lines changed

‎dummy-monitor/README.md

+147-75
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
1-
# Arduino pluggable discovery reference implementation
1+
# Arduino pluggable monitor reference implementation
22

3-
The `dummy-discovery` tool is a command line program that interacts via stdio. It accepts commands as plain ASCII strings terminated with LF `\n` and sends response as JSON.
4-
The "communication ports" returned by the tool are fake, this discovery is intenteded only for educational and testing purposes.
3+
The `dummy-monitor` tool is a command line program that interacts via stdio. It accepts commands as plain ASCII strings terminated with LF `\n` and sends response as JSON.
4+
The "communication ports" returned by the tool are fake, this monitor is intenteded only for educational and testing purposes.
55

66
## How to build
77

8-
Install a recent go environment and run `go build`. The executable `dummy-discovery` will be produced in your working directory.
8+
Install a recent go environment and run `go build`. The executable `dummy-monitor` will be produced in your working directory.
99

1010
## Usage
1111

12-
After startup, the tool waits for commands. The available commands are: `HELLO`, `START`, `STOP`, `QUIT`, `LIST` and `START_SYNC`.
12+
After startup, the tool will just stay idle waiting for commands. The available commands are: HELLO, DESCRIBE, CONFIGURE, OPEN, CLOSE and QUIT.
1313

1414
#### HELLO command
1515

16-
The `HELLO` command is used to establish the pluggable discovery protocol between client and discovery.
16+
The `HELLO` command is used to establish the pluggable monitor protocol between client and monitor.
1717
The format of the command is:
1818

1919
`HELLO <PROTOCOL_VERSION> "<USER_AGENT>"`
@@ -37,118 +37,190 @@ The response to the command is:
3737
}
3838
```
3939

40-
`protocolVersion` is the protocol version that the discovery is going to use in the remainder of the communication.
40+
`protocolVersion` is the protocol version that the monitor is going to use in the remainder of the communication.
4141

42-
#### START command
42+
#### DESCRIBE command
4343

44-
The `START` starts the internal subroutines of the discovery that looks for ports. This command must be called before `LIST` or `START_SYNC`. The response to the start command is:
44+
The `DESCRIBE` command returns a description of the communication port. The description will have metadata about the port configuration, and which parameters are available:
4545

4646
```json
4747
{
48-
"eventType": "start",
49-
"message": "OK"
48+
"event": "describe",
49+
"message": "ok",
50+
"port_description": {
51+
"protocol": "serial",
52+
"configuration_parameters": {
53+
"baudrate": {
54+
"label": "Baudrate",
55+
"type": "enum",
56+
"values": [
57+
"300", "600", "750", "1200", "2400", "4800", "9600",
58+
"19200", "38400", "57600", "115200", "230400", "460800",
59+
"500000", "921600", "1000000", "2000000"
60+
],
61+
"selected": "9600"
62+
},
63+
"parity": {
64+
"label": "Parity",
65+
"type": "enum",
66+
"values": [ "N", "E", "O", "M", "S" ],
67+
"selected": "N"
68+
},
69+
"bits": {
70+
"label": "Data bits",
71+
"type": "enum",
72+
"values": [ "5", "6", "7", "8", "9" ],
73+
"selected": "8"
74+
},
75+
"stop_bits": {
76+
"label": "Stop bits",
77+
"type": "enum",
78+
"values": [ "1", "1.5", "2" ],
79+
"selected": "1"
80+
}
81+
}
82+
}
5083
}
5184
```
5285

53-
#### STOP command
86+
Each parameter has a unique name (`baudrate`, `parity`, etc...), a `type` (in this case only enum but more types will be added in the future), and the `selected` value for each parameter.
5487

55-
The `STOP` command stops the discovery internal subroutines and free some resources. This command should be called if the client wants to pause the discovery for a while. The response to the stop command is:
88+
The parameter name can not contain spaces, and the allowed characters in the name are alphanumerics, underscore `_`, dot `.`, and dash `-`.
5689

57-
```json
90+
The `enum` types must have a list of possible `values`.
91+
92+
The client/IDE may expose these configuration values to the user via a config file or a GUI, in this case the `label` field may be used for a user readable description of the parameter.
93+
94+
#### CONFIGURE command
95+
96+
The `CONFIGURE` command sets configuration parameters for the communication port. The parameters can be changed one at a time and the syntax is:
97+
98+
`CONFIGURE <PARAMETER_NAME> <VALUE>`
99+
100+
The response to the command is:
101+
102+
```JSON
58103
{
59-
"eventType": "stop",
60-
"message": "OK"
104+
"event": "configure",
105+
"message": "ok",
61106
}
62107
```
63108

64-
#### QUIT command
65-
66-
The `QUIT` command terminates the discovery. The response to quit is:
109+
or if there is an error:
67110

68-
```json
111+
```JSON
69112
{
70-
"eventType": "quit",
71-
"message": "OK"
113+
"event": "configure",
114+
"error": true,
115+
"message": "invalid value for parameter baudrate: 123456"
72116
}
73117
```
74118

75-
after this output the tool quits.
119+
The currently selected parameters may be obtained using the `DESCRIBE` command.
76120

77-
#### LIST command
121+
#### OPEN command
78122

79-
The `LIST` command returns a list of the currently available serial ports. The format of the response is the following:
123+
The `OPEN` command opens a communication with the board, the data exchanged with the board will be transferred to the Client/IDE via TCP/IP.
80124

81-
```json
125+
The Client/IDE must first TCP-Listen to a randomly selected port and send it to the monitor tool as part of the OPEN command. The syntax of the OPEN command is:
126+
127+
`OPEN <CLIENT_IP_ADDRESS> <BOARD_PORT>`
128+
129+
For example, let's suppose that the Client/IDE wants to communicate with the serial port `/dev/ttyACM0` then the sequence of actions to perform will be the following:
130+
131+
1. the Client/IDE must first listen to a random TCP port (let's suppose it chose `32123`)
132+
1. the Client/IDE sends the command `OPEN 127.0.0.1:32123 /dev/ttyACM0` to the monitor tool
133+
1. the monitor tool opens `/dev/ttyACM0`
134+
1. the monitor tool connects via TCP/IP to `127.0.0.1:32123` and start streaming data back and forth
135+
136+
The answer to the `OPEN` command is:
137+
138+
```JSON
82139
{
83-
"eventType": "list",
84-
"ports": [
85-
{
86-
"address": "1",
87-
"label": "Dummy upload port",
88-
"protocol": "dummy",
89-
"protocolLabel": "Dummy protocol",
90-
"properties": {
91-
"mac": "73622384782",
92-
"pid": "0x0041",
93-
"vid": "0x2341"
94-
}
95-
}
96-
]
140+
"event": "open",
141+
"message": "ok"
142+
}
143+
```
144+
145+
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:
146+
147+
```JSON
148+
{
149+
"event": "open",
150+
"error": true,
151+
"message": "unknown port /dev/ttyACM23"
97152
}
98153
```
99154

100-
#### START_SYNC command
155+
The board port will be opened using the parameters previously set through the `CONFIGURE` command.
101156

102-
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.
103-
The immediate response to the command is:
157+
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. In this case an asynchronous `port_closed` message must be generated from the monitor tool:
104158

105-
```json
159+
```JSON
106160
{
107-
"eventType": "start_sync",
108-
"message": "OK"
161+
"event": "port_closed",
162+
"message": "serial port disappeared!"
109163
}
110164
```
111165

112-
after that the discovery enters in "events" mode.
166+
or
113167

114-
The `add` events looks like the following:
168+
```JSON
169+
{
170+
"event": "port_closed",
171+
"message": "lost TCP/IP connection with the client!"
172+
}
173+
```
115174

116-
```json
175+
#### CLOSE command
117176

118-
"eventType": "add",
119-
"port": {
120-
"address": "4",
121-
"label": "Dummy upload port",
122-
"protocol": "dummy",
123-
"protocolLabel": "Dummy protocol",
124-
"properties": {
125-
"mac": "294489539128",
126-
"pid": "0x0041",
127-
"vid": "0x2341"
128-
}
129-
}
177+
The `CLOSE` command will close the currently opened port and close the TCP/IP connection used to communicate with the Client/IDE. The answer to the command is:
178+
179+
```JSON
180+
{
181+
"event": "close",
182+
"message": "ok"
130183
}
131184
```
132185

133-
it basically gather the same information as the `list` event but for a single port. After calling `START_SYNC` a bunch of `add` events may be generated in sequence to report all the ports available at the moment of the start.
186+
or in case of error
134187

135-
The `remove` event looks like this:
188+
```JSON
189+
{
190+
"event": "close",
191+
"error": true,
192+
"message": "port already closed"
193+
}
194+
```
136195

137-
```json
196+
#### QUIT command
197+
198+
The `QUIT` command terminates the monitor. The response to `QUIT` is:
199+
200+
```JSON
138201
{
139-
"eventType": "remove",
140-
"port": {
141-
"address": "4",
142-
"protocol": "dummy"
143-
}
202+
"eventType": "quit",
203+
"message": "OK"
144204
}
145205
```
146206

147-
in this case only the `address` and `protocol` fields are reported.
207+
after this output the monitor exits. This command is supposed to always succeed.
148208

149-
### Example of usage
209+
#### Invalid commands
150210

151-
A possible transcript of the discovery usage:
211+
If the client sends an invalid or malformed command, the monitor should answer with:
212+
213+
```JSON
214+
{
215+
"eventType": "command_error",
216+
"error": true,
217+
"message": "Unknown command XXXX"
218+
}
219+
```
220+
fis
221+
### Example of usage
222+
<!-- TODO -->
223+
A possible transcript of the monitor usage:
152224

153225
```
154226
HELLO 1 "arduino-cli"
@@ -249,7 +321,7 @@ $
249321
## Security
250322

251323
If you think you found a vulnerability or other security-related bug in this project, please read our
252-
[security policy](https://github.com/arduino/pluggable-discovery-protocol-handler/security/policy) and report the bug to our Security Team 🛡️
324+
[security policy](https://github.com/arduino/pluggable-monitor-protocol-handler/security/policy) and report the bug to our Security Team 🛡️
253325
Thank you!
254326

255327
e-mail contact: [email protected]
@@ -259,7 +331,7 @@ e-mail contact: [email protected]
259331
Copyright (c) 2021 ARDUINO SA (www.arduino.cc)
260332

261333
The software is released under the GNU General Public License, which covers the main body
262-
of the serial-discovery code. The terms of this license can be found at:
334+
of the serial-monitor code. The terms of this license can be found at:
263335
https://www.gnu.org/licenses/gpl-3.0.en.html
264336

265-
See [LICENSE.txt](https://github.com/arduino/pluggable-discovery-protocol-handler/blob/master/LICENSE.txt) for details.
337+
See [LICENSE.txt](https://github.com/arduino/pluggable-monitor-protocol-handler/blob/master/LICENSE.txt) for details.

0 commit comments

Comments
 (0)