Skip to content

Commit 3e05773

Browse files
ubidefeoubidefeo
authored
Merge pull request #20 from arduino/README
added README.md
2 parents 5d25583 + 652e08e commit 3e05773

File tree

2 files changed

+274
-5
lines changed

2 files changed

+274
-5
lines changed

‎README.md

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# Arduino pluggable discovery for serial ports
2+
3+
The `dfu-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.
4+
5+
## How to build
6+
7+
Install a recent golang environment and run `go build`. The executable `dfu-discovery` will be produced in your working directory.
8+
9+
## Usage
10+
11+
After startup, the tool waits for commands. The available commands are: `HELLO`, `START`, `STOP`, `QUIT`, `LIST` and `START_SYNC`.
12+
13+
#### HELLO command
14+
15+
The `HELLO` command is used to establish the pluggable discovery protocol between client and discovery.
16+
The format of the command is:
17+
18+
`HELLO <PROTOCOL_VERSION> "<USER_AGENT>"`
19+
20+
for example:
21+
22+
`HELLO 1 "Arduino IDE"`
23+
24+
or:
25+
26+
`HELLO 1 "arduino-cli"`
27+
28+
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).
29+
The response to the command is:
30+
31+
```json
32+
{
33+
"eventType": "hello",
34+
"protocolVersion": 1,
35+
"message": "OK"
36+
}
37+
```
38+
39+
`protocolVersion` is the protocol version that the discovery is going to use in the remainder of the communication.
40+
41+
#### START command
42+
43+
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:
44+
45+
```json
46+
{
47+
"eventType": "start",
48+
"message": "OK"
49+
}
50+
```
51+
52+
#### STOP command
53+
54+
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:
55+
56+
```json
57+
{
58+
"eventType": "stop",
59+
"message": "OK"
60+
}
61+
```
62+
63+
#### QUIT command
64+
65+
The `QUIT` command terminates the discovery. The response to quit is:
66+
67+
```json
68+
{
69+
"eventType": "quit",
70+
"message": "OK"
71+
}
72+
```
73+
74+
after this output the tool quits.
75+
76+
#### LIST command
77+
78+
The `LIST` command returns a list of the currently available serial ports. The format of the response is the following:
79+
80+
```json
81+
{
82+
"eventType": "list",
83+
"ports": [
84+
{
85+
"address": "0-1",
86+
"label": "0-1",
87+
"properties": {
88+
"pid": "0x0399",
89+
"vid": "0x2341",
90+
"serialNumber": "321315255931323671D633314B572C41"
91+
},
92+
"hardwareId": "321315255931323671D633314B572C41",
93+
"protocol": "dfu",
94+
"protocolLabel": "USB DFU"
95+
}
96+
]
97+
}
98+
```
99+
100+
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`.
101+
102+
The list command is a one-shot command, if you need continuous monitoring of ports you should use `START_SYNC` command.
103+
104+
#### START_SYNC command
105+
106+
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.
107+
The immediate response to the command is:
108+
109+
```json
110+
{
111+
"eventType": "start_sync",
112+
"message": "OK"
113+
}
114+
```
115+
116+
after that the discovery enters the "events" mode.
117+
118+
The `add` events looks like the following:
119+
120+
```json
121+
{
122+
"eventType": "add",
123+
"port": {
124+
"address": "0-1",
125+
"label": "0-1",
126+
"protocol": "dfu",
127+
"protocolLabel": "USB DFU",
128+
"properties": {
129+
"pid": "0399",
130+
"serial": "321315255931323671D633314B572C41",
131+
"vid": "2341"
132+
},
133+
"hardwareId": "321315255931323671D633314B572C41"
134+
}
135+
```
136+
137+
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.
138+
139+
The `remove` event looks like this:
140+
141+
```json
142+
{
143+
"eventType": "remove",
144+
"port": {
145+
"address": "0-1",
146+
"label": "0-1",
147+
"protocol": "dfu",
148+
"protocolLabel": "USB DFU",
149+
"properties": {
150+
"pid": "0399",
151+
"serial": "321315255931323671D633314B572C41",
152+
"vid": "2341"
153+
},
154+
"hardwareId": "321315255931323671D633314B572C41"
155+
}
156+
}
157+
```
158+
159+
in this case only the `address` and `protocol` fields are reported.
160+
161+
### Example of usage
162+
163+
A possible transcript of the discovery usage:
164+
165+
```bash
166+
$ ./serial-discovery
167+
HELLO 1 "arduino-cli"
168+
{
169+
"eventType": "hello",
170+
"protocolVersion": 1,
171+
"message": "OK"
172+
}
173+
START
174+
{
175+
"eventType": "start",
176+
"message": "OK"
177+
}
178+
LIST
179+
{
180+
"eventType": "list",
181+
"ports": [
182+
{
183+
"address": "0-1",
184+
"label": "0-1",
185+
"protocol": "dfu",
186+
"protocolLabel": "USB DFU",
187+
"properties": {
188+
"pid": "0399",
189+
"serial": "321315255931323671D633314B572C41",
190+
"vid": "2341"
191+
},
192+
"hardwareId": "321315255931323671D633314B572C41"
193+
}
194+
]
195+
}
196+
START_SYNC
197+
{
198+
"eventType": "start_sync",
199+
"message": "OK"
200+
}
201+
{
202+
"eventType": "list",
203+
"ports": [
204+
{
205+
"address": "0-1",
206+
"label": "0-1",
207+
"protocol": "dfu",
208+
"protocolLabel": "USB DFU",
209+
"properties": {
210+
"pid": "0369",
211+
"serial": "321315255931323671D633314B572C41",
212+
"vid": "2341"
213+
},
214+
"hardwareId": "321315255931323671D633314B572C41"
215+
}
216+
]
217+
}
218+
{
219+
"eventType": "remove",
220+
"port": {
221+
"address": "0-1",
222+
"label": "0-1",
223+
"protocol": "dfu",
224+
"protocolLabel": "USB DFU",
225+
"properties": {
226+
"pid": "0399",
227+
"serial": "321315255931323671D633314B572C41",
228+
"vid": "2341"
229+
},
230+
"hardwareId": "321315255931323671D633314B572C41"
231+
}
232+
}
233+
{
234+
"eventType": "list",
235+
"ports": [
236+
{
237+
"address": "0-1",
238+
"label": "0-1",
239+
"protocol": "dfu",
240+
"protocolLabel": "USB DFU",
241+
"properties": {
242+
"pid": "0369",
243+
"serial": "321315255931323671D633314B572C41",
244+
"vid": "2341"
245+
},
246+
"hardwareId": "321315255931323671D633314B572C41"
247+
}
248+
]
249+
}
250+
QUIT
251+
{
252+
"eventType": "quit",
253+
"message": "OK"
254+
}
255+
$
256+
```
257+
258+
## Security
259+
260+
If you think you found a vulnerability or other security-related bug in this project, please read our
261+
[security policy](https://github.com/arduino/serial-discovery/security/policy) and report the bug to our Security Team 🛡️
262+
Thank you!
263+
264+
e-mail contact: [email protected]
265+
266+
## License
267+
268+
Copyright (c) 2018 ARDUINO SA (www.arduino.cc)
269+
270+
The software is released under the GNU General Public License, which covers the main body
271+
of the serial-discovery code. The terms of this license can be found at:
272+
https://www.gnu.org/licenses/gpl-3.0.en.html
273+
274+
See [LICENSE.txt](https://github.com/arduino/serial-discovery/blob/master/LICENSE.txt) for details.

‎compile_mac_m1.sh

Lines changed: 0 additions & 5 deletions
This file was deleted.

0 commit comments

Comments
 (0)