Skip to content

Commit

Permalink
Merge pull request #6 from arduino/protocol_v1
Browse files Browse the repository at this point in the history 
Implement Pluggable Discovery protocol v1
  • Loading branch information
@cmaglie
cmaglie committed Jun 8, 2021
2 parents d21bd88 + 497dea0 commit 9d079c1
Show file tree
Hide file tree
Showing 6 changed files with 226 additions and 111 deletions.
124 changes: 84 additions & 40 deletions README.md
View file
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 client 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

0 comments on commit 9d079c1

Please sign in to comment.