The serial-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.
Install a recent golang environment and run go build
. The executable serial-discovery
will be produced in your working directory.
After startup, the tool waits for commands. The available commands are: HELLO
, START
, STOP
, QUIT
, LIST
and START_SYNC
.
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.
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"
}
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"
}
The QUIT
command terminates the discovery. The response to quit is:
{
"eventType": "quit",
"message": "OK"
}
after this output the tool quits.
The LIST
command returns a list of the currently available serial ports. The format of the response is the following:
{
"eventType": "list",
"ports": [
{
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"properties": {
"pid": "0x804e",
"vid": "0x2341",
"serialNumber": "EBEABFD6514D32364E202020FF10181E"
},
"hardwareId": "EBEABFD6514D32364E202020FF10181E",
"protocol": "serial",
"protocolLabel": "Serial Port (USB)"
}
]
}
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 continuous monitoring of ports you should use 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 the "events" mode.
The add
events looks like the following:
{
"eventType": "add",
"port": {
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"properties": {
"pid": "0x804e",
"vid": "0x2341",
"serialNumber": "EBEABFD6514D32364E202020FF10181E"
},
"hardwareId": "EBEABFD6514D32364E202020FF10181E",
"protocol": "serial",
"protocolLabel": "Serial Port (USB)"
}
}
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": "/dev/ttyACM0",
"protocol": "serial"
}
}
in this case only the address
and protocol
fields are reported.
A possible transcript of the discovery usage:
$ ./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"
},
"hardwareId": "EBEABFD6514D32364E202020FF10181E"
}
]
}
START_SYNC
{
"eventType": "start_sync",
"message": "OK"
}
{ <--- this event has been immediately sent
"eventType": "add",
"port": {
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"protocol": "serial",
"protocolLabel": "Serial Port (USB)",
"properties": {
"pid": "0x004e",
"serialNumber": "EBEABFD6514D32364E202020FF10181E",
"vid": "0x2341"
},
"hardwareId": "EBEABFD6514D32364E202020FF10181E"
}
}
{ <--- the board has been disconnected here
"eventType": "remove",
"port": {
"address": "/dev/ttyACM0",
"protocol": "serial"
}
}
{ <--- the board has been connected again
"eventType": "add",
"port": {
"address": "/dev/ttyACM0",
"label": "/dev/ttyACM0",
"protocol": "serial",
"protocolLabel": "Serial Port (USB)",
"properties": {
"pid": "0x004e",
"serialNumber": "EBEABFD6514D32364E202020FF10181E",
"vid": "0x2341"
},
"hardwareId": "EBEABFD6514D32364E202020FF10181E"
}
}
QUIT
{
"eventType": "quit",
"message": "OK"
}
$
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
Copyright (c) 2018 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.