dummy-discovery

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 environment 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:

{
  "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:

{
  "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:

{
  "eventType": "stop",
  "message": "OK"
}

QUIT command

The QUIT command terminates the discovery. The response to quit is:

{
  "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:

{
  "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:

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

after that the discovery enters in "events" mode.

The add events looks like the following:

  "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:

{
  "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 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 for details.