Merge pull request #6 from arduino/protocol_v1

Implement Pluggable Discovery protocol v1

Author: cmaglie

README.md

@@ -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
 
@@ -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)"
@@ -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:
 
@@ -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)"
@@ -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
@@ -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.