added readme to dummy-discovery

Author: cmaglie

dummy-discovery/README.md

@@ -0,0 +1,265 @@
+# Arduino pluggable discovery reference implementation
+
+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.
+The "communication ports" returned by the tool are fake, this discovery is intenteded only for educational and testing purposes.
+
+## How to build
+
+Install a recent go enviroment and run `go build`. The executable `dummy-discovery` will be produced in your working directory.
+
+## Usage
+
+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
+
+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:
+
+```json
+{
+  "eventType": "start",
+  "message": "OK"
+}
+```
+
+#### STOP command
+
+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:
+
+```json
+{
+  "eventType": "stop",
+  "message": "OK"
+}
+```
+
+#### QUIT command
+
+The `QUIT` command terminates the discovery. The response to quit is:
+
+```json
+{
+  "eventType": "quit",
+  "message": "OK"
+}
+```
+
+after this output the tool quits.
+
+#### LIST command
+
+The `LIST` command returns a list of the currently available serial ports. The format of the response is the following:
+
+```json
+{
+  "eventType": "list",
+  "ports": [
+    {
+      "address": "1",
+      "label": "Dummy upload port",
+      "protocol": "dummy",
+      "protocolLabel": "Dummy protocol",
+      "properties": {
+        "mac": "73622384782",
+        "pid": "0x0041",
+        "vid": "0x2341"
+      }
+    }
+  ]
+}
+```
+
+#### 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:
+
+```json
+
+  "eventType": "add",
+  "port": {
+    "address": "4",
+    "label": "Dummy upload port",
+    "protocol": "dummy",
+    "protocolLabel": "Dummy protocol",
+    "properties": {
+      "mac": "294489539128",
+      "pid": "0x0041",
+      "vid": "0x2341"
+    }
+  }
+}
+```
+
+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.
+
+The `remove` event looks like this:
+
+```json
+{
+  "eventType": "remove",
+  "port": {
+    "address": "4",
+    "protocol": "dummy"
+  }
+}
+```
+
+in this case only the `address` and `protocol` fields are reported.
+
+### Example of usage
+
+A possible transcript of the discovery usage:
+
+```
+HELLO 1 "arduino-cli"
+{
+  "eventType": "hello",
+  "message": "OK",
+  "protocolVersion": 1
+}
+START
+{
+  "eventType": "start",
+  "message": "OK"
+}
+LIST
+{
+  "eventType": "list",
+  "ports": [
+    {
+      "address": "1",
+      "label": "Dummy upload port",
+      "protocol": "dummy",
+      "protocolLabel": "Dummy protocol",
+      "properties": {
+        "mac": "73622384782",
+        "pid": "0x0041",
+        "vid": "0x2341"
+      }
+    }
+  ]
+}
+STOP
+{
+  "eventType": "stop",
+  "message": "OK"
+}
+START_SYNC
+{
+  "eventType": "start_sync",
+  "message": "OK"
+}
+{
+  "eventType": "add",
+  "port": {
+    "address": "2",
+    "label": "Dummy upload port",
+    "protocol": "dummy",
+    "protocolLabel": "Dummy protocol",
+    "properties": {
+      "mac": "147244769564",
+      "pid": "0x0041",
+      "vid": "0x2341"
+    }
+  }
+}
+{
+  "eventType": "add",
+  "port": {
+    "address": "3",
+    "label": "Dummy upload port",
+    "protocol": "dummy",
+    "protocolLabel": "Dummy protocol",
+    "properties": {
+      "mac": "220867154346",
+      "pid": "0x0041",
+      "vid": "0x2341"
+    }
+  }
+}
+{
+  "eventType": "add",
+  "port": {
+    "address": "4",
+    "label": "Dummy upload port",
+    "protocol": "dummy",
+    "protocolLabel": "Dummy protocol",
+    "properties": {
+      "mac": "294489539128",
+      "pid": "0x0041",
+      "vid": "0x2341"
+    }
+  }
+}
+{
+  "eventType": "remove",
+  "port": {
+    "address": "4",
+    "protocol": "dummy"
+  }
+}
+QUIT
+{
+  "eventType": "quit",
+  "message": "OK"
+}
+$
+```
+
+## Security
+
+If you think you found a vulnerability or other security-related bug in this project, please read our
+[security policy](https://github.com/arduino/serial-discovery/security/policy) and report the bug to our Security Team 🛡️
+Thank you!
+
+e-mail contact: security@arduino.cc
+
+## License
+
+Copyright (c) 2021 ARDUINO SA (www.arduino.cc)
+
+The software is released under the GNU General Public License, which covers the main body
+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.