Skip to content

Implement Pluggable Discovery protocol v1 #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jun 8, 2021
Merged

Implement Pluggable Discovery protocol v1 #6

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
adaf607
Factored json output and added Error field
cmaglie Jun 3, 2021
0b87821
Implemented HELLO cmd
cmaglie Jun 3, 2021
51184d9
Implemented ERROR protocol
cmaglie Jun 3, 2021
d70b1fb
Port does not have identification properties anymore
cmaglie Jun 3, 2021
f1fd9f3
Report protocol on 'remove' event
cmaglie Jun 3, 2021
87c2119
Updated readme
cmaglie Jun 3, 2021
3b72f45
Update README.md
cmaglie Jun 4, 2021
e45938d
Change ProtocolVersion field to int
cmaglie Jun 8, 2021
497dea0
Removed commented code
cmaglie Jun 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 84 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,35 @@ Install a recent go enviroment (>=13.0) and run `go build`. The executable `seri

## Usage

After startup, the tool waits for commands. The available commands are: `START`, `STOP`, `QUIT`, `LIST` and `START_SYNC`.
After startup, the tool waits for commands. The available commands are: `HELLO`, `START`, `STOP`, `QUIT`, `LIST` and `START_SYNC`.

#### HELLO command

The `HELLO` command is used to establish the pluggable discovery protocol between client and discovery.
The format of the command is:

`HELLO <PROTOCOL_VERSION> "<USER_AGENT>"`

for example:

`HELLO 1 "Arduino IDE"`

or:

`HELLO 1 "arduino-cli"`

in this case the protocol version requested by the clien is `1` (at the moment of writing there were no other revisions of the protocol).
The response to the command is:

```json
{
"eventType": "hello",
"protocolVersion": "1",
"message": "OK"
}
```

`protocolVersion` is the protocol version that the discovery is going to use in the remainder of the communication.

#### START command

Expand Down Expand Up @@ -56,14 +84,10 @@ The `LIST` command returns a list of the currently available serial ports. The f
{
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"prefs": {
"productId": "0x804e",
"serialNumber": "EBEABFD6514D32364E202020FF10181E",
"vendorId": "0x2341"
},
"identificationPrefs": {
"properties": {
"pid": "0x804e",
"vid": "0x2341"
"vid": "0x2341",
"serialNumber": "EBEABFD6514D32364E202020FF10181E"
},
"protocol": "serial",
"protocolLabel": "Serial Port (USB)"
Expand All @@ -72,13 +96,23 @@ The `LIST` command returns a list of the currently available serial ports. The f
}
```

The `ports` field contains a list of the available serial ports. If the serial port comes from an USB serial converter the USB VID/PID and USB SERIAL NUMBER properties are also reported inside `prefs`. Inside the `identificationPrefs` instead we have only the properties useful for product identification (in this case USB VID/PID only that may be useful to identify the board)
The `ports` field contains a list of the available serial ports. If the serial port comes from an USB serial converter the USB VID/PID and USB SERIAL NUMBER properties are also reported inside `properties`.

The list command is a one-shot command, if you need continuos monitoring of ports you should use `START_SYNC` command.

#### START_SYNC command

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.
The immediate response to the command is:

```json
{
"eventType": "start_sync",
"message": "OK"
}
```

after that the discovery enters in "events" mode.

The `add` events looks like the following:

Expand All @@ -88,14 +122,10 @@ The `add` events looks like the following:
"port": {
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"prefs": {
"productId": "0x804e",
"serialNumber": "EBEABFD6514D32364E202020FF10181E",
"vendorId": "0x2341"
},
"identificationPrefs": {
"properties": {
"pid": "0x804e",
"vid": "0x2341"
"vid": "0x2341",
"serialNumber": "EBEABFD6514D32364E202020FF10181E"
},
"protocol": "serial",
"protocolLabel": "Serial Port (USB)"
Expand All @@ -111,65 +141,80 @@ The `remove` event looks like this:
{
"eventType": "remove",
"port": {
"address": "/dev/ttyACM0"
"address": "/dev/ttyACM0",
"protocol": "serial"
}
}
```

in this case only the `address` field is reported.
in this case only the `address` and `protocol` fields are reported.

### Example of usage

A possible transcript of the discovery usage:

```
$ ./serial-discovery
$ ./serial-discovery
START
{
"eventType": "start",
"message": "OK"
}
LIST
{
"eventType": "list",
"ports": [
{
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"protocol": "serial",
"protocolLabel": "Serial Port (USB)",
"properties": {
"pid": "0x004e",
"serialNumber": "EBEABFD6514D32364E202020FF10181E",
"vid": "0x2341"
}
}
]
}
START_SYNC
{
"eventType": "start_sync",
"message": "OK"
}
{ <--- this event has been immediately sent
"eventType": "add",
"port": {
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"prefs": {
"productId": "0x804e",
"protocol": "serial",
"protocolLabel": "Serial Port (USB)",
"properties": {
"pid": "0x004e",
"serialNumber": "EBEABFD6514D32364E202020FF10181E",
"vendorId": "0x2341"
},
"identificationPrefs": {
"pid": "0x804e",
"vid": "0x2341"
},
"protocol": "serial",
"protocolLabel": "Serial Port (USB)"
}
}
}
{ <--- the board has been disconnected here
"eventType": "remove",
"port": {
"address": "/dev/ttyACM0"
"address": "/dev/ttyACM0",
"protocol": "serial"
}
}
{ <--- the board has been connected again
"eventType": "add",
"port": {
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"prefs": {
"productId": "0x804e",
"protocol": "serial",
"protocolLabel": "Serial Port (USB)",
"properties": {
"pid": "0x004e",
"serialNumber": "EBEABFD6514D32364E202020FF10181E",
"vendorId": "0x2341"
},
"identificationPrefs": {
"pid": "0x804e",
"vid": "0x2341"
},
"protocol": "serial",
"protocolLabel": "Serial Port (USB)"
}
}
}
QUIT
Expand All @@ -196,5 +241,4 @@ The software is released under the GNU General Public License, which covers the
of the serial-discovery code. The terms of this license can be found at:
https://www.gnu.org/licenses/gpl-3.0.en.html

See [LICENSE.txt](<https://github.com/arduino/serial-discovery/blob/master/LICENSE.txt>) for details.

See [LICENSE.txt](https://github.com/arduino/serial-discovery/blob/master/LICENSE.txt) for details.
Loading