Skip to content

Commit 956ab37

Browse files
cmagliecmaglie
authored
Merge branch 'master' into go-cross
2 parents 6e26418 + 3e05773 commit 956ab37

File tree

1 file changed

+261
-2
lines changed

1 file changed

+261
-2
lines changed

‎README.md

Lines changed: 261 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,269 @@ The platform to build can be one of:
2020

2121
The executable `dfu-discovery` will be produced inside `dist/dfu-discovery-<platform>/dfu-discovery`.
2222

23+
## Usage
24+
25+
After startup, the tool waits for commands. The available commands are: `HELLO`, `START`, `STOP`, `QUIT`, `LIST` and `START_SYNC`.
26+
27+
#### HELLO command
28+
29+
The `HELLO` command is used to establish the pluggable discovery protocol between client and discovery.
30+
The format of the command is:
31+
32+
`HELLO <PROTOCOL_VERSION> "<USER_AGENT>"`
33+
34+
for example:
35+
36+
`HELLO 1 "Arduino IDE"`
37+
38+
or:
39+
40+
`HELLO 1 "arduino-cli"`
41+
42+
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).
43+
The response to the command is:
44+
45+
```json
46+
{
47+
"eventType": "hello",
48+
"protocolVersion": 1,
49+
"message": "OK"
50+
}
51+
```
52+
53+
`protocolVersion` is the protocol version that the discovery is going to use in the remainder of the communication.
54+
55+
#### START command
56+
57+
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:
58+
59+
```json
60+
{
61+
"eventType": "start",
62+
"message": "OK"
63+
}
64+
```
65+
66+
#### STOP command
67+
68+
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:
69+
70+
```json
71+
{
72+
"eventType": "stop",
73+
"message": "OK"
74+
}
75+
```
76+
77+
#### QUIT command
78+
79+
The `QUIT` command terminates the discovery. The response to quit is:
80+
81+
```json
82+
{
83+
"eventType": "quit",
84+
"message": "OK"
85+
}
86+
```
87+
88+
after this output the tool quits.
89+
90+
#### LIST command
91+
92+
The `LIST` command returns a list of the currently available dfu ports. The format of the response is the following:
93+
94+
```json
95+
{
96+
"eventType": "list",
97+
"ports": [
98+
{
99+
"address": "0-1",
100+
"label": "0-1",
101+
"properties": {
102+
"pid": "0x0399",
103+
"vid": "0x2341",
104+
"serialNumber": "321315255931323671D633314B572C41"
105+
},
106+
"hardwareId": "321315255931323671D633314B572C41",
107+
"protocol": "dfu",
108+
"protocolLabel": "USB DFU"
109+
}
110+
]
111+
}
112+
```
113+
114+
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`.
115+
116+
The list command is a one-shot command, if you need continuous monitoring of ports you should use `START_SYNC` command.
117+
118+
#### START_SYNC command
119+
120+
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.
121+
The immediate response to the command is:
122+
123+
```json
124+
{
125+
"eventType": "start_sync",
126+
"message": "OK"
127+
}
128+
```
129+
130+
after that the discovery enters the "events" mode.
131+
132+
The `add` events looks like the following:
133+
134+
```json
135+
{
136+
"eventType": "add",
137+
"port": {
138+
"address": "0-1",
139+
"label": "0-1",
140+
"protocol": "dfu",
141+
"protocolLabel": "USB DFU",
142+
"properties": {
143+
"pid": "0399",
144+
"serial": "321315255931323671D633314B572C41",
145+
"vid": "2341"
146+
},
147+
"hardwareId": "321315255931323671D633314B572C41"
148+
}
149+
```
150+
151+
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.
152+
153+
The `remove` event looks like this:
154+
155+
```json
156+
{
157+
"eventType": "remove",
158+
"port": {
159+
"address": "0-1",
160+
"label": "0-1",
161+
"protocol": "dfu",
162+
"protocolLabel": "USB DFU",
163+
"properties": {
164+
"pid": "0399",
165+
"serial": "321315255931323671D633314B572C41",
166+
"vid": "2341"
167+
},
168+
"hardwareId": "321315255931323671D633314B572C41"
169+
}
170+
}
171+
```
172+
173+
in this case only the `address` and `protocol` fields are reported.
174+
175+
### Example of usage
176+
177+
A possible transcript of the discovery usage:
178+
179+
```bash
180+
$ ./serial-discovery
181+
HELLO 1 "arduino-cli"
182+
{
183+
"eventType": "hello",
184+
"protocolVersion": 1,
185+
"message": "OK"
186+
}
187+
START
188+
{
189+
"eventType": "start",
190+
"message": "OK"
191+
}
192+
LIST
193+
{
194+
"eventType": "list",
195+
"ports": [
196+
{
197+
"address": "0-1",
198+
"label": "0-1",
199+
"protocol": "dfu",
200+
"protocolLabel": "USB DFU",
201+
"properties": {
202+
"pid": "0399",
203+
"serial": "321315255931323671D633314B572C41",
204+
"vid": "2341"
205+
},
206+
"hardwareId": "321315255931323671D633314B572C41"
207+
}
208+
]
209+
}
210+
START_SYNC
211+
{
212+
"eventType": "start_sync",
213+
"message": "OK"
214+
}
215+
{
216+
"eventType": "list",
217+
"ports": [
218+
{
219+
"address": "0-1",
220+
"label": "0-1",
221+
"protocol": "dfu",
222+
"protocolLabel": "USB DFU",
223+
"properties": {
224+
"pid": "0369",
225+
"serial": "321315255931323671D633314B572C41",
226+
"vid": "2341"
227+
},
228+
"hardwareId": "321315255931323671D633314B572C41"
229+
}
230+
]
231+
}
232+
{
233+
"eventType": "remove",
234+
"port": {
235+
"address": "0-1",
236+
"label": "0-1",
237+
"protocol": "dfu",
238+
"protocolLabel": "USB DFU",
239+
"properties": {
240+
"pid": "0399",
241+
"serial": "321315255931323671D633314B572C41",
242+
"vid": "2341"
243+
},
244+
"hardwareId": "321315255931323671D633314B572C41"
245+
}
246+
}
247+
{
248+
"eventType": "list",
249+
"ports": [
250+
{
251+
"address": "0-1",
252+
"label": "0-1",
253+
"protocol": "dfu",
254+
"protocolLabel": "USB DFU",
255+
"properties": {
256+
"pid": "0369",
257+
"serial": "321315255931323671D633314B572C41",
258+
"vid": "2341"
259+
},
260+
"hardwareId": "321315255931323671D633314B572C41"
261+
}
262+
]
263+
}
264+
QUIT
265+
{
266+
"eventType": "quit",
267+
"message": "OK"
268+
}
269+
$
270+
```
271+
23272
## Security
24273

25274
If you think you found a vulnerability or other security-related bug in this project, please read our
26-
[security policy](https://github.com/arduino/mdns-discovery/security/policy) and report the bug to our Security Team 🛡️
275+
[security policy](https://github.com/arduino/dfu-discovery/security/policy) and report the bug to our Security Team 🛡️
27276
Thank you!
28277

29-
e-mail contact: [email protected]
278+
e-mail contact: [email protected]
279+
280+
## License
281+
282+
Copyright (c) 2018 ARDUINO SA (www.arduino.cc)
283+
284+
The software is released under the GNU General Public License, which covers the main body
285+
of the dfu-discovery code. The terms of this license can be found at:
286+
https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
287+
288+
See [LICENSE.txt](https://github.com/arduino/dfu-discovery/blob/master/LICENSE.txt) for details.

0 commit comments

Comments
 (0)