Skip to content

Commit f60f4a9

Browse files
cmagliecmaglie
authored
Merge pull request #1 from arduino/extract_as_lib
Made this repo a library
2 parents f2d7d51 + fc56748 commit f60f4a9

File tree

10 files changed

+731
-644
lines changed

10 files changed

+731
-644
lines changed

‎.github/workflows/test.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,4 @@ jobs:
2626
go-version: "1.16"
2727

2828
- name: Build
29-
run: task build
29+
run: task build-dummy-discovery

‎README.md

+1-244
Original file line numberDiff line numberDiff line change
@@ -1,250 +1,7 @@
1-
# Arduino pluggabe discovery reference implementation
2-
3-
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.
1+
# A golang library to handle the Arduino pluggable-discovery communication protocol.
42

53
## How to build
64

7-
Install a recent go enviroment and run `go build`. The executable `dummy-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": "1",
86-
"label": "Dummy upload port",
87-
"protocol": "dummy",
88-
"protocolLabel": "Dummy protocol",
89-
"properties": {
90-
"mac": "73622384782",
91-
"pid": "0x0041",
92-
"vid": "0x2341"
93-
}
94-
}
95-
]
96-
}
97-
```
98-
99-
#### START_SYNC command
100-
101-
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.
102-
The immediate response to the command is:
103-
104-
```json
105-
{
106-
"eventType": "start_sync",
107-
"message": "OK"
108-
}
109-
```
110-
111-
after that the discovery enters in "events" mode.
112-
113-
The `add` events looks like the following:
114-
115-
```json
116-
117-
"eventType": "add",
118-
"port": {
119-
"address": "4",
120-
"label": "Dummy upload port",
121-
"protocol": "dummy",
122-
"protocolLabel": "Dummy protocol",
123-
"properties": {
124-
"mac": "294489539128",
125-
"pid": "0x0041",
126-
"vid": "0x2341"
127-
}
128-
}
129-
}
130-
```
131-
132-
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.
133-
134-
The `remove` event looks like this:
135-
136-
```json
137-
{
138-
"eventType": "remove",
139-
"port": {
140-
"address": "4",
141-
"protocol": "dummy"
142-
}
143-
}
144-
```
145-
146-
in this case only the `address` and `protocol` fields are reported.
147-
148-
### Example of usage
149-
150-
A possible transcript of the discovery usage:
151-
152-
```
153-
HELLO 1 "arduino-cli"
154-
{
155-
"eventType": "hello",
156-
"message": "OK",
157-
"protocolVersion": 1
158-
}
159-
START
160-
{
161-
"eventType": "start",
162-
"message": "OK"
163-
}
164-
LIST
165-
{
166-
"eventType": "list",
167-
"ports": [
168-
{
169-
"address": "1",
170-
"label": "Dummy upload port",
171-
"protocol": "dummy",
172-
"protocolLabel": "Dummy protocol",
173-
"properties": {
174-
"mac": "73622384782",
175-
"pid": "0x0041",
176-
"vid": "0x2341"
177-
}
178-
}
179-
]
180-
}
181-
STOP
182-
{
183-
"eventType": "stop",
184-
"message": "OK"
185-
}
186-
START_SYNC
187-
{
188-
"eventType": "start_sync",
189-
"message": "OK"
190-
}
191-
{
192-
"eventType": "add",
193-
"port": {
194-
"address": "2",
195-
"label": "Dummy upload port",
196-
"protocol": "dummy",
197-
"protocolLabel": "Dummy protocol",
198-
"properties": {
199-
"mac": "147244769564",
200-
"pid": "0x0041",
201-
"vid": "0x2341"
202-
}
203-
}
204-
}
205-
{
206-
"eventType": "add",
207-
"port": {
208-
"address": "3",
209-
"label": "Dummy upload port",
210-
"protocol": "dummy",
211-
"protocolLabel": "Dummy protocol",
212-
"properties": {
213-
"mac": "220867154346",
214-
"pid": "0x0041",
215-
"vid": "0x2341"
216-
}
217-
}
218-
}
219-
{
220-
"eventType": "add",
221-
"port": {
222-
"address": "4",
223-
"label": "Dummy upload port",
224-
"protocol": "dummy",
225-
"protocolLabel": "Dummy protocol",
226-
"properties": {
227-
"mac": "294489539128",
228-
"pid": "0x0041",
229-
"vid": "0x2341"
230-
}
231-
}
232-
}
233-
{
234-
"eventType": "remove",
235-
"port": {
236-
"address": "4",
237-
"protocol": "dummy"
238-
}
239-
}
240-
QUIT
241-
{
242-
"eventType": "quit",
243-
"message": "OK"
244-
}
245-
$
246-
```
247-
2485
## Security
2496

2507
If you think you found a vulnerability or other security-related bug in this project, please read our

‎Taskfile.yml

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
version: "3"
22

33
tasks:
4-
build:
5-
desc: Build the project
4+
build-dummy-discovery:
5+
desc: Build the dummy-discovery client example
66
cmds:
7-
- go build -v -ldflags '{{.LDFLAGS}}'
7+
- go build -o dist/dummy-discovery -v -ldflags '{{.LDFLAGS}}' ./dummy-discovery
88

99
vars:
1010
PROJECT_NAME: "dummy-discovery"
@@ -14,5 +14,5 @@ vars:
1414
TIMESTAMP:
1515
sh: echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
1616
LDFLAGS: >
17-
-X github.com/arduino/dummy-discovery/version.Tag={{.VERSION}}
18-
-X github.com/arduino/dummy-discovery/version.Timestamp={{.TIMESTAMP}}
17+
-X github.com/arduino/pluggable-discovery-protocol-handler/dummy-discovery/args.Tag={{.VERSION}}
18+
-X github.com/arduino/pluggable-discovery-protocol-handler/dummy-discovery/args.Timestamp={{.TIMESTAMP}}

0 commit comments

Comments
 (0)